1 /**
  2  * @class activeSound
  3  * @description
  4  * Class that assists in working with audio waveforms that are currently being streamed 
  5  * to the audio manager. </br></br>
  6  *
  7  * Once an audio asset ({@link audioBlock}) is requested to be played through 
  8  * {@link sandboxe.sound.playAudio}, activeSound objects allow you to interact 
  9  * with the playing waveform to allow for more dynamic behavior. Since 
 10  * activeSounds reflect a temporary object on the audio engine, activeSounds 
 11  * are not directly instantiable. </br></br>
 12  * 
 13  * Example: </br>
 14  * @example 
 15  // Once we play a sound, we get the activeSound reference.
 16  var sound = sandboxe.sound.playAudio(myAudioAsset);
 17 
 18  // Since we want to interact with the sound over time, lets 
 19  // make an entity and insert its behavior into its step function.
 20  var fader = sandboxe.entity.create();
 21 
 22  fader.onStep = function() {
 23      // We're going to make the sound fade out over time by setting its volume
 24      sound.volume *= .99;
 25      
 26      // if the volume is too low, halt the sound and remove the object
 27      if (sound.volume < .1) {
 28          sandboxe.console.info('Sound halted!\n');        
 29          sound.stop();
 30          fader.remove();
 31      }
 32 
 33      // If the sound stopped natrually before the volume was low enough, 
 34      // just remove the object and report it.
 35      if (!sound.valid) {
 36          fader.remove();
 37          sandboxe.console.info('Sound ended on its own!\n');
 38      }
 39  }
 40 
 41  sandboxe.engine.setRoot(fader);
 42  *
 43  *
 44  */ 
 45 function activeSound() {
 46      
 47 
 48     /**
 49      * Requests that the sound manager change its playback position of the active sound to 
 50      * a new location.
 51      * @param {Number} seconds Seconds of progress within the sample to seek.  
 52      */
 53     this.seek = function(){};
 54     
 55     /**
 56      * Requests that the sound manager halt playing this sound.
 57      */
 58     this.stop = function(){};
 59 
 60     /**
 61      * Requests that the sound manager temporary halt the playback of this sound.
 62      * If the process is acknowledged, the sample will be suspended until 
 63      * resume() is called.
 64      */
 65     this.pause = function(){};
 66 
 67     /**
 68      * Requests that the sound manager continue playing this sample.
 69      */
 70     this.resume = function(){};
 71 
 72 
 73      
 74     /**
 75      * The volume of the sample. 0.0 will result in a silent playback 
 76      * 1.0 is the default.
 77      * @type {Number}
 78      */
 79     this.volume = 1.0;
 80 
 81     /**
 82      * The panning of the sample playback. The default is 0.5, meaning evenly 
 83      * split between the 2 output channels. 0.0 is leftmost, 1.0 is rightmost.
 84      * @type {Number}
 85      */
 86     this.panning = .5;
 87      
 88 
 89     /**
 90      * Sets whether the sample should be repeated once all samples have been exhausted.  
 91      * This reference to the active sound will be valid until repeat is over.
 92      * @type {Boolean}
 93      */
 94     this.repeat = false;
 95 
 96     /**
 97      * The output channel of the sound sample. Changing this requests a new output channel for the buffer.
 98      * The default is the channel that the sound was played on.
 99      * @type {Number}
100      */
101     this.channel = 0;
102 
103     /**
104      * Whether this activeSound still refers to a valid sound. Writing over this 
105      * value has no effect.
106      * @type {Boolean}
107      */
108     this.valid = true;
109 
110     
111      
112     return this;
113 }