From 9760dd0242099588897ef37846e8f7e846ccb86f Mon Sep 17 00:00:00 2001
From: Jason Sigal <jason.sigal@gmail.com>
Date: Mon, 6 Jan 2020 00:28:37 -0500
Subject: [PATCH] update inline examples (#388) (#403)

- Update inline examples to start audio context on a user gesture, either by playing a sound (soundFile.play() / oscillator.start()) or by explicitly calling userStartAudio() #388

- Use let in examples, instead of var, but not const, as discussed in this issue where it was decided to use let exclusively in examples: processing/p5.js#3877

- Update styles for consistency with other p5 inline examples

Some examples use soundFile.play() or oscillator.start() rather than a potentially redundant call to userStartAudio(). It might be worth that redundant call, because the difference between methods that call "start" on a WebAudio node (thus enabling audio on a user gesture) and those that do not is pretty obfuscated...
---
 fragments/before.frag |  58 ++++----
 src/amplitude.js      |  83 ++++++-----
 src/audiocontext.js   |  60 ++++----
 src/audioin.js        |  55 ++++++--
 src/delay.js          |  41 +++---
 src/envelope.js       | 313 ++++++++++++++++++++----------------------
 src/eq.js             |  53 ++++---
 src/fft.js            | 111 ++++++++-------
 src/filter.js         |  96 ++++++-------
 src/gain.js           | 110 +++++++--------
 src/helpers.js        |  43 ++++--
 src/looper.js         |  70 ++++------
 src/master.js         |  15 +-
 src/monosynth.js      |  84 +++++++-----
 src/oscillator.js     |  85 +++++++-----
 src/polysynth.js      |  95 +++++++------
 src/pulse.js          |  21 ++-
 src/reverb.js         |  59 ++++++--
 src/signal.js         |  22 ++-
 src/soundLoop.js      |  53 ++++---
 src/soundRecorder.js  |  21 ++-
 src/soundfile.js      | 231 ++++++++++++++++++-------------
 22 files changed, 1010 insertions(+), 769 deletions(-)

diff --git a/fragments/before.frag b/fragments/before.frag
index cafe1bb7..e85faada 100644
--- a/fragments/before.frag
+++ b/fragments/before.frag
@@ -1,40 +1,46 @@
 /**
- *  p5.sound extends p5 with <a href="http://caniuse.com/audio-api"
+ *  <p>p5.sound extends p5 with <a href="http://caniuse.com/audio-api"
  *  target="_blank">Web Audio</a> functionality including audio input,
  *  playback, analysis and synthesis.
- *  <br/><br/>
- *  <a href="#/p5.SoundFile"><b>p5.SoundFile</b></a>: Load and play sound files.<br/>
- *  <a href="#/p5.Amplitude"><b>p5.Amplitude</b></a>: Get the current volume of a sound.<br/>
- *  <a href="#/p5.AudioIn"><b>p5.AudioIn</b></a>: Get sound from an input source, typically
- *    a computer microphone.<br/>
- *  <a href="#/p5.FFT"><b>p5.FFT</b></a>: Analyze the frequency of sound. Returns
- *    results from the frequency spectrum or time domain (waveform).<br/>
- *  <a href="#/p5.Oscillator"><b>p5.Oscillator</b></a>: Generate Sine,
+ *  </p>
+ *  <ul>
+ *  <li><a href="#/p5.SoundFile"><b>p5.SoundFile</b></a>: Load and play sound files.</li>
+ *  <li><a href="#/p5.Amplitude"><b>p5.Amplitude</b></a>: Get the current volume of a sound.</li>
+ *  <li><a href="#/p5.AudioIn"><b>p5.AudioIn</b></a>: Get sound from an input source, typically
+ *    a computer microphone.</li>
+ *  <li><a href="#/p5.FFT"><b>p5.FFT</b></a>: Analyze the frequency of sound. Returns
+ *    results from the frequency spectrum or time domain (waveform).</li>
+ *  <li><a href="#/p5.Oscillator"><b>p5.Oscillator</b></a>: Generate Sine,
  *    Triangle, Square and Sawtooth waveforms. Base class of
- *    <a href="#/p5.Noise">p5.Noise</a> and <a href="#/p5.Pulse">p5.Pulse</a>.
- *    <br/>
- *  <a href="#/p5.Envelope"><b>p5.Envelope</b></a>: An Envelope is a series
+ *    <li><a href="#/p5.Noise">p5.Noise</a> and <a href="#/p5.Pulse">p5.Pulse</a>.
+ *    </li>
+ *  <li>
+ *    <a href="#/p5.MonoSynth">p5.MonoSynth</a> and <a href="#/p5.PolySynth">p5.PolySynth</a>: Play musical notes
+ *  </li>
+ *  <li><a href="#/p5.Envelope"><b>p5.Envelope</b></a>: An Envelope is a series
  *    of fades over time. Often used to control an object's
  *    output gain level as an "ADSR Envelope" (Attack, Decay,
- *    Sustain, Release). Can also modulate other parameters.<br/>
- *  <a href="#/p5.Delay"><b>p5.Delay</b></a>: A delay effect with
- *    parameters for feedback, delayTime, and lowpass filter.<br/>
- *  <a href="#/p5.Filter"><b>p5.Filter</b></a>: Filter the frequency range of a
+ *    Sustain, Release). Can also modulate other parameters.</li>
+ *  <li><a href="#/p5.Delay"><b>p5.Delay</b></a>: A delay effect with
+ *    parameters for feedback, delayTime, and lowpass filter.</li>
+ *  <li><a href="#/p5.Filter"><b>p5.Filter</b></a>: Filter the frequency range of a
  *    sound.
- *  <br/>
- *  <a href="#/p5.Reverb"><b>p5.Reverb</b></a>: Add reverb to a sound by specifying
- *    duration and decay. <br/>
- *  <b><a href="#/p5.Convolver">p5.Convolver</a>:</b> Extends
+ *  </li>
+ *  <li><a href="#/p5.Reverb"><b>p5.Reverb</b></a>: Add reverb to a sound by specifying
+ *    duration and decay. </li>
+ *  <b><li><a href="#/p5.Convolver">p5.Convolver</a>:</b> Extends
  *  <a href="#/p5.Reverb">p5.Reverb</a> to simulate the sound of real
- *    physical spaces through convolution.<br/>
- *  <b><a href="#/p5.SoundRecorder">p5.SoundRecorder</a></b>: Record sound for playback
+ *    physical spaces through convolution.</li>
+ *  <b><li><a href="#/p5.SoundRecorder">p5.SoundRecorder</a></b>: Record sound for playback
  *    / save the .wav file.
- *  <b><a href="#/p5.Phrase">p5.Phrase</a></b>, <b><a href="#/p5.Part">p5.Part</a></b> and
+ *  <b><li><a href="#/p5.SoundLoop">p5.SoundLoop</a>, <a href="#/p5.Phrase">p5.Phrase</a></b>, <b><a href="#/p5.Part">p5.Part</a></b> and
  *  <b><a href="#/p5.Score">p5.Score</a></b>: Compose musical sequences.
- *  <br/><br/>
- *  p5.sound is on <a href="https://github.com/therewasaguy/p5.sound/">GitHub</a>.
+ *  </li>
+ *  <li><a href="#/p5/userStartAudio">userStartAudio</a>: Enable audio in a
+ *  browser- and user-friendly way.</a>
+ *  <p>p5.sound is on <a href="https://github.com/therewasaguy/p5.sound/">GitHub</a>.
  *  Download the latest version
- *  <a href="https://github.com/therewasaguy/p5.sound/blob/master/lib/p5.sound.js">here</a>.
+ *  <a href="https://github.com/therewasaguy/p5.sound/blob/master/lib/p5.sound.js">here</a>.</p>
  *
  *  @module p5.sound
  *  @submodule p5.sound
diff --git a/src/amplitude.js b/src/amplitude.js
index f59516ef..051bbed4 100644
--- a/src/amplitude.js
+++ b/src/amplitude.js
@@ -17,32 +17,34 @@ define(function (require) {
    *                             amplitude readings (defaults to 0)
    *  @example
    *  <div><code>
-   *  var sound, amplitude, cnv;
+   *  let sound, amplitude;
    *
    *  function preload(){
    *    sound = loadSound('assets/beat.mp3');
    *  }
    *  function setup() {
-   *    cnv = createCanvas(100,100);
+   *    let cnv = createCanvas(100,100);
+   *    cnv.mouseClicked(toggleSound);
    *    amplitude = new p5.Amplitude();
-   *
-   *    // start / stop the sound when canvas is clicked
-   *    cnv.mouseClicked(function() {
-   *      if (sound.isPlaying() ){
-   *        sound.stop();
-   *      } else {
-   *        sound.play();
-   *      }
-   *    });
    *  }
+   *
    *  function draw() {
-   *    background(0);
-   *    fill(255);
-   *    var level = amplitude.getLevel();
-   *    var size = map(level, 0, 1, 0, 200);
+   *    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 (sound.isPlaying() ){
+   *      sound.stop();
+   *    } else {
+   *      sound.play();
+   *    }
+   *  }
+   *
    *  </code></div>
    */
   p5.Amplitude = function(smoothing) {
@@ -117,21 +119,30 @@ define(function (require) {
    *    sound2 = loadSound('assets/drum.mp3');
    *  }
    *  function setup(){
+   *    cnv = createCanvas(100, 100);
+   *    cnv.mouseClicked(toggleSound);
+   *
    *    amplitude = new p5.Amplitude();
-   *    sound1.play();
-   *    sound2.play();
    *    amplitude.setInput(sound2);
    *  }
+   *
    *  function draw() {
-   *    background(0);
-   *    fill(255);
-   *    var level = amplitude.getLevel();
-   *    var size = map(level, 0, 1, 0, 200);
+   *    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 mouseClicked(){
-   *    sound1.stop();
-   *    sound2.stop();
+   *
+   *  function toggleSound(){
+   *    if (sound1.isPlaying() && sound2.isPlaying()) {
+   *      sound1.stop();
+   *      sound2.stop();
+   *    } else {
+   *      sound1.play();
+   *      sound2.play();
+   *    }
    *  }
    *  </code></div>
    */
@@ -197,19 +208,29 @@ define(function (require) {
    *  function preload(){
    *    sound = loadSound('assets/beat.mp3');
    *  }
+   *
    *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mouseClicked(toggleSound);
    *    amplitude = new p5.Amplitude();
-   *    sound.play();
    *  }
+   *
    *  function draw() {
-   *    background(0);
-   *    fill(255);
-   *    var level = amplitude.getLevel();
-   *    var size = map(level, 0, 1, 0, 200);
+   *    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 mouseClicked(){
-   *    sound.stop();
+   *
+   *  function toggleSound(){
+   *    if (sound.isPlaying()) {
+   *      sound.stop();
+   *    } else {
+   *      sound.play();
+   *    }
    *  }
    *  </code></div>
    */
diff --git a/src/audiocontext.js b/src/audiocontext.js
index 6cfeb300..7f0ef7e2 100644
--- a/src/audiocontext.js
+++ b/src/audiocontext.js
@@ -19,6 +19,7 @@ define(['startaudiocontext', 'Tone/core/Context', 'Tone/core/Tone'], function (S
    * <p>Some browsers require users to startAudioContext
    * with a user gesture, such as touchStarted in the example below.</p>
    *
+   * @for p5
    * @method getAudioContext
    * @return {Object}    AudioContext for this sketch
    * @example
@@ -50,44 +51,55 @@ define(['startaudiocontext', 'Tone/core/Context', 'Tone/core/Tone'], function (S
 
 
   /**
-   *  <p>It is a good practice to give users control over starting audio playback.
-   *  This practice is enforced by Google Chrome's autoplay policy as of r70
-   *  (<a href="https://goo.gl/7K7WLu">info</a>), iOS Safari, and other browsers.
-   *  </p>
+   *  <p>It is not only a good practice to give users control over starting
+   *  audio. This policy is enforced by many web browsers, including iOS and
+   *  <a href="https://goo.gl/7K7WLu" title="Google Chrome's autoplay
+   *  policy">Google Chrome</a>, which create the Web Audio API's
+   *  <a href="https://developer.mozilla.org/en-US/docs/Web/API/AudioContext"
+   *  title="Audio Context @ MDN">Audio Context</a>
+   *  in a suspended state.</p>
    *
-   *  <p>
-   *  userStartAudio() starts the <a href="https://developer.mozilla.org/en-US/docs/Web/API/AudioContext"
-   *  target="_blank" title="Audio Context @ MDN">Audio Context</a> on a user gesture. It utilizes
-   *  the <a href="https://github.com/tambien/StartAudioContext">StartAudioContext</a> library by
-   *  Yotam Mann (MIT Licence, 2016). Read more at https://github.com/tambien/StartAudioContext.
-   *  </p>
+   *  <p>In these browser-specific policies, sound will not play until a user
+   *  interaction event (i.e. <code>mousePressed()</code>) explicitly resumes
+   *  the AudioContext, or starts an audio node. This can be accomplished by
+   *  calling <code>start()</code> on a <code>p5.Oscillator</code>,
+   *  <code> play()</code> on a <code>p5.SoundFile</code>, or simply
+   *  <code>userStartAudio()</code>.</p>
    *
-   *  <p>Starting the audio context on a user gesture can be as simple as <code>userStartAudio()</code>.
-   *  Optional parameters let you decide on a specific element that will start the audio context,
-   *  and/or call a function once the audio context is started.</p>
+   *  <p><code>userStartAudio()</code> starts the AudioContext on a user
+   *  gesture. The default behavior will enable audio on any
+   *  mouseUp or touchEnd event. It can also be placed in a specific
+   *  interaction function, such as <code>mousePressed()</code> as in the
+   *  example below. This method utilizes
+   *  <a href="https://github.com/tambien/StartAudioContext">StartAudioContext
+   *  </a>, a library by Yotam Mann (MIT Licence, 2016).</p>
    *  @param  {Element|Array}   [element(s)] This argument can be an Element,
    *                                Selector String, NodeList, p5.Element,
    *                                jQuery Element, or an Array of any of those.
-   *  @param  {Function} [callback] Callback to invoke when the AudioContext has started
-   *  @return {Promise}            Returns a Promise which is resolved when
+   *  @param  {Function} [callback] Callback to invoke when the AudioContext
+   *                                has started
+   *  @return {Promise}            Returns a Promise that resolves when
    *                                       the AudioContext state is 'running'
    *  @method userStartAudio
    *  @for p5
    *  @example
    *  <div><code>
    *  function setup() {
-   *    var myDiv = createDiv('click to start audio');
-   *    myDiv.position(0, 0);
+   *    // mimics the autoplay policy
+   *    getAudioContext().suspend();
    *
-   *    var mySynth = new p5.MonoSynth();
+   *    let mySynth = new p5.MonoSynth();
    *
-   *    // This won't play until the context has started
+   *    // This won't play until the context has resumed
    *    mySynth.play('A6');
-   *
-   *    // Start the audio context on a click/touch event
-   *    userStartAudio().then(function() {
-   *       myDiv.remove();
-   *     });
+   *  }
+   *  function draw() {
+   *    background(220);
+   *    textAlign(CENTER, CENTER);
+   *    text(getAudioContext().state, width/2, height/2);
+   *  }
+   *  function mousePressed() {
+   *    userStartAudio();
    *  }
    *  </code></div>
    */
diff --git a/src/audioin.js b/src/audioin.js
index d599b799..2f3287da 100644
--- a/src/audioin.js
+++ b/src/audioin.js
@@ -29,15 +29,24 @@ define(function (require) {
    *                                    currently allow microphone access.
    *  @example
    *  <div><code>
-   *  var mic;
-   *  function setup(){
-   *    mic = new p5.AudioIn()
+   *  let mic;
+   *
+   *   function setup(){
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(userStartAudio);
+   *    textAlign(CENTER);
+   *    mic = new p5.AudioIn();
    *    mic.start();
    *  }
+   *
    *  function draw(){
    *    background(0);
+   *    fill(255);
+   *    text('tap to start', width/2, 20);
+   *
    *    micLevel = mic.getLevel();
-   *    ellipse(width/2, constrain(height-micLevel*height*5, 0, height), 10, 10);
+   *    let y = height - micLevel * height;
+   *    ellipse(width/2, y, 10, 10);
    *  }
    *  </code></div>
    */
@@ -267,18 +276,21 @@ define(function (require) {
    *                            to the enumerateDevices() method
    * @example
    *  <div><code>
-   *  var audiograb;
+   *  let audioIn;
    *
    *  function setup(){
-   *    //new audioIn
-   *    audioGrab = new p5.AudioIn();
+   *    text('getting sources...', 0, 20);
+   *    audioIn = new p5.AudioIn();
+   *    audioIn.getSources(gotSources);
+   *  }
    *
-   *    audioGrab.getSources(function(deviceList) {
-   *      //print out the array of available sources
-   *      console.log(deviceList);
+   *  function gotSources(deviceList) {
+   *    if (deviceList.length > 0) {
    *      //set the source to the first item in the deviceList array
-   *      audioGrab.setSource(0);
-   *    });
+   *      audioIn.setSource(0);
+   *      let currentSource = deviceList[audioIn.currentSource];
+   *      text('set source to: ' + currentSource.deviceId, 5, 20, width);
+   *    }
    *  }
    *  </code></div>
    */
@@ -316,6 +328,25 @@ define(function (require) {
    *  @method setSource
    *  @for p5.AudioIn
    *  @param {number} num position of input source in the array
+   *  @example
+   *  <div><code>
+   *  let audioIn;
+   *
+   *  function setup(){
+   *    text('getting sources...', 0, 20);
+   *    audioIn = new p5.AudioIn();
+   *    audioIn.getSources(gotSources);
+   *  }
+   *
+   *  function gotSources(deviceList) {
+   *    if (deviceList.length > 0) {
+   *      //set the source to the first item in the deviceList array
+   *      audioIn.setSource(0);
+   *      let currentSource = deviceList[audioIn.currentSource];
+   *      text('set source to: ' + currentSource.deviceId, 5, 20, width);
+   *    }
+   *  }
+   *  </code></div>
    */
   p5.AudioIn.prototype.setSource = function(num) {
     if (p5sound.inputSources.length > 0 && num < p5sound.inputSources.length) {
diff --git a/src/delay.js b/src/delay.js
index 8d095d48..f367cc92 100644
--- a/src/delay.js
+++ b/src/delay.js
@@ -9,7 +9,7 @@ define(function (require) {
    *  and outputs a delayed version of that sound. The p5.Delay can
    *  produce different effects depending on the delayTime, feedback,
    *  filter, and type. In the example below, a feedback of 0.5 (the
-   *  defaul value) will produce a looping delay that decreases in
+   *  default value) will produce a looping delay that decreases in
    *  volume by 50% each repeat. A filter will cut out the high
    *  frequencies so that the delay does not sound as piercing as the
    *  original source.
@@ -24,37 +24,31 @@ define(function (require) {
    *  @constructor
    *  @example
    *  <div><code>
-   *  var noise, env, delay;
+   *  let osc;
    *
    *  function setup() {
-   *    background(0);
-   *    noStroke();
-   *    fill(255);
+   *    let cnv = createCanvas(100, 100);
+   *    background(220);
    *    textAlign(CENTER);
-   *    text('click to play', width/2, height/2);
-   *
-   *    noise = new p5.Noise('brown');
-   *    noise.amp(0);
-   *    noise.start();
+   *    text('tap to play', width/2, height/2);
    *
+   *    osc = new p5.Oscillator('square');
+   *    osc.amp(0.5);
    *    delay = new p5.Delay();
    *
    *    // delay.process() accepts 4 parameters:
-   *    // source, delayTime, feedback, filter frequency
-   *    // play with these numbers!!
-   *    delay.process(noise, .12, .7, 2300);
+   *    // source, delayTime (in seconds), feedback, filter frequency
+   *    delay.process(osc, 0.12, .7, 2300);
+   *
+   *    cnv.mousePressed(oscStart);
+   *  }
    *
-   *    // play the noise with an envelope,
-   *    // a series of fades ( time / value pairs )
-   *    env = new p5.Envelope(.01, 0.2, .2, .1);
+   *  function oscStart() {
+   *    osc.start();
    *  }
    *
-   *  // mouseClick triggers envelope
-   *  function mouseClicked() {
-   *    // is mouse over canvas?
-   *    if (mouseX > 0 && mouseX < width && mouseY > 0 && mouseY < height) {
-   *      env.play(noise);
-   *    }
+   *  function mouseReleased() {
+   *    osc.stop();
    *  }
    *  </code></div>
    */
@@ -72,6 +66,7 @@ define(function (require) {
      *  <a href="http://www.w3.org/TR/webaudio/#DelayNode">
      *  Web Audio Delay Nodes</a>, one for each stereo channel.
      *
+     *  @for p5.Delay
      *  @property {DelayNode} leftDelay
      */
     this.leftDelay = this.ac.createDelay();
@@ -79,7 +74,7 @@ define(function (require) {
      *  The p5.Delay is built with two
      *  <a href="http://www.w3.org/TR/webaudio/#DelayNode">
      *  Web Audio Delay Nodes</a>, one for each stereo channel.
-     *
+     *  @for p5.Delay
      *  @property {DelayNode} rightDelay
      */
     this.rightDelay = this.ac.createDelay();
diff --git a/src/envelope.js b/src/envelope.js
index d7f805c5..cbc75e7c 100644
--- a/src/envelope.js
+++ b/src/envelope.js
@@ -27,36 +27,28 @@ define(function (require) {
    *  @constructor
    *  @example
    *  <div><code>
-   *  var attackLevel = 1.0;
-   *  var releaseLevel = 0;
+   *  let t1 = 0.1; // attack time in seconds
+   *  let l1 = 0.7; // attack level 0.0 to 1.0
+   *  let t2 = 0.3; // decay time in seconds
+   *  let l2 = 0.1; // decay level  0.0 to 1.0
    *
-   *  var attackTime = 0.001;
-   *  var decayTime = 0.2;
-   *  var susPercent = 0.2;
-   *  var releaseTime = 0.5;
-   *
-   *  var env, triOsc;
+   *  let env;
+   *  let triOsc;
    *
    *  function setup() {
-   *    var cnv = createCanvas(100, 100);
-   *
-   *    textAlign(CENTER);
-   *    text('click to play', width/2, height/2);
-   *
-   *    env = new p5.Envelope();
-   *    env.setADSR(attackTime, decayTime, susPercent, releaseTime);
-   *    env.setRange(attackLevel, releaseLevel);
+   *    let cnv = createCanvas(100, 100);
+   *    background(220);
+   *    text('tap to play', 20, 20);
+   *    cnv.mousePressed(playSound);
    *
+   *    env = new p5.Envelope(t1, l1, t2, l2);
    *    triOsc = new p5.Oscillator('triangle');
-   *    triOsc.amp(env);
-   *    triOsc.start();
-   *    triOsc.freq(220);
-   *
-   *    cnv.mousePressed(playEnv);
    *  }
    *
-   *  function playEnv()  {
-   *    env.play();
+   *  function playSound() {
+   *    // starting the oscillator ensures that audio is enabled.
+   *    triOsc.start();
+   *    env.play(triOsc);
    *  }
    *  </code></div>
    */
@@ -151,36 +143,36 @@ define(function (require) {
    *  @param {Number} releaseLevel  Amplitude
    *  @example
    *  <div><code>
-   *  var t1 = 0.1; // attack time in seconds
-   *  var l1 = 0.7; // attack level 0.0 to 1.0
-   *  var t2 = 0.3; // decay time in seconds
-   *  var l2 = 0.1; // decay level  0.0 to 1.0
-   *  var t3 = 0.2; // sustain time in seconds
-   *  var l3 = 0.5; // sustain level  0.0 to 1.0
-   *  // release level defaults to zero
+   *  let attackTime;
+   *  let l1 = 0.7; // attack level 0.0 to 1.0
+   *  let t2 = 0.3; // decay time in seconds
+   *  let l2 = 0.1; // decay level  0.0 to 1.0
+   *  let l3 = 0.2; // release time in seconds
    *
-   *  var env;
-   *  var triOsc;
+   *  let env, triOsc;
    *
    *  function setup() {
-   *    background(0);
-   *    noStroke();
-   *    fill(255);
-   *    textAlign(CENTER);
-   *    text('click to play', width/2, height/2);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playSound);
    *
-   *    env = new p5.Envelope(t1, l1, t2, l2, t3, l3);
+   *    env = new p5.Envelope();
    *    triOsc = new p5.Oscillator('triangle');
-   *    triOsc.amp(env); // give the env control of the triOsc's amp
-   *    triOsc.start();
+   *  }
+   *
+   *  function draw() {
+   *    background(220);
+   *    text('tap here to play', 5, 20);
+   *
+   *    attackTime = map(mouseX, 0, width, 0.0, 1.0);
+   *    text('attack time: ' + attackTime, 5, height - 20);
    *  }
    *
    *  // mouseClick triggers envelope if over canvas
-   *  function mouseClicked() {
-   *    // is mouse over canvas?
-   *    if (mouseX > 0 && mouseX < width && mouseY > 0 && mouseY < height) {
-   *      env.play(triOsc);
-   *    }
+   *  function playSound() {
+   *    env.set(attackTime, l1, t2, l2, l3);
+   *
+   *    triOsc.start();
+   *    env.play(triOsc);
    *  }
    *  </code></div>
    *
@@ -220,35 +212,36 @@ define(function (require) {
    *  @param {Number} [releaseTime]   Time in seconds from now (defaults to 0)
    *  @example
    *  <div><code>
-   *  var attackLevel = 1.0;
-   *  var releaseLevel = 0;
+   *  let attackLevel = 1.0;
+   *  let releaseLevel = 0;
    *
-   *  var attackTime = 0.001;
-   *  var decayTime = 0.2;
-   *  var susPercent = 0.2;
-   *  var releaseTime = 0.5;
+   *  let attackTime = 0.001;
+   *  let decayTime = 0.2;
+   *  let susPercent = 0.2;
+   *  let releaseTime = 0.5;
    *
-   *  var env, triOsc;
+   *  let env, triOsc;
    *
    *  function setup() {
-   *    var cnv = createCanvas(100, 100);
-   *
-   *    textAlign(CENTER);
-   *    text('click to play', width/2, height/2);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playEnv);
    *
    *    env = new p5.Envelope();
-   *    env.setADSR(attackTime, decayTime, susPercent, releaseTime);
-   *    env.setRange(attackLevel, releaseLevel);
-   *
    *    triOsc = new p5.Oscillator('triangle');
    *    triOsc.amp(env);
-   *    triOsc.start();
    *    triOsc.freq(220);
+   *  }
    *
-   *    cnv.mousePressed(playEnv);
+   *  function draw() {
+   *    background(220);
+   *    text('tap here to play', 5, 20);
+   *    attackTime = map(mouseX, 0, width, 0, 1.0);
+   *    text('attack time: ' + attackTime, 5, height - 40);
    *  }
    *
-   *  function playEnv()  {
+   *  function playEnv() {
+   *    triOsc.start();
+   *    env.setADSR(attackTime, decayTime, susPercent, releaseTime);
    *    env.play();
    *  }
    *  </code></div>
@@ -276,35 +269,36 @@ define(function (require) {
    *  @param {Number} rLevel release level (defaults to 0)
    *  @example
    *  <div><code>
-   *  var attackLevel = 1.0;
-   *  var releaseLevel = 0;
+   *  let attackLevel = 1.0;
+   *  let releaseLevel = 0;
    *
-   *  var attackTime = 0.001;
-   *  var decayTime = 0.2;
-   *  var susPercent = 0.2;
-   *  var releaseTime = 0.5;
+   *  let attackTime = 0.001;
+   *  let decayTime = 0.2;
+   *  let susPercent = 0.2;
+   *  let releaseTime = 0.5;
    *
-   *  var env, triOsc;
+   *  let env, triOsc;
    *
    *  function setup() {
-   *    var cnv = createCanvas(100, 100);
-   *
-   *    textAlign(CENTER);
-   *    text('click to play', width/2, height/2);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playEnv);
    *
    *    env = new p5.Envelope();
-   *    env.setADSR(attackTime, decayTime, susPercent, releaseTime);
-   *    env.setRange(attackLevel, releaseLevel);
-   *
    *    triOsc = new p5.Oscillator('triangle');
    *    triOsc.amp(env);
-   *    triOsc.start();
    *    triOsc.freq(220);
+   *  }
    *
-   *    cnv.mousePressed(playEnv);
+   *  function draw() {
+   *    background(220);
+   *    text('tap here to play', 5, 20);
+   *    attackLevel = map(mouseY, height, 0, 0, 1.0);
+   *    text('attack level: ' + attackLevel, 5, height - 20);
    *  }
    *
-   *  function playEnv()  {
+   *  function playEnv() {
+   *    triOsc.start();
+   *    env.setRange(attackLevel, releaseLevel);
    *    env.play();
    *  }
    *  </code></div>
@@ -401,12 +395,12 @@ define(function (require) {
   };
 
   /**
-   *  Play tells the envelope to start acting on a given input.
+   *  <p>Play tells the envelope to start acting on a given input.
    *  If the input is a p5.sound object (i.e. AudioIn, Oscillator,
    *  SoundFile), then Envelope will control its output volume.
    *  Envelopes can also be used to control any <a href="
    *  http://docs.webplatform.org/wiki/apis/webaudio/AudioParam">
-   *  Web Audio Audio Param.</a>
+   *  Web Audio Audio Param.</a></p>
    *
    *  @method  play
    *  @for p5.Envelope
@@ -416,38 +410,43 @@ define(function (require) {
    *  @param  {Number} [sustainTime] time to sustain before releasing the envelope
    *  @example
    *  <div><code>
-   *  var attackLevel = 1.0;
-   *  var releaseLevel = 0;
+   *  let attackLevel = 1.0;
+   *  let releaseLevel = 0;
    *
-   *  var attackTime = 0.001;
-   *  var decayTime = 0.2;
-   *  var susPercent = 0.2;
-   *  var releaseTime = 0.5;
+   *  let attackTime = 0.001;
+   *  let decayTime = 0.2;
+   *  let susPercent = 0.2;
+   *  let releaseTime = 0.5;
    *
-   *  var env, triOsc;
+   *  let env, triOsc;
    *
    *  function setup() {
-   *    var cnv = createCanvas(100, 100);
-   *
-   *    textAlign(CENTER);
-   *    text('click to play', width/2, height/2);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playEnv);
    *
    *    env = new p5.Envelope();
-   *    env.setADSR(attackTime, decayTime, susPercent, releaseTime);
-   *    env.setRange(attackLevel, releaseLevel);
-   *
    *    triOsc = new p5.Oscillator('triangle');
    *    triOsc.amp(env);
-   *    triOsc.start();
    *    triOsc.freq(220);
+   *    triOsc.start();
+   *  }
    *
-   *    cnv.mousePressed(playEnv);
+   *  function draw() {
+   *    background(220);
+   *    text('tap here to play', 5, 20);
+   *    attackTime = map(mouseX, 0, width, 0, 1.0);
+   *    attackLevel = map(mouseY, height, 0, 0, 1.0);
+   *    text('attack time: ' + attackTime, 5, height - 40);
+   *    text('attack level: ' + attackLevel, 5, height - 20);
    *  }
    *
-   *  function playEnv()  {
-   *    // trigger env on triOsc, 0 seconds from now
-   *    // After decay, sustain for 0.2 seconds before release
-   *    env.play(triOsc, 0, 0.2);
+   *  function playEnv() {
+   *    // ensure that audio is enabled
+   *    userStartAudio();
+   *
+   *    env.setADSR(attackTime, decayTime, susPercent, releaseTime);
+   *    env.setRange(attackLevel, releaseLevel);
+   *    env.play();
    *  }
    *  </code></div>
    */
@@ -481,48 +480,43 @@ define(function (require) {
    *  @param  {Number} secondsFromNow time from now (in seconds)
    *  @example
    *  <div><code>
-   *
-   *  var attackLevel = 1.0;
-   *  var releaseLevel = 0;
-   *
-   *  var attackTime = 0.001;
-   *  var decayTime = 0.3;
-   *  var susPercent = 0.4;
-   *  var releaseTime = 0.5;
-   *
-   *  var env, triOsc;
+   *  let attackTime = 0.001;
+   *  let decayTime = 0.2;
+   *  let susPercent = 0.3;
+   *  let releaseTime = 0.4;
+   *  let env, triOsc;
    *
    *  function setup() {
-   *    var cnv = createCanvas(100, 100);
-   *    background(200);
+   *    let cnv = createCanvas(100, 100);
+   *    background(220);
    *    textAlign(CENTER);
-   *    text('click to play', width/2, height/2);
+   *    textSize(10);
+   *    text('tap to triggerAttack', width/2, height/2);
    *
    *    env = new p5.Envelope();
    *    env.setADSR(attackTime, decayTime, susPercent, releaseTime);
-   *    env.setRange(attackLevel, releaseLevel);
-   *
+   *    env.setRange(1.0, 0.0);
    *    triOsc = new p5.Oscillator('triangle');
-   *    triOsc.amp(env);
-   *    triOsc.start();
    *    triOsc.freq(220);
    *
    *    cnv.mousePressed(envAttack);
    *  }
    *
    *  function envAttack()  {
-   *    console.log('trigger attack');
-   *    env.triggerAttack();
+   *    background(0, 255, 255);
+   *    text('release to release', width/2, height/2);
+   *
+   *    // ensures audio is enabled. See also: `userStartAudio`
+   *    triOsc.start();
    *
-   *    background(0,255,0);
-   *    text('attack!', width/2, height/2);
+   *    env.triggerAttack(triOsc);
    *  }
    *
    *  function mouseReleased() {
-   *    env.triggerRelease();
+   *    background(220);
+   *    text('tap to triggerAttack', width/2, height/2);
    *
-   *    background(200);
-   *    text('click to play', width/2, height/2);
+   *    env.triggerRelease(triOsc);
    *  }
    *  </code></div>
    */
@@ -603,48 +597,43 @@ define(function (require) {
    *  @param  {Number} secondsFromNow time to trigger the release
    *  @example
    *  <div><code>
-   *
-   *  var attackLevel = 1.0;
-   *  var releaseLevel = 0;
-   *
-   *  var attackTime = 0.001;
-   *  var decayTime = 0.3;
-   *  var susPercent = 0.4;
-   *  var releaseTime = 0.5;
-   *
-   *  var env, triOsc;
+   *  let attackTime = 0.001;
+   *  let decayTime = 0.2;
+   *  let susPercent = 0.3;
+   *  let releaseTime = 0.4;
+   *  let env, triOsc;
    *
    *  function setup() {
-   *    var cnv = createCanvas(100, 100);
-   *    background(200);
+   *    let cnv = createCanvas(100, 100);
+   *    background(220);
    *    textAlign(CENTER);
-   *    text('click to play', width/2, height/2);
+   *    textSize(10);
+   *    text('tap to triggerAttack', width/2, height/2);
    *
    *    env = new p5.Envelope();
    *    env.setADSR(attackTime, decayTime, susPercent, releaseTime);
-   *    env.setRange(attackLevel, releaseLevel);
-   *
+   *    env.setRange(1.0, 0.0);
    *    triOsc = new p5.Oscillator('triangle');
-   *    triOsc.amp(env);
-   *    triOsc.start();
    *    triOsc.freq(220);
    *
    *    cnv.mousePressed(envAttack);
    *  }
    *
    *  function envAttack()  {
-   *    console.log('trigger attack');
-   *    env.triggerAttack();
+   *    background(0, 255, 255);
+   *    text('release to release', width/2, height/2);
+   *
+   *    // ensures audio is enabled. See also: `userStartAudio`
+   *    triOsc.start();
    *
-   *    background(0,255,0);
-   *    text('attack!', width/2, height/2);
+   *    env.triggerAttack(triOsc);
    *  }
    *
    *  function mouseReleased() {
-   *    env.triggerRelease();
+   *    background(220);
+   *    text('tap to triggerAttack', width/2, height/2);
    *
-   *    background(200);
-   *    text('click to play', width/2, height/2);
+   *    env.triggerRelease(triOsc);
    *  }
    *  </code></div>
    */
@@ -674,6 +663,7 @@ define(function (require) {
 
     // get and set value (with linear or exponential ramp) to anchor automation
     var valToSet = this.control.getValueAtTime(t);
+
     if (this.isExponential === true)
     {
       this.control.exponentialRampToValueAtTime(this.checkExpInput(valToSet), t);
@@ -720,39 +710,38 @@ define(function (require) {
    *  @param  {Number} [v2]           Second target value (optional)
    *  @example
    *  <div><code>
-   *  var env, osc, amp, cnv;
+   *  let env, osc, amp;
    *
-   *  var attackTime = 0.001;
-   *  var decayTime = 0.2;
-   *  var attackLevel = 1;
-   *  var decayLevel = 0;
+   *  let attackTime = 0.001;
+   *  let decayTime = 0.2;
+   *  let attackLevel = 1;
+   *  let decayLevel = 0;
    *
    *  function setup() {
-   *    cnv = createCanvas(100, 100);
+   *    let cnv = createCanvas(100, 100);
    *    fill(0,255,0);
    *    noStroke();
    *
    *    env = new p5.Envelope();
    *    env.setADSR(attackTime, decayTime);
-   *
    *    osc = new p5.Oscillator();
    *    osc.amp(env);
-   *    osc.start();
-   *
    *    amp = new p5.Amplitude();
    *
    *    cnv.mousePressed(triggerRamp);
    *  }
    *
    *  function triggerRamp() {
+   *    // ensures audio is enabled. See also: `userStartAudio`
+   *    osc.start();
+   *
    *    env.ramp(osc, 0, attackLevel, decayLevel);
    *  }
    *
    *  function draw() {
-   *    background(20,20,20);
-   *    text('click me', 10, 20);
-   *    var h = map(amp.getLevel(), 0, 0.4, 0, height);;
-   *
+   *    background(20);
+   *    text('tap to play', 10, 20);
+   *    let h = map(amp.getLevel(), 0, 0.4, 0, height);;
    *    rect(0, height, width, -h);
    *  }
    *  </code></div>
diff --git a/src/eq.js b/src/eq.js
index 26b4409f..3ff5bcb3 100644
--- a/src/eq.js
+++ b/src/eq.js
@@ -29,11 +29,9 @@ define(function (require) {
    *
    * @example
    * <div><code>
-   * var eq;
-   * var band_names;
-   * var band_index;
-   *
-   * var soundFile, play;
+   * let eq, soundFile
+   * let eqBandIndex = 0;
+   * let eqBandNames = ['lows', 'mids', 'highs'];
    *
    * function preload() {
    *   soundFormats('mp3', 'ogg');
@@ -41,48 +39,47 @@ define(function (require) {
    * }
    *
    * function setup() {
-   *   eq = new p5.EQ(3);
+   *   let cnv = createCanvas(100, 100);
+   *   cnv.mousePressed(toggleSound);
+   *
+   *   eq = new p5.EQ(eqBandNames.length);
    *   soundFile.disconnect();
    *   eq.process(soundFile);
-   *
-   *   band_names = ['lows','mids','highs'];
-   *   band_index = 0;
-   *   play = false;
-   *   textAlign(CENTER);
    * }
    *
    * function draw() {
    *   background(30);
    *   noStroke();
    *   fill(255);
-   *   text('click to kill',50,25);
+   *   textAlign(CENTER);
+   *   text('filtering ', 50, 25);
    *
    *   fill(255, 40, 255);
    *   textSize(26);
-   *   text(band_names[band_index],50,55);
+   *   text(eqBandNames[eqBandIndex], 50, 55);
    *
    *   fill(255);
    *   textSize(9);
-   *   text('space = play/pause',50,80);
-   * }
    *
-   * //If mouse is over canvas, cycle to the next band and kill the frequency
-   * function mouseClicked() {
-   *   for (var i = 0; i < eq.bands.length; i++) {
-   *     eq.bands[i].gain(0);
-   *   }
-   *   eq.bands[band_index].gain(-40);
-   *   if (mouseX > 0 && mouseX < width && mouseY < height && mouseY > 0) {
-   *     band_index === 2 ? band_index = 0 : band_index++;
+   *   if (!soundFile.isPlaying()) {
+   *     text('tap to play', 50, 80);
+   *   } else {
+   *     text('tap to filter next band', 50, 80)
    *   }
    * }
    *
-   * //use space bar to trigger play / pause
-   * function keyPressed() {
-   *   if (key===' ') {
-   *     play = !play
-   *     play ? soundFile.loop() : soundFile.pause();
+   * function toggleSound() {
+   *   if (!soundFile.isPlaying()) {
+   *     soundFile.play();
+   *   } else {
+   *     eqBandIndex = (eqBandIndex + 1) % eq.bands.length;
+   *   }
+   *
+   *   for (let i = 0; i < eq.bands.length; i++) {
+   *     eq.bands[i].gain(0);
    *   }
+   *   // filter the band we want to filter
+   *   eq.bands[eqBandIndex].gain(-40);
    * }
    * </code></div>
    */
diff --git a/src/fft.js b/src/fft.js
index 2dcaad04..7cd546df 100644
--- a/src/fft.js
+++ b/src/fft.js
@@ -46,40 +46,38 @@ define(function(require) {
    *  }
    *
    *  function setup(){
-   *    var cnv = createCanvas(100,100);
+   *    let cnv = createCanvas(100,100);
    *    cnv.mouseClicked(togglePlay);
    *    fft = new p5.FFT();
    *    sound.amp(0.2);
    *  }
    *
    *  function draw(){
-   *    background(0);
+   *    background(220);
    *
-   *    var spectrum = fft.analyze();
+   *    let spectrum = fft.analyze();
    *    noStroke();
-   *    fill(0,255,0); // spectrum is green
-   *    for (var i = 0; i< spectrum.length; i++){
-   *      var x = map(i, 0, spectrum.length, 0, width);
-   *      var h = -height + map(spectrum[i], 0, 255, height, 0);
+   *    fill(255, 0, 255);
+   *    for (let i = 0; i< spectrum.length; i++){
+   *      let x = map(i, 0, spectrum.length, 0, width);
+   *      let h = -height + map(spectrum[i], 0, 255, height, 0);
    *      rect(x, height, width / spectrum.length, h )
    *    }
    *
-   *    var waveform = fft.waveform();
+   *    let waveform = fft.waveform();
    *    noFill();
    *    beginShape();
-   *    stroke(255,0,0); // waveform is red
-   *    strokeWeight(1);
-   *    for (var i = 0; i< waveform.length; i++){
-   *      var x = map(i, 0, waveform.length, 0, width);
-   *      var y = map( waveform[i], -1, 1, 0, height);
+   *    stroke(20);
+   *    for (let i = 0; i < waveform.length; i++){
+   *      let x = map(i, 0, waveform.length, 0, width);
+   *      let y = map( waveform[i], -1, 1, 0, height);
    *      vertex(x,y);
    *    }
    *    endShape();
    *
-   *    text('click to play/pause', 4, 10);
+   *    text('tap to play', 20, 20);
    *  }
    *
-   *  // fade sound if mouse is over canvas
    *  function togglePlay() {
    *    if (sound.isPlaying()) {
    *      sound.pause();
@@ -227,47 +225,47 @@ define(function(require) {
    *                              possible is 255.
    *  @example
    *  <div><code>
-   *  var osc;
-   *  var fft;
+   *  let osc, fft;
    *
    *  function setup(){
-   *    createCanvas(100,100);
+   *    let cnv = createCanvas(100,100);
+   *    cnv.mousePressed(startSound);
    *    osc = new p5.Oscillator();
    *    osc.amp(0);
-   *    osc.start();
    *    fft = new p5.FFT();
    *  }
    *
    *  function draw(){
-   *    background(0);
+   *    background(220);
    *
-   *    var freq = map(mouseX, 0, 800, 20, 15000);
+   *    let freq = map(mouseX, 0, windowWidth, 20, 10000);
    *    freq = constrain(freq, 1, 20000);
    *    osc.freq(freq);
    *
-   *    var spectrum = fft.analyze();
+   *    let spectrum = fft.analyze();
    *    noStroke();
-   *    fill(0,255,0); // spectrum is green
-   *    for (var i = 0; i< spectrum.length; i++){
-   *      var x = map(i, 0, spectrum.length, 0, width);
-   *      var h = -height + map(spectrum[i], 0, 255, height, 0);
+   *    fill(255, 0, 255);
+   *    for (let i = 0; i< spectrum.length; i++){
+   *      let x = map(i, 0, spectrum.length, 0, width);
+   *      let h = -height + map(spectrum[i], 0, 255, height, 0);
    *      rect(x, height, width / spectrum.length, h );
    *    }
    *
    *    stroke(255);
-   *    text('Freq: ' + round(freq)+'Hz', 10, 10);
+   *    if (!osc.started) {
+   *      text('tap here and drag to change frequency', 10, 20, width - 20);
+   *    } else {
+   *      text(round(freq)+'Hz', 10, 20);
+   *    }
+   *  }
    *
-   *    isMouseOverCanvas();
+   *  function startSound() {
+   *    osc.start();
+   *    osc.amp(0.5, 0.2);
    *  }
    *
-   *  // only play sound when mouse is over canvas
-   *  function isMouseOverCanvas() {
-   *    var mX = mouseX, mY = mouseY;
-   *    if (mX > 0 && mX < width && mY < height && mY > 0) {
-   *      osc.amp(0.5, 0.2);
-   *    } else {
-   *      osc.amp(0, 0.2);
-   *    }
+   *  function mouseReleased() {
+   *    osc.amp(0, 0.2);
    *  }
    *  </code></div>
    *
@@ -294,7 +292,7 @@ define(function(require) {
       freqToInt(this, this.freqDomain);
       this.analyser.getByteFrequencyData(this.freqDomain);
       var normalArray = Array.apply([], this.freqDomain);
-      
+
       return normalArray;
     }
   };
@@ -402,54 +400,53 @@ define(function(require) {
    *
    * @example
    *  <div><code>
-   *
-   *
-   *function setup(){
+   * function setup(){
    *  cnv = createCanvas(100,100);
+   *  cnv.mousePressed(userStartAudio);
    *  sound = new p5.AudioIn();
    *  sound.start();
    *  fft = new p5.FFT();
    *  sound.connect(fft);
    *}
    *
-   *
-   *function draw(){
-   *
-   *  var centroidplot = 0.0;
-   *  var spectralCentroid = 0;
-   *
+   *function draw() {
+   *  if (getAudioContext().state !== 'running') {
+   *    background(220);
+   *    text('tap here and enable mic to begin', 10, 20, width - 20);
+   *    return;
+   *  }
+   *  let centroidplot = 0.0;
+   *  let spectralCentroid = 0;
    *
    *  background(0);
    *  stroke(0,255,0);
-   *  var spectrum = fft.analyze();
+   *  let spectrum = fft.analyze();
    *  fill(0,255,0); // spectrum is green
    *
    *  //draw the spectrum
-   *  for (var i = 0; i< spectrum.length; i++){
-   *    var x = map(log(i), 0, log(spectrum.length), 0, width);
-   *    var h = map(spectrum[i], 0, 255, 0, height);
-   *    var rectangle_width = (log(i+1)-log(i))*(width/log(spectrum.length));
+   *  for (let i = 0; i < spectrum.length; i++){
+   *    let x = map(log(i), 0, log(spectrum.length), 0, width);
+   *    let h = map(spectrum[i], 0, 255, 0, height);
+   *    let rectangle_width = (log(i+1)-log(i))*(width/log(spectrum.length));
    *    rect(x, height, rectangle_width, -h )
    *  }
-
-   *  var nyquist = 22050;
+   *  let nyquist = 22050;
    *
    *  // get the centroid
    *  spectralCentroid = fft.getCentroid();
    *
    *  // the mean_freq_index calculation is for the display.
-   *  var mean_freq_index = spectralCentroid/(nyquist/spectrum.length);
+   *  let mean_freq_index = spectralCentroid/(nyquist/spectrum.length);
    *
    *  centroidplot = map(log(mean_freq_index), 0, log(spectrum.length), 0, width);
    *
-   *
    *  stroke(255,0,0); // the line showing where the centroid is will be red
    *
    *  rect(centroidplot, 0, width / spectrum.length, height)
    *  noStroke();
    *  fill(255,255,255);  // text is white
-   *  text("centroid: ", 10, 20);
-   *  text(round(spectralCentroid)+" Hz", 10, 40);
+   *  text('centroid: ', 10, 20);
+   *  text(round(spectralCentroid)+' Hz', 10, 40);
    *}
    * </code></div>
    */
diff --git a/src/filter.js b/src/filter.js
index d89f0bb8..e0ed60d8 100644
--- a/src/filter.js
+++ b/src/filter.js
@@ -30,52 +30,56 @@ define(function (require) {
    *  @param {String} [type] 'lowpass' (default), 'highpass', 'bandpass'
    *  @example
    *  <div><code>
-   *  var fft, noise, filter;
-   *
-   *  function setup() {
-   *    fill(255, 40, 255);
-   *
-   *    filter = new p5.BandPass();
-   *
-   *    noise = new p5.Noise();
-   *    // disconnect unfiltered noise,
-   *    // and connect to filter
-   *    noise.disconnect();
-   *    noise.connect(filter);
-   *    noise.start();
-   *
-   *    fft = new p5.FFT();
-   *  }
-   *
-   *  function draw() {
-   *    background(30);
-   *
-   *    // set the BandPass frequency based on mouseX
-   *    var freq = map(mouseX, 0, width, 20, 10000);
-   *    filter.freq(freq);
-   *    // give the filter a narrow band (lower res = wider bandpass)
-   *    filter.res(50);
-   *
-   *    // draw filtered spectrum
-   *    var spectrum = fft.analyze();
-   *    noStroke();
-   *    for (var i = 0; i < spectrum.length; i++) {
-   *      var x = map(i, 0, spectrum.length, 0, width);
-   *      var h = -height + map(spectrum[i], 0, 255, height, 0);
-   *      rect(x, height, width/spectrum.length, h);
-   *    }
-   *
-   *    isMouseOverCanvas();
-   *  }
-   *
-   *  function isMouseOverCanvas() {
-   *    var mX = mouseX, mY = mouseY;
-   *    if (mX > 0 && mX < width && mY < height && mY > 0) {
-   *      noise.amp(0.5, 0.2);
-   *    } else {
-   *      noise.amp(0, 0.2);
-   *    }
-   *  }
+  *  let fft, noise, filter;
+  *
+  *  function setup() {
+  *    let cnv = createCanvas(100,100);
+  *    cnv.mousePressed(makeNoise);
+  *    fill(255, 0, 255);
+  *
+  *    filter = new p5.BandPass();
+  *    noise = new p5.Noise();
+  *    noise.disconnect();
+  *    noise.connect(filter);
+  *
+  *    fft = new p5.FFT();
+  *  }
+  *
+  *  function draw() {
+  *    background(220);
+  *
+  *    // set the BandPass frequency based on mouseX
+  *    let freq = map(mouseX, 0, width, 20, 10000);
+  *    freq = constrain(freq, 0, 22050);
+  *    filter.freq(freq);
+  *    // give the filter a narrow band (lower res = wider bandpass)
+  *    filter.res(50);
+  *
+  *    // draw filtered spectrum
+  *    let spectrum = fft.analyze();
+  *    noStroke();
+  *    for (let i = 0; i < spectrum.length; i++) {
+  *      let x = map(i, 0, spectrum.length, 0, width);
+  *      let h = -height + map(spectrum[i], 0, 255, height, 0);
+  *      rect(x, height, width/spectrum.length, h);
+  *    }
+  *    if (!noise.started) {
+  *      text('tap here and drag to change frequency', 10, 20, width - 20);
+  *    } else {
+  *      text('Frequency: ' + round(freq)+'Hz', 20, 20, width - 20);
+  *    }
+  *  }
+  *
+  *  function makeNoise() {
+  *    // see also: `userStartAudio()`
+  *    noise.start();
+  *    noise.amp(0.5, 0.2);
+  *  }
+  *
+  *  function mouseReleased() {
+  *    noise.amp(0, 0.2);
+  *  }
+  *
    *  </code></div>
    */
   p5.Filter = function (type) {
diff --git a/src/gain.js b/src/gain.js
index a6e76480..628552b1 100644
--- a/src/gain.js
+++ b/src/gain.js
@@ -12,61 +12,63 @@ define(function (require) {
    *  @example
    *  <div><code>
    *
-   * // load two soundfile and crossfade beetween them
-   * var sound1,sound2;
-   * var gain1, gain2, gain3;
-   *
-   * function preload(){
-   *   soundFormats('ogg', 'mp3');
-   *   sound1 = loadSound('assets/Damscray_-_Dancing_Tiger_01');
-   *   sound2 = loadSound('assets/beat.mp3');
-   * }
-   *
-   * function setup() {
-   *   createCanvas(400,200);
-   *
-   *   // create a 'master' gain to which we will connect both soundfiles
-   *   gain3 = new p5.Gain();
-   *   gain3.connect();
-   *
-   *   // setup first sound for playing
-   *   sound1.rate(1);
-   *   sound1.loop();
-   *   sound1.disconnect(); // diconnect from p5 output
-   *
-   *   gain1 = new p5.Gain(); // setup a gain node
-   *   gain1.setInput(sound1); // connect the first sound to its input
-   *   gain1.connect(gain3); // connect its output to the 'master'
-   *
-   *   sound2.rate(1);
-   *   sound2.disconnect();
-   *   sound2.loop();
-   *
-   *   gain2 = new p5.Gain();
-   *   gain2.setInput(sound2);
-   *   gain2.connect(gain3);
-   *
-   * }
-   *
-   * function draw(){
-   *   background(180);
-   *
-   *   // calculate the horizontal distance beetween the mouse and the right of the screen
-   *   var d = dist(mouseX,0,width,0);
-   *
-   *   // map the horizontal position of the mouse to values useable for volume control of sound1
-   *   var vol1 = map(mouseX,0,width,0,1);
-   *   var vol2 = 1-vol1; // when sound1 is loud, sound2 is quiet and vice versa
-   *
-   *   gain1.amp(vol1,0.5,0);
-   *   gain2.amp(vol2,0.5,0);
-   *
-   *   // map the vertical position of the mouse to values useable for 'master volume control'
-   *   var vol3 = map(mouseY,0,height,0,1);
-   *   gain3.amp(vol3,0.5,0);
-   * }
+   *  // load two soundfile and crossfade beetween them
+   *  let sound1,sound2;
+   *  let sound1Gain, sound2Gain, masterGain;
+   *  function preload(){
+   *    soundFormats('ogg', 'mp3');
+   *    sound1 = loadSound('assets/Damscray_-_Dancing_Tiger_01');
+   *    sound2 = loadSound('assets/beat');
+   *  }
+   *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(startSound);
+   *    // create a 'master' gain to which we will connect both soundfiles
+   *    masterGain = new p5.Gain();
+   *    masterGain.connect();
+   *    sound1.disconnect(); // diconnect from p5 output
+   *    sound1Gain = new p5.Gain(); // setup a gain node
+   *    sound1Gain.setInput(sound1); // connect the first sound to its input
+   *    sound1Gain.connect(masterGain); // connect its output to the 'master'
+   *    sound2.disconnect();
+   *    sound2Gain = new p5.Gain();
+   *    sound2Gain.setInput(sound2);
+   *    sound2Gain.connect(masterGain);
+   *  }
+   *  function startSound() {
+   *    sound1.loop();
+   *    sound2.loop();
+   *    loop();
+   *  }
+   *  function mouseReleased() {
+   *    sound1.stop();
+   *    sound2.stop();
+   *  }
+   *  function draw(){
+   *    background(220);
+   *    textAlign(CENTER);
+   *    textSize(11);
+   *    fill(0);
+   *    if (!sound1.isPlaying()) {
+   *      text('tap and drag to play', width/2, height/2);
+   *      return;
+   *    }
+   *    // map the horizontal position of the mouse to values useable for volume    *  control of sound1
+   *    var sound1Volume = constrain(map(mouseX,width,0,0,1), 0, 1);
+   *    var sound2Volume = 1-sound1Volume;
+   *    sound1Gain.amp(sound1Volume);
+   *    sound2Gain.amp(sound2Volume);
+   *    // map the vertical position of the mouse to values useable for 'master    *  volume control'
+   *    var masterVolume = constrain(map(mouseY,height,0,0,1), 0, 1);
+   *    masterGain.amp(masterVolume);
+   *    text('master', width/2, height - masterVolume * height * 0.9)
+   *    fill(255, 0, 255);
+   *    textAlign(LEFT);
+   *    text('sound1', 5, height - sound1Volume * height * 0.9);
+   *    textAlign(RIGHT);
+   *    text('sound2', width - 5, height - sound2Volume * height * 0.9);
+   *  }
    *</code></div>
-   *
    */
 
   p5.Gain = function() {
diff --git a/src/helpers.js b/src/helpers.js
index a13be6c9..f829e9db 100644
--- a/src/helpers.js
+++ b/src/helpers.js
@@ -47,23 +47,37 @@ define(function (require) {
    *  @return {Number} Frequency value of the given MIDI note
    *  @example
    *  <div><code>
-   *  var notes = [60, 64, 67, 72];
-   *  var i = 0;
+   *  let midiNotes = [60, 64, 67, 72];
+   *  let noteIndex = 0;
+   *  let midiVal, freq;
    *
    *  function setup() {
-   *    osc = new p5.Oscillator('Triangle');
-   *    osc.start();
-   *    frameRate(1);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(startSound);
+   *    osc = new p5.TriOsc();
+   *    env = new p5.Envelope();
    *  }
    *
    *  function draw() {
-   *    var freq = midiToFreq(notes[i]);
-   *    osc.freq(freq);
-   *    i++;
-   *    if (i >= notes.length){
-   *      i = 0;
+   *    background(220);
+   *    text('tap to play', 10, 20);
+   *    if (midiVal) {
+   *      text('MIDI: ' + midiVal, 10, 40);
+   *      text('Freq: ' + freq, 10, 60);
    *    }
    *  }
+   *
+   *  function startSound() {
+   *    // see also: userStartAudio();
+   *    osc.start();
+   *
+   *    midiVal = midiNotes[noteIndex % midiNotes.length];
+   *    freq = midiToFreq(midiVal);
+   *    osc.freq(freq);
+   *    env.ramp(osc, 0, 1.0, 0);
+   *
+   *    noteIndex++;
+   *  }
    *  </code></div>
    */
   var midiToFreq = p5.prototype.midiToFreq = function(m) {
@@ -113,8 +127,13 @@ define(function (require) {
    *  }
    *
    *  function setup() {
-   *    mySound.play();
-   *  }
+   *       let cnv = createCanvas(100, 100);
+   *       background(220);
+   *       text('sound loaded! tap to play', 10, 20, width - 20);
+   *       cnv.mousePressed(function() {
+   *         mySound.play();
+   *       });
+   *     }
    *  </code></div>
    */
   p5.prototype.soundFormats = function() {
diff --git a/src/looper.js b/src/looper.js
index 49f3e48a..c136fe91 100644
--- a/src/looper.js
+++ b/src/looper.js
@@ -54,43 +54,35 @@ define(function(require) {
    *                            at each step of the phrase.
    *  @example
    *  <div><code>
-   *  var mySound, myPhrase, myPart;
-   *  var pattern = [1,0,0,2,0,2,0,0];
-   *  var msg = 'click to play';
+   *  let mySound, myPhrase, myPart;
+   *  let pattern = [1,0,0,2,0,2,0,0];
    *
    *  function preload() {
    *    mySound = loadSound('assets/beatbox.mp3');
    *  }
    *
    *  function setup() {
-   *    noStroke();
-   *    fill(255);
-   *    textAlign(CENTER);
-   *    masterVolume(0.1);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playMyPart);
+   *    background(220);
+   *    text('tap to play', width/2, height/2);
+   *    textAlign(CENTER, CENTER);
    *
-   *    myPhrase = new p5.Phrase('bbox', makeSound, pattern);
+   *    myPhrase = new p5.Phrase('bbox', onEachStep, pattern);
    *    myPart = new p5.Part();
    *    myPart.addPhrase(myPhrase);
    *    myPart.setBPM(60);
    *  }
    *
-   *  function draw() {
-   *    background(0);
-   *    text(msg, width/2, height/2);
-   *  }
-   *
-   *  function makeSound(time, playbackRate) {
+   *  function onEachStep(time, playbackRate) {
    *    mySound.rate(playbackRate);
    *    mySound.play(time);
    *  }
    *
-   *  function mouseClicked() {
-   *    if (mouseX > 0 && mouseX < width && mouseY > 0 && mouseY < height) {
-   *      myPart.start();
-   *      msg = 'playing pattern';
-   *    }
+   *  function playMyPart() {
+   *    userStartAudio();
+   *    myPart.start();
    *  }
-   *
    *  </code></div>
    */
   p5.Phrase = function(name, callback, sequence) {
@@ -121,10 +113,9 @@ define(function(require) {
    *  @param {Number} [tatums] Divisions of a beat, e.g. use 1/4, or 0.25 for a quater note (default is 1/16, a sixteenth note)
    *  @example
    *  <div><code>
-   *  var box, drum, myPart;
-   *  var boxPat = [1,0,0,2,0,2,0,0];
-   *  var drumPat = [0,1,1,0,2,0,1,0];
-   *  var msg = 'click to play';
+   *  let box, drum, myPart;
+   *  let boxPat = [1,0,0,2,0,2,0,0];
+   *  let drumPat = [0,1,1,0,2,0,1,0];
    *
    *  function preload() {
    *    box = loadSound('assets/beatbox.mp3');
@@ -132,23 +123,18 @@ define(function(require) {
    *  }
    *
    *  function setup() {
-   *    noStroke();
-   *    fill(255);
-   *    textAlign(CENTER);
-   *    masterVolume(0.1);
-   *
-   *    var boxPhrase = new p5.Phrase('box', playBox, boxPat);
-   *    var drumPhrase = new p5.Phrase('drum', playDrum, drumPat);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playMyPart);
+   *    background(220);
+   *    textAlign(CENTER, CENTER);
+   *    text('tap to play', width/2, height/2);
+   *
+   *    let boxPhrase = new p5.Phrase('box', playBox, boxPat);
+   *    let drumPhrase = new p5.Phrase('drum', playDrum, drumPat);
    *    myPart = new p5.Part();
    *    myPart.addPhrase(boxPhrase);
    *    myPart.addPhrase(drumPhrase);
    *    myPart.setBPM(60);
-   *    masterVolume(0.1);
-   *  }
-   *
-   *  function draw() {
-   *    background(0);
-   *    text(msg, width/2, height/2);
    *  }
    *
    *  function playBox(time, playbackRate) {
@@ -161,11 +147,10 @@ define(function(require) {
    *    drum.play(time);
    *  }
    *
-   *  function mouseClicked() {
-   *    if (mouseX > 0 && mouseX < width && mouseY > 0 && mouseY < height) {
-   *      myPart.start();
-   *      msg = 'playing part';
-   *    }
+   *  function playMyPart() {
+   *    userStartAudio();
+   *
+   *    myPart.start();
    *  }
    *  </code></div>
    */
@@ -363,7 +348,6 @@ define(function(require) {
       this.partStep += 1;
     } else {
       if (!this.looping && this.partStep === this.length - 1) {
-        console.log('done');
         // this.callback(time);
         this.onended();
       }
diff --git a/src/master.js b/src/master.js
index 06acb85b..1f229752 100644
--- a/src/master.js
+++ b/src/master.js
@@ -2,10 +2,7 @@
 
 
 define(['audiocontext'], function (audiocontext) {
-  /**
-   * Master contains AudioContext and the master sound output.
-   * @for p5
-   */
+  // Master contains the master sound output.
   var Master = function() {
     this.input = audiocontext.createGain();
     this.output = audiocontext.createGain();
@@ -113,13 +110,9 @@ define(['audiocontext'], function (audiocontext) {
    */
   p5.prototype.soundOut = p5.soundOut = p5sound;
 
-  /**
-   *  a silent connection to the DesinationNode
-   *  which will ensure that anything connected to it
-   *  will not be garbage collected
-   *
-   *  @private
-   */
+  // a silent connection to the DesinationNode
+  // which will ensure that anything connected to it
+  // will not be garbage collected
   p5.soundOut._silentNode = p5sound.audiocontext.createGain();
   p5.soundOut._silentNode.gain.value = 0;
   p5.soundOut._silentNode.connect(p5sound.audiocontext.destination);
diff --git a/src/monosynth.js b/src/monosynth.js
index 17961a13..e6e2f567 100644
--- a/src/monosynth.js
+++ b/src/monosynth.js
@@ -17,31 +17,30 @@ define(function (require) {
     *  @constructor
     *  @example
     *  <div><code>
-    *  var monoSynth;
+    *  let monoSynth;
     *
     *  function setup() {
-    *    var cnv = createCanvas(100, 100);
+    *    let cnv = createCanvas(100, 100);
     *    cnv.mousePressed(playSynth);
+    *    background(220);
+    *    textAlign(CENTER);
+    *    text('tap to play', width/2, height/2);
     *
     *    monoSynth = new p5.MonoSynth();
-    *
-    *    textAlign(CENTER);
-    *    text('click to play', width/2, height/2);
     *  }
     *
     *  function playSynth() {
+    *    userStartAudio();
+    *
+    *    let note = random(['Fb4', 'G4']);
+    *    // note velocity (volume, from 0 to 1)
+    *    let velocity = random();
     *    // time from now (in seconds)
-    *    var time = 0;
+    *    let time = 0;
     *    // note duration (in seconds)
-    *    var dur = 0.25;
-    *    // velocity (volume, from 0 to 1)
-    *    var v = 0.2;
+    *    let dur = 1/6;
     *
-    *    monoSynth.play("G3", v, time, dur);
-    *    monoSynth.play("C4", v, time += dur, dur);
-    *
-    *    background(random(255), random(255), 255);
-    *    text('click to play', width/2, height/2);
+    *    monoSynth.play(note, velocity, time, dur);
     *  }
     *  </code></div>
     **/
@@ -89,34 +88,33 @@ define(function (require) {
     *                                 Tone</a>. Defaults to 440 hz.
     *  @param  {Number} [velocity] velocity of the note to play (ranging from 0 to 1)
     *  @param  {Number} [secondsFromNow]  time from now (in seconds) at which to play
-    *  @param  {Number} [sustainTime] time to sustain before releasing the envelope
+    *  @param  {Number} [sustainTime] time to sustain before releasing the envelope. Defaults to 0.15 seconds.
     *  @example
     *  <div><code>
-    *  var monoSynth;
+    *  let monoSynth;
     *
     *  function setup() {
-    *    var cnv = createCanvas(100, 100);
+    *    let cnv = createCanvas(100, 100);
     *    cnv.mousePressed(playSynth);
+    *    background(220);
+    *    textAlign(CENTER);
+    *    text('tap to play', width/2, height/2);
     *
     *    monoSynth = new p5.MonoSynth();
-    *
-    *    textAlign(CENTER);
-    *    text('click to play', width/2, height/2);
     *  }
     *
     *  function playSynth() {
+    *    userStartAudio();
+    *
+    *    let note = random(['Fb4', 'G4']);
+    *    // note velocity (volume, from 0 to 1)
+    *    let velocity = random();
     *    // time from now (in seconds)
-    *    var time = 0;
+    *    let time = 0;
     *    // note duration (in seconds)
-    *    var dur = 1/6;
-    *    // note velocity (volume, from 0 to 1)
-    *    var v = random();
-    *
-    *    monoSynth.play("Fb3", v, 0, dur);
-    *    monoSynth.play("Gb3", v, time += dur, dur);
+    *    let dur = 1/6;
     *
-    *    background(random(255), random(255), 255);
-    *    text('click to play', width/2, height/2);
+    *    monoSynth.play(note, velocity, time, dur);
     *  }
     *  </code></div>
     *
@@ -142,9 +140,19 @@ define(function (require) {
      *  @for p5.MonoSynth
      *  @example
      *  <div><code>
-     *  var monoSynth = new p5.MonoSynth();
+     *  let monoSynth;
+     *
+     *  function setup() {
+     *    let cnv = createCanvas(100, 100);
+     *    cnv.mousePressed(triggerAttack);
+     *    background(220);
+     *    text('tap here for attack, let go to release', 5, 20, width - 20);
+     *    monoSynth = new p5.MonoSynth();
+     *  }
+     *
+     *  function triggerAttack() {
+     *    userStartAudio();
      *
-     *  function mousePressed() {
      *    monoSynth.triggerAttack("E3");
      *  }
      *
@@ -171,9 +179,19 @@ define(function (require) {
      *  @for p5.MonoSynth
      *  @example
      *  <div><code>
-     *  var monoSynth = new p5.MonoSynth();
+     *  let monoSynth;
+     *
+     *  function setup() {
+     *    let cnv = createCanvas(100, 100);
+     *    cnv.mousePressed(triggerAttack);
+     *    background(220);
+     *    text('tap here for attack, let go to release', 5, 20, width - 20);
+     *    monoSynth = new p5.MonoSynth();
+     *  }
+     *
+     *  function triggerAttack() {
+     *    userStartAudio();
      *
-     *  function mousePressed() {
      *    monoSynth.triggerAttack("E3");
      *  }
      *
diff --git a/src/oscillator.js b/src/oscillator.js
index e64a2b8b..798432d9 100644
--- a/src/oscillator.js
+++ b/src/oscillator.js
@@ -30,40 +30,43 @@ define(function (require) {
    *                         'sawtooth', 'square'
    *  @example
    *  <div><code>
-   *  var osc;
-   *  var playing = false;
+   *  let osc, playing, freq, amp;
    *
    *  function setup() {
-   *    backgroundColor = color(255,0,255);
-   *    textAlign(CENTER);
-   *
-   *    osc = new p5.Oscillator();
-   *    osc.setType('sine');
-   *    osc.freq(240);
-   *    osc.amp(0);
-   *    osc.start();
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playOscillator);
+   *    osc = new p5.Oscillator('sine');
    *  }
    *
    *  function draw() {
-   *    background(backgroundColor)
-   *    text('click to play', width/2, height/2);
-   *  }
+   *    background(220)
+   *    freq = constrain(map(mouseX, 0, width, 100, 500), 100, 500);
+   *    amp = constrain(map(mouseY, height, 0, 0, 1), 0, 1);
+   *
+   *    text('tap to play', 20, 20);
+   *    text('freq: ' + freq, 20, 40);
+   *    text('amp: ' + amp, 20, 60);
    *
-   *  function mouseClicked() {
-   *    if (mouseX > 0 && mouseX < width && mouseY < height && mouseY > 0) {
-   *      if (!playing) {
-   *        // ramp amplitude to 0.5 over 0.05 seconds
-   *        osc.amp(0.5, 0.05);
-   *        playing = true;
-   *        backgroundColor = color(0,255,255);
-   *      } else {
-   *        // ramp amplitude to 0 over 0.5 seconds
-   *        osc.amp(0, 0.5);
-   *        playing = false;
-   *        backgroundColor = color(255,0,255);
-   *      }
+   *    if (playing) {
+   *      // smooth the transitions by 0.1 seconds
+   *      osc.freq(freq, 0.1);
+   *      osc.amp(amp, 0.1);
    *    }
    *  }
+   *
+   *  function playOscillator() {
+   *    // starting an oscillator on a user gesture will enable audio
+   *    // in browsers that have a strict autoplay policy.
+   *    // See also: userStartAudio();
+   *    osc.start();
+   *    playing = true;
+   *  }
+   *
+   *  function mouseReleased() {
+   *    // ramp amplitude to 0 over 0.5 seconds
+   *    osc.amp(0, 0.5);
+   *    playing = false;
+   *  }
    *  </code> </div>
    */
   p5.Oscillator = function(freq, type) {
@@ -108,9 +111,11 @@ define(function (require) {
   };
 
   /**
-   *  Start an oscillator. Accepts an optional parameter to
-   *  determine how long (in seconds from now) until the
-   *  oscillator starts.
+   *  Start an oscillator.
+   *
+   *  Starting an oscillator on a user gesture will enable audio in browsers
+   *  that have a strict autoplay policy, including Chrome and most mobile
+   *  devices. See also: `userStartAudio()`.
    *
    *  @method  start
    *  @for p5.Oscillator
@@ -229,9 +234,25 @@ define(function (require) {
    *                                  this oscillator's frequency
    *  @example
    *  <div><code>
-   *  var osc = new p5.Oscillator(300);
-   *  osc.start();
-   *  osc.freq(40, 10);
+   *  let osc;
+   *
+   *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playOscillator);
+   *    osc = new p5.Oscillator(300);
+   *    background(220);
+   *    text('tap to play', 20, 20);
+   *  }
+   *
+   *  function playOscillator() {
+   *    osc.start();
+   *    osc.amp(0.5);
+   *    // start at 700Hz
+   *    osc.freq(700);
+   *    // ramp to 60Hz over 0.7 seconds
+   *    osc.freq(60, 0.7);
+   *    osc.amp(0, 0.1, 0.7);
+   *  }
    *  </code></div>
    */
   p5.Oscillator.prototype.freq = function(val, rampTime, tFromNow) {
diff --git a/src/polysynth.js b/src/polysynth.js
index 341e8efa..89fce43e 100644
--- a/src/polysynth.js
+++ b/src/polysynth.js
@@ -19,35 +19,33 @@ define(function (require) {
     *  @param {Number} [maxVoices] Number of voices, defaults to 8;
     *  @example
     *  <div><code>
-    *  var polySynth;
+    *  let polySynth;
     *
     *  function setup() {
-    *    var cnv = createCanvas(100, 100);
+    *    let cnv = createCanvas(100, 100);
     *    cnv.mousePressed(playSynth);
+    *    background(220);
+    *    text('click to play', 20, 20);
     *
     *    polySynth = new p5.PolySynth();
-    *
-    *    textAlign(CENTER);
-    *    text('click to play', width/2, height/2);
     *  }
     *
     *  function playSynth() {
+    *    userStartAudio();
+    *
     *    // note duration (in seconds)
-    *    var dur = 1.5;
+    *    let dur = 1.5;
     *
     *    // time from now (in seconds)
-    *    var time = 0;
+    *    let time = 0;
     *
     *    // velocity (volume, from 0 to 1)
-    *    var vel = 0.1;
+    *    let vel = 0.1;
     *
     *    // notes can overlap with each other
-    *    polySynth.play("G2", vel, 0, dur);
-    *    polySynth.play("C3", vel, time += 1/3, dur);
-    *    polySynth.play("G3", vel, time += 1/3, dur);
-    *
-    *    background(random(255), random(255), 255);
-    *    text('click to play', width/2, height/2);
+    *    polySynth.play('G2', vel, 0, dur);
+    *    polySynth.play('C3', vel, time += 1/3, dur);
+    *    polySynth.play('G3', vel, time += 1/3, dur);
     *  }
     *  </code></div>
     **/
@@ -123,34 +121,33 @@ define(function (require) {
    *  @param  {Number} [sustainTime] time to sustain before releasing the envelope
    *  @example
    *  <div><code>
-   *  var polySynth;
+   *  let polySynth;
    *
    *  function setup() {
-   *    var cnv = createCanvas(100, 100);
+   *    let cnv = createCanvas(100, 100);
    *    cnv.mousePressed(playSynth);
+   *    background(220);
+   *    text('click to play', 20, 20);
    *
    *    polySynth = new p5.PolySynth();
-   *
-   *    textAlign(CENTER);
-   *    text('click to play', width/2, height/2);
    *  }
    *
    *  function playSynth() {
+   *    userStartAudio();
+   *
    *    // note duration (in seconds)
-   *    var dur = 0.1;
+   *    let dur = 1.5;
    *
    *    // time from now (in seconds)
-   *    var time = 0;
+   *    let time = 0;
    *
    *    // velocity (volume, from 0 to 1)
-   *    var vel = 0.1;
-   *
-   *    polySynth.play("G2", vel, 0, dur);
-   *    polySynth.play("C3", vel, 0, dur);
-   *    polySynth.play("G3", vel, 0, dur);
+   *    let vel = 0.1;
    *
-   *    background(random(255), random(255), 255);
-   *    text('click to play', width/2, height/2);
+   *    // notes can overlap with each other
+   *    polySynth.play('G2', vel, 0, dur);
+   *    polySynth.play('C3', vel, time += 1/3, dur);
+   *    polySynth.play('G3', vel, time += 1/3, dur);
    *  }
    *  </code></div>
    */
@@ -231,14 +228,23 @@ define(function (require) {
    *  @param  {Number} [secondsFromNow] time from now (in seconds)
    *  @example
    *  <div><code>
-   *  var polySynth = new p5.PolySynth();
-   *  var pitches = ["G", "D", "G", "C"];
-   *  var octaves = [2, 3, 4];
+   *  let polySynth = new p5.PolySynth();
+   *  let pitches = ['G', 'D', 'G', 'C'];
+   *  let octaves = [2, 3, 4];
+   *
+   *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playChord);
+   *    background(220);
+   *    text('tap to play', 20, 20);
+   *  }
+   *
+   *  function playChord() {
+   *    userStartAudio();
    *
-   *  function mousePressed() {
    *    // play a chord: multiple notes at the same time
-   *    for (var i = 0; i < 4; i++) {
-   *      var note = random(pitches) + random(octaves);
+   *    for (let i = 0; i < 4; i++) {
+   *      let note = random(pitches) + random(octaves);
    *      polySynth.noteAttack(note, 0.1);
    *    }
    *  }
@@ -339,14 +345,23 @@ define(function (require) {
    *  @param  {Number} [secondsFromNow] time to trigger the release
    *  @example
    *  <div><code>
-   *  var pitches = ["G", "D", "G", "C"];
-   *  var octaves = [2, 3, 4];
-   *  var polySynth = new p5.PolySynth();
+   *  let polySynth = new p5.PolySynth();
+   *  let pitches = ['G', 'D', 'G', 'C'];
+   *  let octaves = [2, 3, 4];
+   *
+   *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playChord);
+   *    background(220);
+   *    text('tap to play', 20, 20);
+   *  }
+   *
+   *  function playChord() {
+   *    userStartAudio();
    *
-   *  function mousePressed() {
    *    // play a chord: multiple notes at the same time
-   *    for (var i = 0; i < 4; i++) {
-   *      var note = random(pitches) + random(octaves);
+   *    for (let i = 0; i < 4; i++) {
+   *      let note = random(pitches) + random(octaves);
    *      polySynth.noteAttack(note, 0.1);
    *    }
    *  }
diff --git a/src/pulse.js b/src/pulse.js
index 0ab4cbf2..48608ba4 100644
--- a/src/pulse.js
+++ b/src/pulse.js
@@ -22,21 +22,30 @@ define(function (require) {
    *                         defaults to 0)
    *  @example
    *  <div><code>
-   *  var pulse;
+   *  let pulse;
    *  function setup() {
-   *    background(0);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(startPulse);
+   *    background(220);
    *
-   *    // Create and start the pulse wave oscillator
    *    pulse = new p5.Pulse();
    *    pulse.amp(0.5);
    *    pulse.freq(220);
+   *  }
+   *  function startPulse() {
    *    pulse.start();
+   *    pulse.amp(0.5, 0.02);
+   *  }
+   *  function mouseReleased() {
+   *    pulse.amp(0, 0.2);
    *  }
-   *
    *  function draw() {
-   *    var w = map(mouseX, 0, width, 0, 1);
+   *    background(220);
+   *    text('tap to play', 5, 20, width - 20);
+   *    let w = map(mouseX, 0, width, 0, 1);
    *    w = constrain(w, 0, 1);
-   *    pulse.width(w)
+   *    pulse.width(w);
+   *    text('pulse width: ' + w, 5, height - 20);
    *  }
    *  </code></div>
    */
diff --git a/src/reverb.js b/src/reverb.js
index 4b44b6f3..aedad3be 100644
--- a/src/reverb.js
+++ b/src/reverb.js
@@ -23,18 +23,34 @@ define(function (require) {
    *  @constructor
    *  @example
    *  <div><code>
-   *  var soundFile, reverb;
+   *  let soundFile, reverb;
    *  function preload() {
    *    soundFile = loadSound('assets/Damscray_DancingTiger.mp3');
    *  }
    *
    *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playSound);
+   *
    *    reverb = new p5.Reverb();
    *    soundFile.disconnect(); // so we'll only hear reverb...
    *
    *    // connect soundFile to reverb, process w/
    *    // 3 second reverbTime, decayRate of 2%
    *    reverb.process(soundFile, 3, 2);
+   *  }
+   *
+   *  function draw() {
+   *    let dryWet = constrain(map(mouseX, 0, width, 0, 1), 0, 1);
+   *    // 1 = all reverb, 0 = no reverb
+   *    reverb.drywet(dryWet);
+   *
+   *    background(220);
+   *    text('tap to play', 10, 20);
+   *    text('dry/wet: ' + round(dryWet * 100) + '%', 10, height - 20);
+   *  }
+   *
+   *  function playSound() {
    *    soundFile.play();
    *  }
    *  </code></div>
@@ -224,7 +240,7 @@ define(function (require) {
    *                                     about what went wrong.
    *  @example
    *  <div><code>
-   *  var cVerb, sound;
+   *  let cVerb, sound;
    *  function preload() {
    *    // We have both MP3 and OGG versions of all sound assets
    *    soundFormats('ogg', 'mp3');
@@ -239,13 +255,20 @@ define(function (require) {
    *  }
    *
    *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playSound);
+   *    background(220);
+   *    text('tap to play', 20, 20);
+   *
    *    // disconnect from master output...
    *    sound.disconnect();
    *
    *    // ...and process with cVerb
    *    // so that we only hear the convolution
    *    cVerb.process(sound);
+   *  }
    *
+   *  function playSound() {
    *    sound.play();
    *  }
    *  </code></div>
@@ -300,7 +323,7 @@ define(function (require) {
    *  @return {p5.Convolver}
    *  @example
    *  <div><code>
-   *  var cVerb, sound;
+   *  let cVerb, sound;
    *  function preload() {
    *    // We have both MP3 and OGG versions of all sound assets
    *    soundFormats('ogg', 'mp3');
@@ -315,13 +338,20 @@ define(function (require) {
    *  }
    *
    *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playSound);
+   *    background(220);
+   *    text('tap to play', 20, 20);
+   *
    *    // disconnect from master output...
    *    sound.disconnect();
    *
    *    // ...and process with cVerb
    *    // so that we only hear the convolution
    *    cVerb.process(sound);
+   *  }
    *
+   *  function playSound() {
    *    sound.play();
    *  }
    *  </code></div>
@@ -425,7 +455,7 @@ define(function (require) {
   p5.Convolver.prototype.set = null;
 
   /**
-   *  Connect a source to the reverb, and assign reverb parameters.
+   *  Connect a source to the convolver.
    *
    *  @method  process
    *  @for p5.Convolver
@@ -433,25 +463,38 @@ define(function (require) {
    *                           output.
    *  @example
    *  <div><code>
-   *  var cVerb, sound;
+   *  let cVerb, sound;
    *  function preload() {
+   *    // We have both MP3 and OGG versions of all sound assets
    *    soundFormats('ogg', 'mp3');
    *
-   *    cVerb = createConvolver('assets/concrete-tunnel.mp3');
+   *    // Try replacing 'bx-spring' with other soundfiles like
+   *    // 'concrete-tunnel' 'small-plate' 'drum' 'beatbox'
+   *    cVerb = createConvolver('assets/bx-spring.mp3');
    *
-   *    sound = loadSound('assets/beat.mp3');
+   *    // Try replacing 'Damscray_DancingTiger' with
+   *    // 'beat', 'doorbell', lucky_dragons_-_power_melody'
+   *    sound = loadSound('assets/Damscray_DancingTiger.mp3');
    *  }
    *
    *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(playSound);
+   *    background(220);
+   *    text('tap to play', 20, 20);
+   *
    *    // disconnect from master output...
    *    sound.disconnect();
    *
-   *    // ...and process with (i.e. connect to) cVerb
+   *    // ...and process with cVerb
    *    // so that we only hear the convolution
    *    cVerb.process(sound);
+   *  }
    *
+   *  function playSound() {
    *    sound.play();
    *  }
+   *
    *  </code></div>
    */
   p5.Convolver.prototype.process = function(src) {
diff --git a/src/signal.js b/src/signal.js
index 0d280427..52008c6b 100644
--- a/src/signal.js
+++ b/src/signal.js
@@ -30,22 +30,38 @@ define(function (require) {
    *  @return {Tone.Signal} A Signal object from the Tone.js library
    *  @example
    *  <div><code>
+   *  let carrier, modulator;
+   *
    *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    background(220);
+   *    text('tap to play', 20, 20);
+   *
    *    carrier = new p5.Oscillator('sine');
+   *    carrier.start();
    *    carrier.amp(1); // set amplitude
    *    carrier.freq(220); // set frequency
-   *    carrier.start(); // start oscillating
    *
    *    modulator = new p5.Oscillator('sawtooth');
    *    modulator.disconnect();
+   *    modulator.start();
    *    modulator.amp(1);
    *    modulator.freq(4);
-   *    modulator.start();
    *
    *    // Modulator's default amplitude range is -1 to 1.
    *    // Multiply it by -200, so the range is -200 to 200
    *    // then add 220 so the range is 20 to 420
-   *    carrier.freq( modulator.mult(-200).add(220) );
+   *    carrier.freq( modulator.mult(-400).add(220) );
+   *  }
+   *
+   *  function canvasPressed() {
+   *    userStartAudio();
+   *    carrier.amp(1.0);
+   *  }
+   *
+   *  function mouseReleased() {
+   *    carrier.amp(0);
    *  }
    *  </code></div>
    */
diff --git a/src/soundLoop.js b/src/soundLoop.js
index 57955d6b..0de0d963 100644
--- a/src/soundLoop.js
+++ b/src/soundLoop.js
@@ -11,31 +11,46 @@ define(function (require) {
    * @constructor
    *
    * @param {Function} callback this function will be called on each iteration of theloop
-   * @param {Number|String} [interval] amount of time or beats for each iteration of the loop
-   *                                       defaults to 1
+   * @param {Number|String} [interval] amount of time (if a number) or beats (if a string, following <a href = "https://github.com/Tonejs/Tone.js/wiki/Time">Tone.Time</a> convention) for each iteration of the loop. Defaults to 1 second.
    *
    * @example
    * <div><code>
-   * var click;
-   * var looper1;
+   *  let synth, soundLoop;
+   *  let notePattern = [60, 62, 64, 67, 69, 72];
    *
-   * function preload() {
-   *   click = loadSound('assets/drum.mp3');
+   *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    colorMode(HSB);
+   *    background(0, 0, 86);
+   *    text('tap to start/stop', 10, 20);
+   *
+   *    //the looper's callback is passed the timeFromNow
+   *    //this value should be used as a reference point from
+   *    //which to schedule sounds
+   *    let intervalInSeconds = 0.2;
+   *    soundLoop = new p5.SoundLoop(onSoundLoop, intervalInSeconds);
+   *
+   *    synth = new p5.MonoSynth();
    * }
    *
-   * function setup() {
-   *   //the looper's callback is passed the timeFromNow
-   *   //this value should be used as a reference point from
-   *   //which to schedule sounds
-   *   looper1 = new p5.SoundLoop(function(timeFromNow){
-   *     click.play(timeFromNow);
-   *     background(255 * (looper1.iterations % 2));
-   *     }, 2);
+   * function canvasPressed() {
+   *   // ensure audio is enabled
+   *   userStartAudio();
+   *
+   *   if (soundLoop.isPlaying) {
+   *     soundLoop.stop();
+   *   } else {
+   *     // start the loop
+   *     soundLoop.start();
+   *   }
+   * }
    *
-   *   //stop after 10 iteratios;
-   *   looper1.maxIterations = 10;
-   *   //start the loop
-   *   looper1.start();
+   * function onSoundLoop(timeFromNow) {
+   *   let noteIndex = (soundLoop.iterations - 1) % notePattern.length;
+   *   let note = midiToFreq(notePattern[noteIndex]);
+   *   synth.play(note, 0.5, timeFromNow);
+   *   background(noteIndex * 360 / notePattern.length, 50, 100);
    * }
    * </code></div>
    */
@@ -43,7 +58,7 @@ define(function (require) {
     this.callback = callback;
     /**
      * musicalTimeMode uses <a href = "https://github.com/Tonejs/Tone.js/wiki/Time">Tone.Time</a> convention
-	 * true if string, false if number
+     * true if string, false if number
      * @property {Boolean} musicalTimeMode
      */
     this.musicalTimeMode = typeof this._interval === 'number' ? false : true;
diff --git a/src/soundRecorder.js b/src/soundRecorder.js
index 3547b117..6f50a469 100644
--- a/src/soundRecorder.js
+++ b/src/soundRecorder.js
@@ -22,11 +22,15 @@ define(function (require) {
    *  @constructor
    *  @example
    *  <div><code>
-   *  var mic, recorder, soundFile;
-   *  var state = 0;
+   *  let mic, recorder, soundFile;
+   *  let state = 0;
    *
    *  function setup() {
-   *    background(200);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    background(220);
+   *    textAlign(CENTER, CENTER);
+   *
    *    // create an audio in
    *    mic = new p5.AudioIn();
    *
@@ -43,10 +47,13 @@ define(function (require) {
    *    // playback & save the recording
    *    soundFile = new p5.SoundFile();
    *
-   *    text('keyPress to record', 20, 20);
+   *    text('tap to record', width/2, height/2);
    *  }
    *
-   *  function keyPressed() {
+   *  function canvasPressed() {
+   *    // ensure audio is enabled
+   *    userStartAudio();
+   *
    *    // make sure user enabled the mic
    *    if (state === 0 && mic.enabled) {
    *
@@ -54,7 +61,7 @@ define(function (require) {
    *      recorder.record(soundFile);
    *
    *      background(255,0,0);
-   *      text('Recording!', 20, 20);
+   *      text('Recording!', width/2, height/2);
    *      state++;
    *    }
    *    else if (state === 1) {
@@ -64,7 +71,7 @@ define(function (require) {
    *      // send result to soundFile
    *      recorder.stop();
    *
-   *      text('Stopped', 20, 20);
+   *      text('Done! Tap to play and download', width/2, height/2, width - 20);
    *      state++;
    *    }
    *
diff --git a/src/soundfile.js b/src/soundfile.js
index 0d2ad49f..b5065f93 100644
--- a/src/soundfile.js
+++ b/src/soundfile.js
@@ -45,17 +45,24 @@ define(function (require) {
    *
    *  @example
    *  <div><code>
-   *
+   *  let mySound;
    *  function preload() {
    *    soundFormats('mp3', 'ogg');
-   *    mySound = loadSound('assets/doorbell.mp3');
+   *    mySound = loadSound('assets/doorbell');
    *  }
    *
    *  function setup() {
-   *    mySound.setVolume(0.1);
-   *    mySound.play();
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    background(220);
+   *    text('tap here to play', 10, 20);
    *  }
    *
+   *  function canvasPressed() {
+   *    // playing a sound file on a user gesture
+   *    // is equivalent to `userStartAudio()`
+   *    mySound.play();
+   *  }
    * </code></div>
    */
   p5.SoundFile = function(paths, onload, onerror, whileLoading) {
@@ -170,12 +177,22 @@ define(function (require) {
    *  @return {SoundFile}            Returns a p5.SoundFile
    *  @example
    *  <div><code>
+   *  let mySound;
    *  function preload() {
-   *   mySound = loadSound('assets/doorbell.mp3');
+   *    soundFormats('mp3', 'ogg');
+   *    mySound = loadSound('assets/doorbell');
    *  }
    *
    *  function setup() {
-   *    mySound.setVolume(0.1);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    background(220);
+   *    text('tap here to play', 10, 20);
+   *  }
+   *
+   *  function canvasPressed() {
+   *    // playing a sound file on a user gesture
+   *    // is equivalent to `userStartAudio()`
    *    mySound.play();
    *  }
    *  </code></div>
@@ -454,16 +471,27 @@ define(function (require) {
    *  @param  {String} str 'restart' or 'sustain' or 'untilDone'
    *  @example
    *  <div><code>
-   *  var mySound;
+   *  let mySound;
    *  function preload(){
    *    mySound = loadSound('assets/Damscray_DancingTiger.mp3');
    *  }
-   *  function mouseClicked() {
-   *    mySound.playMode('sustain');
-   *    mySound.play();
+   *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    noFill();
+   *    rect(0, height/2, width - 1, height/2 - 1);
+   *    rect(0, 0, width - 1, height/2);
+   *    textAlign(CENTER, CENTER);
+   *    fill(20);
+   *    text('restart', width/2, 1 * height/4);
+   *    text('sustain', width/2, 3 * height/4);
    *  }
-   *  function keyPressed() {
-   *    mySound.playMode('restart');
+   *  function canvasPressed() {
+   *    if (mouseX < height/2) {
+   *      mySound.playMode('restart');
+   *    } else {
+   *      mySound.playMode('sustain');
+   *    }
    *    mySound.play();
    *  }
    *
@@ -503,29 +531,24 @@ define(function (require) {
    *                               seconds from now
    *  @example
    *  <div><code>
-   *  var soundFile;
-   *
+   *  let soundFile;
    *  function preload() {
    *    soundFormats('ogg', 'mp3');
    *    soundFile = loadSound('assets/Damscray_-_Dancing_Tiger_02.mp3');
    *  }
    *  function setup() {
-   *    background(0, 255, 0);
-   *    soundFile.setVolume(0.1);
-   *    soundFile.loop();
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    background(220);
+   *    text('tap to play, release to pause', 10, 20, width - 20);
    *  }
-   *  function keyTyped() {
-   *    if (key == 'p') {
-   *      soundFile.pause();
-   *      background(255, 0, 0);
-   *    }
+   *  function canvasPressed() {
+   *    soundFile.loop();
+   *    background(0, 200, 50);
    *  }
-   *
-   *  function keyReleased() {
-   *    if (key == 'p') {
-   *      soundFile.play();
-   *      background(0, 255, 0);
-   *    }
+   *  function mouseReleased() {
+   *    soundFile.pause();
+   *    background(220);
    *  }
    *  </code>
    *  </div>
@@ -562,6 +585,31 @@ define(function (require) {
    * @param {Number} [amp]         (optional) playback volume
    * @param {Number} [cueLoopStart] (optional) startTime in seconds
    * @param {Number} [duration]  (optional) loop duration in seconds
+   * @example
+   *  <div><code>
+   *  let soundFile;
+   *  let loopStart = 0.5;
+   *  let loopDuration = 0.2;
+   *  function preload() {
+   *    soundFormats('ogg', 'mp3');
+   *    soundFile = loadSound('assets/Damscray_-_Dancing_Tiger_02.mp3');
+   *  }
+   *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    background(220);
+   *    text('tap to play, release to pause', 10, 20, width - 20);
+   *  }
+   *  function canvasPressed() {
+   *    soundFile.loop();
+   *    background(0, 200, 50);
+   *  }
+   *  function mouseReleased() {
+   *    soundFile.pause();
+   *    background(220);
+   *  }
+   *  </code>
+   *  </div>
    */
   p5.SoundFile.prototype.loop = function(startTime, rate, amp, loopStart, duration) {
     this._looping = true;
@@ -744,9 +792,8 @@ define(function (require) {
    *                                 seconds from now
    * @example
    * <div><code>
-   *
-   *  var ball = {};
-   *  var soundFile;
+   *  let ballX = 0;
+   *  let soundFile;
    *
    *  function preload() {
    *    soundFormats('ogg', 'mp3');
@@ -754,15 +801,17 @@ define(function (require) {
    *  }
    *
    *  function draw() {
-   *    background(0);
-   *    ball.x = constrain(mouseX, 0, width);
-   *    ellipse(ball.x, height/2, 20, 20)
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    background(220);
+   *    ballX = constrain(mouseX, 0, width);
+   *    ellipse(ballX, height/2, 20, 20);
    *  }
    *
-   *  function mousePressed(){
+   *  function canvasPressed(){
    *    // map the ball's x location to a panning degree
    *    // between -1.0 (left) and 1.0 (right)
-   *    var panning = map(ball.x, 0., width,-1.0, 1.0);
+   *    let panning = map(ballX, 0., width,-1.0, 1.0);
    *    soundFile.pan(panning);
    *    soundFile.play();
    *  }
@@ -797,29 +846,33 @@ define(function (require) {
    *                                     Values less than zero play backwards.
    *  @example
    *  <div><code>
-   *  var song;
+   *  let mySound;
    *
    *  function preload() {
-   *    song = loadSound('assets/Damscray_DancingTiger.mp3');
+   *    mySound = loadSound('assets/Damscray_DancingTiger.mp3');
    *  }
    *
    *  function setup() {
-   *    song.loop();
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *  }
+   *  function canvasPressed() {
+   *    mySound.loop();
+   *  }
+   *  function mouseReleased() {
+   *    mySound.pause();
    *  }
-   *
    *  function draw() {
-   *    background(200);
+   *    background(220);
    *
    *    // Set the rate to a range between 0.1 and 4
    *    // Changing the rate also alters the pitch
-   *    var speed = map(mouseY, 0.1, height, 0, 2);
-   *    speed = constrain(speed, 0.01, 4);
-   *    song.rate(speed);
-   *
-   *    // Draw a circle to show what is going on
-   *    stroke(0);
-   *    fill(51, 100);
-   *    ellipse(mouseX, 100, 48, 48);
+   *    let playbackRate = map(mouseY, 0.1, height, 2, 0);
+   *    playbackRate = constrain(playbackRate, 0.01, 4);
+   *    mySound.rate(playbackRate);
+   *
+   *    line(0, mouseY, width, mouseY);
+   *    text('rate: ' + round(playbackRate * 100) + '%', 10, 20);
    *  }
    *
    * </code>
@@ -1033,17 +1086,23 @@ define(function (require) {
    *  @for p5.SoundFile
    *  @example
    *  <div><code>
-   *  var drum;
-   *
+   *  let drum;
    *  function preload() {
    *    drum = loadSound('assets/drum.mp3');
    *  }
    *
    *  function setup() {
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    background(220);
+   *    text('tap to play', 20, 20);
+   *  }
+   *
+   *  function canvasPressed() {
+   *    drum.stop();
    *    drum.reverseBuffer();
    *    drum.play();
    *  }
-   *
    * </code>
    * </div>
    */
@@ -1563,43 +1622,32 @@ define(function (require) {
    *                      useful for removeCue(id)
    *  @example
    *  <div><code>
-   *  var mySound;
+   *  let mySound;
    *  function preload() {
-   *    mySound = loadSound('assets/beat.mp3');
+   *    mySound = loadSound('assets/Damscray_DancingTiger.mp3');
    *  }
    *
    *  function setup() {
-   *    background(0);
-   *    noStroke();
-   *    fill(255);
-   *    textAlign(CENTER);
-   *    text('click to play', width/2, height/2);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    background(220);
+   *    text('tap to play', 10, 20);
    *
    *    // schedule calls to changeText
-   *    mySound.addCue(0.50, changeText, "hello" );
-   *    mySound.addCue(1.00, changeText, "p5" );
-   *    mySound.addCue(1.50, changeText, "what" );
-   *    mySound.addCue(2.00, changeText, "do" );
-   *    mySound.addCue(2.50, changeText, "you" );
-   *    mySound.addCue(3.00, changeText, "want" );
-   *    mySound.addCue(4.00, changeText, "to" );
-   *    mySound.addCue(5.00, changeText, "make" );
-   *    mySound.addCue(6.00, changeText, "?" );
+   *    mySound.addCue(0, changeText, "hello" );
+   *    mySound.addCue(0.5, changeText, "hello," );
+   *    mySound.addCue(1, changeText, "hello, p5!");
+   *    mySound.addCue(1.5, changeText, "hello, p5!!");
+   *    mySound.addCue(2, changeText, "hello, p5!!!!!");
    *  }
    *
    *  function changeText(val) {
-   *    background(0);
-   *    text(val, width/2, height/2);
+   *    background(220);
+   *    text(val, 10, 20);
    *  }
    *
-   *  function mouseClicked() {
-   *    if (mouseX > 0 && mouseX < width && mouseY > 0 && mouseY < height) {
-   *      if (mySound.isPlaying() ) {
-   *        mySound.stop();
-   *      } else {
-   *        mySound.play();
-   *      }
-   *    }
+   *  function canvasPressed() {
+   *    mySound.play();
    *  }
    *  </code></div>
    */
@@ -1683,19 +1731,19 @@ define(function (require) {
    * @param  {String} [fileName]      name of the resulting .wav file.
    * @example
    *  <div><code>
-   *  var inp, button, mySound;
-   *  var fileName = 'cool';
+   *  let mySound;
    *  function preload() {
    *    mySound = loadSound('assets/doorbell.mp3');
    *  }
    *  function setup() {
-   *    btn = createButton('click to save file');
-   *    btn.position(0, 0);
-   *    btn.mouseClicked(handleMouseClick);
+   *    let cnv = createCanvas(100, 100);
+   *    cnv.mousePressed(canvasPressed);
+   *    background(220);
+   *    text('tap to download', 10, 20);
    *  }
    *
-   *  function handleMouseClick() {
-   *    mySound.save(fileName);
+   *  function canvasPressed() {
+   *    mySound.save('my cool filename');
    *  }
    * </code></div>
    */
@@ -1719,18 +1767,17 @@ define(function (require) {
    * @returns {Blob} A file-like data object
    * @example
    *  <div><code>
-   *
    *  function preload() {
    *    mySound = loadSound('assets/doorbell.mp3');
    *  }
    *
    *  function setup() {
    *    noCanvas();
-   *    var soundBlob = mySound.getBlob();
+   *    let soundBlob = mySound.getBlob();
    *
    *    // Now we can send the blob to a server...
-   *    var serverUrl = 'https://jsonplaceholder.typicode.com/posts';
-   *    var httpRequestOptions = {
+   *    let serverUrl = 'https://jsonplaceholder.typicode.com/posts';
+   *    let httpRequestOptions = {
    *      method: 'POST',
    *      body: new FormData().append('soundBlob', soundBlob),
    *      headers: new Headers({
@@ -1740,15 +1787,15 @@ define(function (require) {
    *    httpDo(serverUrl, httpRequestOptions);
    *
    *    // We can also create an `ObjectURL` pointing to the Blob
-   *    var blobUrl = URL.createObjectURL(soundBlob);
+   *    let blobUrl = URL.createObjectURL(soundBlob);
    *
    *    // The `<Audio>` Element accepts Object URL's
-   *    var htmlAudioElt = createAudio(blobUrl).showControls();
+   *    createAudio(blobUrl).showControls();
    *
    *    createDiv();
    *
    *    // The ObjectURL exists as long as this tab is open
-   *    var input = createInput(blobUrl);
+   *    let input = createInput(blobUrl);
    *    input.attribute('readonly', true);
    *    input.mouseClicked(function() { input.elt.select() });
    *  }