synths accept notes as frequency or as midi note string (C4)

Author: jvntf

src/audioVoice.js

@@ -3,8 +3,12 @@ define(function() {
   var p5sound = require('master');
 
   /**
-   * Base class for synthesizers and instruments
-   * handles note triggering and what not
+   * Base class for monophonic synthesizers. Any extensions of this class
+   * should follow the API and implement the methods below in order to 
+   * remain compatible with p5.PolySynth();
+   *
+   * @class AudioVoice
+   * @constructor
    */
   p5.AudioVoice = function () {
 	  this.ac = p5sound.audiocontext;
@@ -13,14 +17,19 @@ define(function() {
 	  p5sound.soundArray.push(this);
   };
 
+  /**
+   * This method converts midi notes specified as a string "C4", "Eb3"...etc
+   * to frequency
+   * @private
+   * @method  _setNote
+   * @param {String} note 
+   */
   p5.AudioVoice.prototype._setNote = function(note) {
     var wholeNotes = {A:21, B:23, C:24, D:26, E:28, F:29, G:31};
-
     var value = wholeNotes[ note[0] ];
     var octave = typeof Number(note.slice(-1)) === 'number'? note.slice(-1) : 0;
     value += 12 * octave;
     value = note[1] === '#' ? value+1 : note[1] ==='b' ? value - 1 : value;
-
     //return midi value converted to frequency
     return p5.prototype.midiToFreq(value);
   };
@@ -37,17 +46,20 @@ define(function() {
   p5.AudioVoice.prototype.amp = function(vol, rampTime) {
   };
 
-  p5.AudioVoice.prototype.setParams = function(params) {
-  };
-
-  p5.AudioVoice.prototype.loadPreset = function(preset) {
-  };
-
+  /**
+   * Connect to p5 objects or Web Audio Nodes
+   * @method  connect
+   * @param {Object} unit 
+   */
   p5.AudioVoice.prototype.connect = function(unit) {
     var u = unit || p5sound.input;
     this.output.connect(u.input ? u.input : u);
   };
 
+  /**
+   * Disconnect from soundOut
+   * @method  disconnect
+   */
   p5.AudioVoice.prototype.disconect = function() {
     this.output.disconnect();
   };

src/monosynth.js

@@ -65,7 +65,8 @@ define(function (require) {
   p5.MonoSynth.prototype = Object.create(p5.AudioVoice.prototype);
 
   /**
-     *  Play tells the MonoSynth to start playing a note
+     *  Play tells the MonoSynth to start playing a note. This method schedules
+     *  the calling of .triggerAttack and .triggerRelease.
      *
      *  @method play
      *  @param {String | Number} note the note you want to play, specified as a 
@@ -78,7 +79,6 @@ define(function (require) {
      *  @param  {Number} [sustainTime] time to sustain before releasing the envelope
      *
      */
-
   p5.MonoSynth.prototype.play = function (note, velocity, secondsFromNow, susTime) {
     // set range of env (TO DO: allow this to be scheduled in advance)
     var susTime = susTime || this.sustain;
@@ -104,24 +104,24 @@ define(function (require) {
      */
   p5.MonoSynth.prototype.triggerAttack = function (note, velocity, secondsFromNow) {
     var secondsFromNow = secondsFromNow || 0;
-    var freq = typeof note === 'string' ? this._setNote(note) 
-            : typeof note === 'number' ? note : 440;
-    var vel = velocity || 1;
 
+    //triggerAttack uses ._setNote to convert a midi string to a frequency if necessary
+    var freq = typeof note === 'string' ? this._setNote(note)
+      : typeof note === 'number' ? note : 440;
+    var vel = velocity || 1;
     this._isOn = true;
     this.oscillator.freq(freq, 0, secondsFromNow);
     this.env.ramp(this.output, secondsFromNow, vel);
   };
 
   /**
-     *  Trigger the Release of the Envelope. This is similar to releasing
+     *  Trigger the release of the Envelope. This is similar to releasing
      *  the key on a piano and letting the sound fade according to the
      *  release level and release time.
      *
      *  @param  {Number} secondsFromNow time to trigger the release
      *  @method  triggerRelease
      */
-
   p5.MonoSynth.prototype.triggerRelease = function (secondsFromNow) {
     var secondsFromNow = secondsFromNow || 0;
     this.env.ramp(this.output, secondsFromNow, 0);
@@ -148,8 +148,7 @@ define(function (require) {
      *                                increased to 1.0 (using <code>setRange</code>),
      *                                then decayLevel would increase proportionally, to become 0.5.
      *  @param {Number} [releaseTime]   Time in seconds from now (defaults to 0)
-     **/
-
+     */
   p5.MonoSynth.prototype.setADSR = function (attack,decay,sustain,release) {
     this.env.setADSR(attack, decay,  sustain, release);
   };
@@ -232,7 +231,7 @@ define(function (require) {
   /**
    *  Disconnect all outputs
    *
-   *  @method  disconnects
+   *  @method  disconnect
    */
   p5.MonoSynth.prototype.disconnect = function() {
     this.output.disconnect();

src/polysynth.js

@@ -17,11 +17,9 @@ define(function (require) {
     *  
     *  @param {Number} [synthVoice]   A monophonic synth voice inheriting
     *                                 the AudioVoice class. Defaults to p5.MonoSynth
-    *
     *  @param {Number} [polyValue] Number of voices, defaults to 8;
     *
     *
-    *
     *  @example
     *  <div><code>
     *  var polysynth;
@@ -85,6 +83,7 @@ define(function (require) {
   /**
    * Construct the appropriate number of audiovoices
    * @private
+   * @method  _allocateVoices
    */
   p5.PolySynth.prototype._allocateVoices = function() {
     for(var i = 0; i< this.polyValue; i++) {
@@ -183,43 +182,61 @@ define(function (require) {
     //this value is used by this._voicesInUse
     var t = now + tFromNow;
 
-    // var note = _note === undefined ?  60 : _note;
-    // 
-    var note = typeof _note === 'string' ? this.AudioVoice.prototype._setNote(_note) 
-            : typeof _note === 'number' ? _note : 440;
+    //Convert note to frequency if necessary. This is because entries into this.notes
+    //should be based on frequency for the sake of consistency.
+    var note = typeof _note === 'string' ? this.AudioVoice.prototype._setNote(_note)
+      : typeof _note === 'number' ? _note : 440;
     var velocity = _velocity === undefined ? 1 : _velocity;
 
     var currentVoice;
 
+    //Release the note if it is already playing
     if (this.notes[note] !== undefined) {
       this.noteRelease(note,0);
     }
 
-
+    //Check to see how many voices are in use at the time the note will start
     if(this._voicesInUse.getValueAtTime(t) < this.polyValue) {
       currentVoice = this._voicesInUse.getValueAtTime(t);
-    } else {
+    }
+    //If we are exceeding the polyvalue, bump off the oldest notes and replace
+    //with a new note
+    else {
       currentVoice = this._oldest;
 
       var oldestNote = p5.prototype.freqToMidi(this.audiovoices[this._oldest].oscillator.freq().value);
       this.noteRelease(oldestNote);
       this._oldest = ( this._oldest + 1 ) % (this.polyValue - 1);
     }
 
+    //Overrite the entry in the notes object. A note (frequency value) 
+    //corresponds to the index of the audiovoice that is playing it
     this.notes[note] = currentVoice;
 
-    //this._voicesInUse.setValueAtTime(this._voicesInUse.getValueAtTime(t) + 1, t);
-
+    //Find the scheduled change in this._voicesInUse that will be previous to this new note
+    //Add 1 and schedule this value at time 't', when this note will start playing
     var previousVal = this._voicesInUse._searchBefore(t) === null ? 0 : this._voicesInUse._searchBefore(t).value;
     this._voicesInUse.setValueAtTime(previousVal + 1, t);
+
+    //Then update all scheduled values that follow to increase by 1
     this._updateAfter(t, 1);
 
     this._newest = currentVoice;
 
+    //The audiovoice handles the actual scheduling of the note
     this.audiovoices[currentVoice].triggerAttack(note, velocity, tFromNow);
-
   };
 
+  /**
+   * Private method to ensure accurate values of this._voicesInUse
+   * Any time a new value is scheduled, it is necessary to increment all subsequent
+   * scheduledValues after attack, and decrement all subsequent 
+   * scheduledValues after release
+   * 
+   * @param  {[type]} time  [description]
+   * @param  {[type]} value [description]
+   * @return {[type]}       [description]
+   */
   p5.PolySynth.prototype._updateAfter = function(time, value) {
 
     if(this._voicesInUse._searchAfter(time) === null) {
@@ -229,8 +246,7 @@ define(function (require) {
       var nextTime = this._voicesInUse._searchAfter(time).time;
       this._updateAfter(nextTime, value);
     }
-  }
-
+  };
 
 
   /**
@@ -245,12 +261,9 @@ define(function (require) {
    */  
 
   p5.PolySynth.prototype.noteRelease = function (_note,secondsFromNow) {
-    // var note = _note === undefined ?
-    //   p5.prototype.freqToMidi(this.audiovoices[this._newest].oscillator.freq().value)
-    //   : _note;
+    //Make sure note is in frequency inorder to query the this.notes object
     var note = typeof _note === 'string' ? this.AudioVoice.prototype._setNote(_note)
-            : typeof _note === 'number' ? _note : this.audiovoices[this._newest].oscillator.freq().value;
-
+      : typeof _note === 'number' ? _note : this.audiovoices[this._newest].oscillator.freq().value;
 
     if (this.notes[note] === undefined) {
       console.warn('Cannot release a note that is not already playing');
@@ -259,10 +272,11 @@ define(function (require) {
       var tFromNow = secondsFromNow || 0;
       var t = now + tFromNow;
 
-      // this._voicesInUse.setValueAtTime(this._voicesInUse.getValueAtTime(t)-1, t);
-      // console.log('value at time: '+ t +' value '+this._voicesInUse.getValueAtTime(t));
+      //Find the scheduled change in this._voicesInUse that will be previous to this new note
+      //subtract 1 and schedule this value at time 't', when this note will stop playing
       var previousVal = this._voicesInUse._searchBefore(t) === null ? 0 : this._voicesInUse._searchBefore(t).value;
       this._voicesInUse.setValueAtTime(previousVal - 1, t);
+      //Then update all scheduled values that follow to decrease by 1
       this._updateAfter(t, -1);
 
       // console.log('RELEASE ' + note);
@@ -274,37 +288,33 @@ define(function (require) {
 
   };
 
-
   /**
-   *  Set cutoms parameters to a specific synth implementation 
-   *  with the help of JavaScript Object Notation (JSON).
-   *  
-   *  @method  setParams
-   *  @param   JSON object  
-   * 
-   *  For instance to set the detune parameter of a synth, call :
-   *  setParams({detune: 15 });
-   *
-   */  
-  p5.PolySynth.prototype.noteParams = function (note,params) {
-    if(this.voices[note] == null) {
-      this.voices[note] = new this.AudioVoice();
-    }
-    this.voices[note].setParams(params);
-
-  };
-
+    *  Connect to a p5.sound / Web Audio object.
+    *
+    *  @method  connect
+    *  @param  {Object} unit A p5.sound or Web Audio object
+    */
   p5.PolySynth.prototype.connect = function (unit) {
     var u = unit || p5sound.input;
     this.output.connect(u.input ? u.input : u);
   };
 
+  /**
+  *  Disconnect all outputs
+  *
+  *  @method  disconnect
+  */
   p5.PolySynth.prototype.disconnect = function() {
     this.output.disconnect();
   };
 
+  /**
+    *  Get rid of the MonoSynth and free up its resources / memory.
+    *
+    *  @method  dispose
+    */
   p5.PolySynth.prototype.dispose = function() {
-    this.audiovoices.forEach(function(voice){
+    this.audiovoices.forEach(function(voice) {
       voice.dispose();
     });