diff --git a/src/howler.core.js b/src/howler.core.js index 173619bb..dac7284c 100644 --- a/src/howler.core.js +++ b/src/howler.core.js @@ -63,8 +63,8 @@ /** * Get/set the global volume for all sounds. - * @param {Float} vol Volume from 0.0 to 1.0. - * @return {Howler/Float} Returns self or current volume. + * @param {Number} [vol] - Volume from 0.0 to 1.0. + * @return {Howler|Number} - Returns self or current volume. */ volume: function(vol) { var self = this || Howler; @@ -113,7 +113,8 @@ /** * Handle muting and unmuting globally. - * @param {Boolean} muted Is muted or not. + * @param {Boolean} muted - Is muted or not. + * @return {Howler} */ mute: function(muted) { var self = this || Howler; @@ -152,6 +153,7 @@ /** * Handle stopping all sounds globally. + * @return {Howler} */ stop: function() { var self = this || Howler; @@ -187,7 +189,7 @@ /** * Check for codec support of specific extension. - * @param {String} ext Audio file extention. + * @param {String} ext - Audio file extension. * @return {Boolean} */ codecs: function(ext) { @@ -207,12 +209,14 @@ // Automatically begin the 30-second suspend process self._autoSuspend(); + var test; + // Check if audio is available. if (!self.usingWebAudio) { // No audio is available on this system if noAudio is set to true. if (typeof Audio !== 'undefined') { try { - var test = new Audio(); + test = new Audio(); // Check if the canplaythrough event is available. if (typeof test.oncanplaythrough === 'undefined') { @@ -228,7 +232,7 @@ // Test to make sure audio isn't disabled in Internet Explorer. try { - var test = new Audio(); + test = new Audio(); if (test.muted) { self.noAudio = true; } @@ -292,7 +296,7 @@ * Some browsers/devices will only allow audio to be played after a user interaction. * Attempt to automatically unlock audio on the first user interaction. * Concept from: http://paulbakaus.com/tutorials/html5/web-audio-on-ios/ - * @return {Howler} + * @return {Howler|undefined} */ _unlockAudio: function() { var self = this || Howler; @@ -411,7 +415,7 @@ /** * Get an unlocked HTML5 Audio object from the pool. If none are left, * return a new Audio object and throw a warning. - * @return {Audio} HTML5 Audio object. + * @return {Audio} - HTML5 Audio object. */ _obtainHtml5Audio: function() { var self = this || Howler; @@ -450,7 +454,7 @@ /** * Automatically suspend the Web Audio AudioContext after no sound has played for 30 seconds. * This saves processing/energy and fixes various browser-specific bugs with audio getting stuck. - * @return {Howler} + * @return {Howler|undefined} */ _autoSuspend: function() { var self = this; @@ -503,7 +507,7 @@ /** * Automatically resume the Web Audio AudioContext when a new sound is played. - * @return {Howler} + * @return {Howler|undefined} */ _autoResume: function() { var self = this; @@ -545,7 +549,7 @@ /** * Create an audio group controller. - * @param {Object} o Passed in properties for this group. + * @param {Object} o - Passed in properties for this group. */ var Howl = function(o) { var self = this; @@ -561,7 +565,7 @@ Howl.prototype = { /** * Initialize a new Howl group object. - * @param {Object} o Passed in properties for this group. + * @param {Object} o - Passed in properties for this group. * @return {Howl} */ init: function(o) { @@ -645,7 +649,7 @@ /** * Load the audio file. - * @return {Howler} + * @return {Howler|undefined} */ load: function() { var self = this; @@ -728,9 +732,9 @@ /** * Play a sound or resume previous playback. - * @param {String/Number} sprite Sprite name for sprite playback or sound id to continue previous. - * @param {Boolean} internal Internal Use: true prevents event firing. - * @return {Number} Sound ID. + * @param {String|Number} [sprite] - Sprite name for sprite playback or sound id to continue previous. + * @param {Boolean} [internal] - Internal Use: true prevents event firing. + * @return {Number} - Sound ID. */ play: function(sprite, internal) { var self = this; @@ -840,7 +844,7 @@ // End the sound instantly if seek is at the end. if (seek >= stop) { self._ended(sound); - return; + return sound._id; } // Begin the actual playback. @@ -968,7 +972,7 @@ node.load(); } - // Play immediately if ready, or wait for the 'canplaythrough'e vent. + // Play immediately if ready, or wait for the 'canplaythrough' vent. var loadedNoReadyState = (window && window.ejecta) || (!node.readyState && Howler._navigator.isCocoonJS); if (node.readyState >= 3 || loadedNoReadyState) { playHtml5(); @@ -994,10 +998,11 @@ /** * Pause playback and save current position. - * @param {Number} id The sound ID (empty to pause all in group). + * @param {Number} id - The sound ID (empty to pause all in group). + * @param {Boolean} [internal] - Internal Use: true prevents event firing. * @return {Howl} */ - pause: function(id) { + pause: function(id, internal) { var self = this; // If the sound hasn't loaded or a play() promise is pending, add it to the load queue to pause when capable. @@ -1053,7 +1058,7 @@ } // Fire the pause event, unless `true` is passed as the 2nd argument. - if (!arguments[1]) { + if (!internal) { self._emit('pause', sound ? sound._id : null); } } @@ -1063,8 +1068,8 @@ /** * Stop playback and reset to start. - * @param {Number} id The sound ID (empty to stop all in group). - * @param {Boolean} internal Internal Use: true prevents event firing. + * @param {Number} id - The sound ID (empty to stop all in group). + * @param {Boolean} [internal] - Internal Use: true prevents event firing. * @return {Howl} */ stop: function(id, internal) { @@ -1137,8 +1142,8 @@ /** * Mute/unmute a single sound or all sounds in this Howl group. - * @param {Boolean} muted Set to true to mute and false to unmute. - * @param {Number} id The sound ID to update (omit to mute/unmute all). + * @param {Boolean} muted - Set to true to mute and false to unmute. + * @param {Number} id - The sound ID to update (omit to mute/unmute all). * @return {Howl} */ mute: function(muted, id) { @@ -1199,7 +1204,7 @@ * volume(id) -> Returns the sound id's current volume. * volume(vol) -> Sets the volume of all sounds in this Howl group. * volume(vol, id) -> Sets the volume of passed sound id. - * @return {Howl/Number} Returns self or current volume. + * @return {Howl|Number} - Returns self or current volume. */ volume: function() { var self = this; @@ -1277,10 +1282,10 @@ /** * Fade a currently playing sound between two volumes (if no id is passed, all sounds will fade). - * @param {Number} from The value to fade from (0.0 to 1.0). - * @param {Number} to The volume to fade to (0.0 to 1.0). - * @param {Number} len Time in milliseconds to fade. - * @param {Number} id The sound id (omit to fade all sounds). + * @param {Number} from - The value to fade from (0.0 to 1.0). + * @param {Number} to - The volume to fade to (0.0 to 1.0). + * @param {Number} len - Time in milliseconds to fade. + * @param {Number} id - The sound id (omit to fade all sounds). * @return {Howl} */ fade: function(from, to, len, id) { @@ -1337,12 +1342,12 @@ /** * Starts the internal interval to fade a sound. - * @param {Object} sound Reference to sound to fade. - * @param {Number} from The value to fade from (0.0 to 1.0). - * @param {Number} to The volume to fade to (0.0 to 1.0). - * @param {Number} len Time in milliseconds to fade. - * @param {Number} id The sound id to fade. - * @param {Boolean} isGroup If true, set the volume on the group. + * @param {Object} sound - Reference to sound to fade. + * @param {Number} from - The value to fade from (0.0 to 1.0). + * @param {Number} to - The volume to fade to (0.0 to 1.0). + * @param {Number} len - Time in milliseconds to fade. + * @param {Number} id - The sound id to fade. + * @param {Boolean} isGroup - If true, set the volume on the group. */ _startFadeInterval: function(sound, from, to, len, id, isGroup) { var self = this; @@ -1398,7 +1403,7 @@ /** * Internal method that stops the currently playing fade when * a new fade starts, volume is changed or the sound is stopped. - * @param {Number} id The sound id. + * @param {Number} id - The sound id. * @return {Howl} */ _stopFade: function(id) { @@ -1426,7 +1431,7 @@ * loop(id) -> Returns the sound id's loop value. * loop(loop) -> Sets the loop value for all sounds in this Howl group. * loop(loop, id) -> Sets the loop value of passed sound id. - * @return {Howl/Boolean} Returns self or current loop value. + * @return {Howl|Boolean} - Returns self or current loop value. */ loop: function() { var self = this; @@ -1435,7 +1440,7 @@ // Determine the values for loop and id. if (args.length === 0) { - // Return the grou's loop value. + // Return the groups loop value. return self._loop; } else if (args.length === 1) { if (typeof args[0] === 'boolean') { @@ -1477,7 +1482,7 @@ * rate(id) -> Returns the sound id's current playback rate. * rate(rate) -> Sets the playback rate of all sounds in this Howl group. * rate(rate, id) -> Sets the playback rate of passed sound id. - * @return {Howl/Number} Returns self or the current playback rate. + * @return {Howl|Number} Returns self or the current playback rate. */ rate: function() { var self = this; @@ -1572,7 +1577,7 @@ * seek(id) -> Returns the sound id's current seek position. * seek(seek) -> Sets the seek position of the first sound node. * seek(seek, id) -> Sets the seek position of passed sound id. - * @return {Howl/Number} Returns self or the current seek position. + * @return {Howl|Number} Returns self or the current seek position. */ seek: function() { var self = this; @@ -1675,8 +1680,8 @@ /** * Check if a specific sound is currently playing or not (if id is provided), or check if at least one of the sounds in the group is playing or not. - * @param {Number} id The sound id to check. If none is passed, the whole sound group is checked. - * @return {Boolean} True if playing and false if not. + * @param {Number} id - The sound id to check. If none is passed, the whole sound group is checked. + * @return {Boolean} - True if playing and false if not. */ playing: function(id) { var self = this; @@ -1699,8 +1704,8 @@ /** * Get the duration of this sound. Passing a sound id will return the sprite duration. - * @param {Number} id The sound id to check. If none is passed, return full source duration. - * @return {Number} Audio duration in seconds. + * @param {Number} id - The sound id to check. If none is passed, return full source duration. + * @return {Number} - Audio duration in seconds. */ duration: function(id) { var self = this; @@ -1717,7 +1722,7 @@ /** * Returns the current loaded state of this Howl. - * @return {String} 'unloaded', 'loading', 'loaded' + * @return {String} - 'unloaded', 'loading', 'loaded' */ state: function() { return this._state; @@ -1791,10 +1796,10 @@ /** * Listen to a custom event. - * @param {String} event Event name. - * @param {Function} fn Listener to call. - * @param {Number} id (optional) Only listen to events for this sound. - * @param {Number} once (INTERNAL) Marks event to fire only once. + * @param {String} event - Event name. + * @param {Function} fn - Listener to call. + * @param {Number} [id] - (optional) Only listen to events for this sound. + * @param {Number} [once] - (INTERNAL) Marks event to fire only once. * @return {Howl} */ on: function(event, fn, id, once) { @@ -1810,9 +1815,9 @@ /** * Remove a custom event. Call without parameters to remove all events. - * @param {String} event Event name. - * @param {Function} fn Listener to remove. Leave empty to remove all. - * @param {Number} id (optional) Only remove events for this sound. + * @param {String} event - Event name. + * @param {Function} fn - Listener to remove. Leave empty to remove all. + * @param {Number} [id] - (optional) Only remove events for this sound. * @return {Howl} */ off: function(event, fn, id) { @@ -1853,9 +1858,9 @@ /** * Listen to a custom event and remove it once fired. - * @param {String} event Event name. - * @param {Function} fn Listener to call. - * @param {Number} id (optional) Only listen to events for this sound. + * @param {String} event - Event name. + * @param {Function} fn - Listener to call. + * @param {Number} [id] - (optional) Only listen to events for this sound. * @return {Howl} */ once: function(event, fn, id) { @@ -1869,9 +1874,9 @@ /** * Emit all events of a specific type and pass the sound id. - * @param {String} event Event name. - * @param {Number} id Sound ID. - * @param {Number} msg Message to go with event. + * @param {String} event - Event name. + * @param {Number} [id] - Sound ID. + * @param {String} [msg] - Message to go with event. * @return {Howl} */ _emit: function(event, id, msg) { @@ -1928,7 +1933,7 @@ /** * Fired when playback ends at the end of the duration. - * @param {Sound} sound The sound object to work with. + * @param {Sound} sound - The sound object to work with. * @return {Howl} */ _ended: function(sound) { @@ -1990,7 +1995,7 @@ /** * Clear the end timer for a sound playback. - * @param {Number} id The sound ID. + * @param {Number} id - The sound ID. * @return {Howl} */ _clearTimer: function(id) { @@ -2015,8 +2020,8 @@ /** * Return the sound identified by this ID, or return null. - * @param {Number} id Sound ID - * @return {Object} Sound object or null. + * @param {Number} id - Sound ID + * @return {?Object} Sound object or null. */ _soundById: function(id) { var self = this; @@ -2033,7 +2038,7 @@ /** * Return an inactive sound from the pool or create a new one. - * @return {Sound} Sound playback object. + * @return {Sound} - Sound playback object. */ _inactiveSound: function() { var self = this; @@ -2093,8 +2098,8 @@ /** * Get all ID's from the sounds pool. - * @param {Number} id Only return one ID if one is passed. - * @return {Array} Array of IDs. + * @param {Number} [id] - Only return one ID if one is passed. + * @return {Array} - Array of IDs. */ _getSoundIds: function(id) { var self = this; @@ -2113,7 +2118,7 @@ /** * Load the sound back into the buffer source. - * @param {Sound} sound The sound object to work with. + * @param {Sound} sound - The sound object to work with. * @return {Howl} */ _refreshBuffer: function(sound) { @@ -2143,7 +2148,7 @@ /** * Prevent memory leaks by cleaning up the buffer source after playback. - * @param {Object} node Sound's audio node containing the buffer source. + * @param {Object} node - Sound's audio node containing the buffer source. * @return {Howl} */ _cleanBuffer: function(node) { @@ -2164,7 +2169,7 @@ /** * Set the source to a 0-second silence to stop any downloading (except in IE). - * @param {Object} node Audio node to clear. + * @param {Object} node - Audio node to clear. */ _clearSound: function(node) { var checkIE = /MSIE |Trident\//.test(Howler._navigator && Howler._navigator.userAgent); @@ -2179,7 +2184,7 @@ /** * Setup the sound object, which each node attached to a Howl group is contained in. - * @param {Object} howl The Howl parent group. + * @param {Object} howl - The Howl parent group. */ var Sound = function(howl) { this._parent = howl; @@ -2275,6 +2280,7 @@ self._rate = parent._rate; self._seek = 0; self._rateSeek = 0; + self._playStart = 0; self._paused = true; self._ended = true; self._sprite = '__default'; @@ -2357,7 +2363,7 @@ /** * Buffer a sound from URL, Data URI or cache and decode to audio source (Web Audio API). - * @param {Howl} self + * @param {Howl} self */ var loadBuffer = function(self) { var url = self._src; @@ -2422,7 +2428,7 @@ /** * Send the XHR request wrapped in a try/catch. - * @param {Object} xhr XHR to send. + * @param {Object} xhr - XHR to send. */ var safeXhrSend = function(xhr) { try { @@ -2434,8 +2440,8 @@ /** * Decode audio data from an array buffer. - * @param {ArrayBuffer} arraybuffer The audio data. - * @param {Howl} self + * @param {ArrayBuffer} arraybuffer - The audio data. + * @param {Howl} self */ var decodeAudioData = function(arraybuffer, self) { // Fire a load error if something broke. @@ -2463,8 +2469,8 @@ /** * Sound is now loaded, so finish setting everything up and fire the loaded event. - * @param {Howl} self - * @param {Object} buffer The decoded buffer sound source. + * @param {Howl} self + * @param {Object} [buffer] - The decoded buffer sound source. */ var loadSound = function(self, buffer) { // Set the duration. diff --git a/src/plugins/howler.spatial.js b/src/plugins/howler.spatial.js index 1ebe275d..12264e64 100644 --- a/src/plugins/howler.spatial.js +++ b/src/plugins/howler.spatial.js @@ -24,8 +24,8 @@ /** * Helper method to update the stereo panning position of all current Howls. * Future Howls will not use this value unless explicitly set. - * @param {Number} pan A value of -1.0 is all the way left and 1.0 is all the way right. - * @return {Howler/Number} Self or current stereo panning value. + * @param {Number} pan - A value of -1.0 is all the way left and 1.0 is all the way right. + * @return {Howler|Number} - Self or current stereo panning value. */ HowlerGlobal.prototype.stereo = function(pan) { var self = this; @@ -46,10 +46,10 @@ /** * Get/set the position of the listener in 3D cartesian space. Sounds using * 3D position will be relative to the listener's position. - * @param {Number} x The x-position of the listener. - * @param {Number} y The y-position of the listener. - * @param {Number} z The z-position of the listener. - * @return {Howler/Array} Self or current listener position. + * @param {Number} x - The x-position of the listener. + * @param {Number} y - The y-position of the listener. + * @param {Number} z - The z-position of the listener. + * @return {Howler|Array} - Self or current listener position. */ HowlerGlobal.prototype.pos = function(x, y, z) { var self = this; @@ -86,13 +86,13 @@ * face of the listener is pointing, and up is the direction the top of the * listener is pointing. Thus, these values are expected to be at right angles * from each other. - * @param {Number} x The x-orientation of the listener. - * @param {Number} y The y-orientation of the listener. - * @param {Number} z The z-orientation of the listener. - * @param {Number} xUp The x-orientation of the top of the listener. - * @param {Number} yUp The y-orientation of the top of the listener. - * @param {Number} zUp The z-orientation of the top of the listener. - * @return {Howler/Array} Returns self or the current orientation vectors. + * @param {Number} x - The x-orientation of the listener. + * @param {Number} y - The y-orientation of the listener. + * @param {Number} z - The z-orientation of the listener. + * @param {Number} xUp - The x-orientation of the top of the listener. + * @param {Number} yUp - The y-orientation of the top of the listener. + * @param {Number} zUp - The z-orientation of the top of the listener. + * @return {Howler|Array} - Returns self or the current orientation vectors. */ HowlerGlobal.prototype.orientation = function(x, y, z, xUp, yUp, zUp) { var self = this; @@ -135,7 +135,7 @@ /** * Add new properties to the core init. - * @param {Function} _super Core init method. + * @param {Function} _super - Core init method. * @return {Howl} */ Howl.prototype.init = (function(_super) { @@ -169,9 +169,9 @@ /** * Get/set the stereo panning of the audio source for this sound or all in the group. - * @param {Number} pan A value of -1.0 is all the way left and 1.0 is all the way right. - * @param {Number} id (optional) The sound ID. If none is passed, all in group will be updated. - * @return {Howl/Number} Returns self or the current stereo panning value. + * @param {Number} pan - A value of -1.0 is all the way left and 1.0 is all the way right. + * @param {Number} [id] - (optional) The sound ID. If none is passed, all in group will be updated. + * @return {Howl|Number} - Returns self or the current stereo panning value. */ Howl.prototype.stereo = function(pan, id) { var self = this; @@ -252,11 +252,11 @@ /** * Get/set the 3D spatial position of the audio source for this sound or group relative to the global listener. - * @param {Number} x The x-position of the audio source. - * @param {Number} y The y-position of the audio source. - * @param {Number} z The z-position of the audio source. - * @param {Number} id (optional) The sound ID. If none is passed, all in group will be updated. - * @return {Howl/Array} Returns self or the current 3D spatial position: [x, y, z]. + * @param {Number} x - The x-position of the audio source. + * @param {Number} y - The y-position of the audio source. + * @param {Number} z - The z-position of the audio source. + * @param {Number} [id] - (optional) The sound ID. If none is passed, all in group will be updated. + * @return {Howl|Array} - Returns self or the current 3D spatial position: [x, y, z]. */ Howl.prototype.pos = function(x, y, z, id) { var self = this; @@ -331,11 +331,11 @@ * Get/set the direction the audio source is pointing in the 3D cartesian coordinate * space. Depending on how direction the sound is, based on the `cone` attributes, * a sound pointing away from the listener can be quiet or silent. - * @param {Number} x The x-orientation of the source. - * @param {Number} y The y-orientation of the source. - * @param {Number} z The z-orientation of the source. - * @param {Number} id (optional) The sound ID. If none is passed, all in group will be updated. - * @return {Howl/Array} Returns self or the current 3D spatial orientation: [x, y, z]. + * @param {Number} x - The x-orientation of the source. + * @param {Number} y - The y-orientation of the source. + * @param {Number} z - The z-orientation of the source. + * @param {Number} [id] - (optional) The sound ID. If none is passed, all in group will be updated. + * @return {Howl|Array} - Returns self or the current 3D spatial orientation: [x, y, z]. */ Howl.prototype.orientation = function(x, y, z, id) { var self = this; @@ -413,7 +413,7 @@ /** * Get/set the panner node's attributes for a sound or group of sounds. - * This method can optionall take 0, 1 or 2 arguments. + * This method can optional take 0, 1 or 2 arguments. * pannerAttr() -> Returns the group's values. * pannerAttr(id) -> Returns the sound id's values. * pannerAttr(o) -> Set's the values of all sounds in this Howl group. @@ -439,7 +439,7 @@ * panningModel - ('HRTF' by default) Determines which spatialization algorithm is used to position audio. * Can be `HRTF` or `equalpower`. * - * @return {Howl/Object} Returns self or current panner attributes. + * @return {Howl|Object} Returns self or current panner attributes. */ Howl.prototype.pannerAttr = function() { var self = this; @@ -459,7 +459,7 @@ if (typeof args[0] === 'object') { o = args[0]; - // Set the grou's panner attribute values. + // Set the groups panner attribute values. if (typeof id === 'undefined') { if (!o.pannerAttr) { o.pannerAttr = { @@ -545,7 +545,7 @@ /** * Add new properties to the core Sound init. - * @param {Function} _super Core Sound init method. + * @param {Function} _super - Core Sound init method. * @return {Sound} */ Sound.prototype.init = (function(_super) { @@ -573,7 +573,7 @@ /** * Override the Sound.reset method to clean up properties from the spatial plugin. - * @param {Function} _super Sound reset method. + * @param {Function} _super - Sound reset method. * @return {Sound} */ Sound.prototype.reset = (function(_super) { @@ -609,8 +609,8 @@ /** * Create a new panner node and save it on the sound. - * @param {Sound} sound Specific sound to setup panning on. - * @param {String} type Type of panner to create: 'stereo' or 'spatial'. + * @param {Sound} sound - Specific sound to setup panning on. + * @param {String} type - Type of panner to create: 'stereo' or 'spatial'. */ var setupPanner = function(sound, type) { type = type || 'spatial';