Merge pull request #737 from processing/p5-sound-versions

Only use old p5.sound on 1.x

Author: davepagurek

public/reference/data.json

@@ -2,14 +2,54 @@
 title: getLevel
 module: p5.sound
 submodule: p5.sound
-file: src/Amplitude.js
-description: Get the current amplitude value of a sound.
-line: 63
+file: lib/addons/p5.sound.js
+description: |
+  <p>Returns a single Amplitude reading at the moment it is called.
+  For continuous readings, run in the draw loop.</p>
+line: 3209
 isConstructor: false
 itemtype: method
+example:
+  - |-
+
+    <div><code>
+    function preload(){
+      sound = loadSound('/assets/beat.mp3');
+    }
+
+    function setup() {
+      let cnv = createCanvas(100, 100);
+      cnv.mouseClicked(toggleSound);
+      amplitude = new p5.Amplitude();
+    }
+
+    function draw() {
+      background(220, 150);
+      textAlign(CENTER);
+      text('tap to play', width/2, 20);
+
+      let level = amplitude.getLevel();
+      let size = map(level, 0, 1, 0, 200);
+      ellipse(width/2, height/2, size, size);
+    }
+
+    function toggleSound(){
+      if (sound.isPlaying()) {
+        sound.stop();
+      } else {
+        sound.play();
+      }
+    }
+    </code></div>
 class: p5.Amplitude
+params:
+  - name: channel
+    description: |
+      <p>Optionally return only channel 0 (left) or 1 (right)</p>
+    type: Number
+    optional: true
 return:
-  description: Amplitude level (volume) of a sound.
+  description: Amplitude as a number between 0.0 and 1.0
   type: Number
 chainable: false
 ---

src/content/reference/en/p5.Amplitude/getLevel.mdx

@@ -2,16 +2,63 @@
 title: setInput
 module: p5.sound
 submodule: p5.sound
-file: src/Amplitude.js
-description: Connect an audio source to the amplitude object.
-line: 53
+file: lib/addons/p5.sound.js
+description: |
+  <p>Connects to the p5sound instance (main output) by default.
+  Optionally, you can pass in a specific source (i.e. a soundfile).</p>
+line: 3117
 isConstructor: false
 itemtype: method
+example:
+  - |-
+
+    <div><code>
+    function preload(){
+      sound1 = loadSound('/assets/beat.mp3');
+      sound2 = loadSound('/assets/drum.mp3');
+    }
+    function setup(){
+      cnv = createCanvas(100, 100);
+      cnv.mouseClicked(toggleSound);
+
+      amplitude = new p5.Amplitude();
+      amplitude.setInput(sound2);
+    }
+
+    function draw() {
+      background(220);
+      text('tap to play', 20, 20);
+
+      let level = amplitude.getLevel();
+      let size = map(level, 0, 1, 0, 200);
+      ellipse(width/2, height/2, size, size);
+    }
+
+    function toggleSound(){
+      if (sound1.isPlaying() && sound2.isPlaying()) {
+        sound1.stop();
+        sound2.stop();
+      } else {
+        sound1.play();
+        sound2.play();
+      }
+    }
+    </code></div>
 class: p5.Amplitude
 params:
-  - name: input
-    description: '- An object that has audio output.'
-    type: Object
+  - name: snd
+    description: |
+      <p>set the sound source
+                                           (optional, defaults to
+                                           main output)</p>
+    type: SoundObject|undefined
+    optional: true
+  - name: smoothing
+    description: |
+      <p>a range between 0.0 and 1.0
+                                            to smooth amplitude readings</p>
+    type: Number|undefined
+    optional: true
 chainable: false
 ---
 

src/content/reference/en/p5.Amplitude/setInput.mdx

@@ -2,17 +2,18 @@
 title: smooth
 module: p5.sound
 submodule: p5.sound
-file: src/Amplitude.js
-description: Get the current amplitude value of a sound.
-line: 73
+file: lib/addons/p5.sound.js
+description: |
+  <p>Smooth Amplitude analysis by averaging with the last analysis
+  frame. Off by default.</p>
+line: 3293
 isConstructor: false
 itemtype: method
 class: p5.Amplitude
 params:
-  - name: Smooth
-    description: >-
-      Amplitude analysis by averaging with the last analysis frame. Off by
-      default.
+  - name: set
+    description: |
+      <p>smoothing from 0.0 <= 1</p>
     type: Number
 chainable: false
 ---

src/content/reference/en/p5.Amplitude/smooth.mdx

@@ -2,16 +2,23 @@
 title: amp
 module: p5.sound
 submodule: p5.sound
-file: src/AudioIn.js
-description: Set amplitude (volume) of a mic input between 0 and 1.0.
-line: 81
+file: lib/addons/p5.sound.js
+description: |
+  <p>Set amplitude (volume) of a mic input between 0 and 1.0. <br/></p>
+line: 6257
 isConstructor: false
 itemtype: method
 class: p5.AudioIn
 params:
-  - name: amplitudeAmount
-    description: An amplitude value between 0 and 1.
+  - name: vol
+    description: |
+      <p>between 0 and 1.0</p>
     type: Number
+  - name: time
+    description: |
+      <p>ramp time (optional)</p>
+    type: Number
+    optional: true
 chainable: false
 ---
 

src/content/reference/en/p5.AudioIn/amp.mdx

@@ -2,12 +2,35 @@
 title: start
 module: p5.sound
 submodule: p5.sound
-file: src/AudioIn.js
-description: Start the audio input.
-line: 56
+file: lib/addons/p5.sound.js
+description: |
+  <p>Start processing audio input. This enables the use of other
+  AudioIn methods like getLevel(). Note that by default, AudioIn
+  is not connected to p5.sound's output. So you won't hear
+  anything unless you use the connect() method.<br/></p>
+  <p>Certain browsers limit access to the user's microphone. For example,
+  Chrome only allows access from localhost and over https. For this reason,
+  you may want to include an errorCallback—a function that is called in case
+  the browser won't provide mic access.</p>
+line: 6114
 isConstructor: false
 itemtype: method
 class: p5.AudioIn
+params:
+  - name: successCallback
+    description: |
+      <p>Name of a function to call on
+                                        success.</p>
+    type: Function
+    optional: true
+  - name: errorCallback
+    description: |
+      <p>Name of a function to call if
+                                        there was an error. For example,
+                                        some browsers do not support
+                                        getUserMedia.</p>
+    type: Function
+    optional: true
 chainable: false
 ---
 

src/content/reference/en/p5.AudioIn/start.mdx

@@ -2,9 +2,11 @@
 title: stop
 module: p5.sound
 submodule: p5.sound
-file: src/AudioIn.js
-description: Stop the audio input.
-line: 72
+file: lib/addons/p5.sound.js
+description: |
+  <p>Turn the AudioIn off. If the AudioIn is stopped, it cannot getLevel().
+  If re-starting, the user may be prompted for permission access.</p>
+line: 6171
 isConstructor: false
 itemtype: method
 class: p5.AudioIn