JiboOs/docs/sound/Sound.js

/**
 * Callback when sound is loaded.
 * @callback jibo.sound.Sound~loadedCallback
 * @param {Error} err The callback error.
 * @param {jibo.sound.Sound} sound The instance of new sound.
 */

/**
 * Callback when sound is completed.
 * @callback jibo.sound.Sound~completeCallback
 * @param {jibo.sound.Sound} sound The instance of sound.
 */

/**
 * Represents a single sound element. Can be used to play, pause, etc. sound instances.
 *
 * @class Sound
 * @memberof jibo.sound
 * @param {jibo.sound.SoundContext} [context] The context.
 * @param {ArrayBuffer|String|Object} options Either the path or url to the source file.
 *        or the object of options to use.
 * @param {ArrayBuffer|String} [options.src] If `options` is an object, the source of file.
 * @param {Boolean} [options.autoPlay=false] true to play after loading.
 * @param {Boolean} [options.preload=false] true to immediately start preloading.
 * @param {Boolean} [options.block=false] true to only play one instance of the sound at a time.
 * @param {Number} [options.volume=1] The amount of volume 1 = 100%.
 * @param {Boolean} [options.useXHR=false] true to use XMLHttpRequest to load the sound. Default is false, loaded with NodeJS's `fs` module.
 * @param {Number} [options.panning=0] The panning amount from -1 (left) to 1 (right).
 * @param {jibo.sound.Sound~completeCallback} [options.complete=null] Global complete callback when play is finished.
 * @param {jibo.sound.Sound~loadedCallback} [options.loaded=null] Call when finished loading.
 * @param {Boolean} [options.loop=false] true to loop the audio playback.
 */

        /**
         * Reference to the sound context.
         * @name jibo.sound.Sound#_context
         * @type {SoundContext}
         * @private
         */

        /**
         * Reference to the WebAudio API AudioContext.
         * @name jibo.sound.Sound#_ctx
         * @type {AudioContext}
         * @private
         */

        /**
         * Instance of the chain builder.
         * @name jibo.sound.Sound#_chain
         * @type {ChainBuilder}
         * @private
         */

        /**
         * `true` if the buffer is loaded.
         * @name jibo.sound.Sound#isLoaded
         * @type {Boolean}
         * @default false
         */

        /**
         * `true` if the sound is currently being played.
         * @name jibo.sound.Sound#isPlaying
         * @type {Boolean}
         * @default false
         * @readOnly
         */

        /**
         * true to start playing immediate after load.
         * @name jibo.sound.Sound#autoPlay
         * @type {Boolean}
         * @private
         * @default false
         * @readOnly
         */

        /**
         * `true` to block successive plays.
         * @name jibo.sound.Sound#block
         * @type {Boolean}
         * @default false
         */

        /**
         * `true` to immediately start preloading.
         * @name jibo.sound.Sound#preload
         * @type {Boolean}
         * @default false
         * @readOnly
         */

        /**
         * Callback when finished playing.
         * @name jibo.sound.Sound#complete
         * @type {jibo.sound.Sound~completeCallback}
         * @default false
         */

        /**
         * Callback when load is finished.
         * @type {jibo.sound.Sound~loadedCallback}
         * @name jibo.sound.Sound#loaded
         * @readOnly
         */

        /**
         * The file source to load.
         * @name jibo.sound.Sound#src
         * @type {String}
         * @readOnly
         */

        /**
         * The file buffer to load.
         * @name jibo.sound.Sound#srcBuffer
         * @type {ArrayBuffer}
         * @readOnly
         */

        /**
         * `true` to use XMLHttpRequest object to load.
         * Default is to use NodeJS's fs module to read the sound.
         * @name jibo.sound.Sound#useXHR
         * @type {Boolean}
         * @default false
         */

        /**
         * The collection of instances being played.
         * @name jibo.sound.Sound#_instances
         * @type {Array<SoundInstance>}
         * @private
         */

    /**
     * Starts the preloading of sound.
     * @method jibo.sound.Sound#_beginPreload
     * @private
     */

    /**
     * Destructor, safer to use `SoundPlugin.remove(alias)` to remove this sound.
     * @private
     * @method jibo.sound.Sound#destroy
     */

    /**
     * Getter of the chain nodes.
     * @name jibo.sound.Sound#nodes
     * @type {Object}
     * @private
     * @readOnly
     */

    /**
     * Gets and sets the volume.
     * @name jibo.sound.Sound#volume
     * @type {Number}
     */

    /**
     * Gets and sets the looping.
     * @name jibo.sound.Sound#loop
     * @type {Boolean}
     */

    /**
     * Gets and sets the buffer.
     * @name jibo.sound.Sound#buffer
     * @type {AudioBuffer}
     */

    /**
     * Gets and sets the panning -1 (full left pan) and 1 (full right pan).
     * @name jibo.sound.Sound#panning
     * @type {Number}
     * @default 0
     */

    /**
     * Gets the list of instances that are currently being played of this sound.
     * @name jibo.sound.Sound#instances
     * @type {Array<SoundInstance>}
     * @readOnly
     */

    /**
     * Plays the sound.
     * @method jibo.sound.Sound#play
     * @param {jibo.sound.Sound~completeCallback|object} options Either completed function or play options.
     * @param {Number} [options.offset=0] time when to play the sound.
     * @param {jibo.sound.Sound~completeCallback} [options.complete] Callback when complete.
     * @param {jibo.sound.Sound~loadedCallback} [options.loaded] If the sound isn't already preloaded, callback when
     *        the audio has completely finished loading and decoded.
     * @return {SoundInstance} Current playing instance.
     */

    /**
     * Sound instance completed.
     * @method jibo.sound.Sound#_onComplete
     * @private
     * @param {jibo.sound.SoundInstance} instance
     */

    /**
     * Stops all the instances of this sound from playing.
     * @method jibo.sound.Sound#stop
     * @return {jibo.sound.Sound} Instance of this sound.
     */

    /**
     * Stops all the instances of this sound from playing.
     * @method jibo.sound.Sound#pause
     * @return {jibo.sound.Sound} Instance of this sound.
     */

    /**
     * Stops all the instances of this sound from playing
     * @method jibo.sound.Sound#stop
     * @return {jibo.sound.Sound} Instance of this sound.
     */

    /**
     * Removes all instances.
     * @method jibo.sound.Sound#_removeInstances
     * @private
     */

    /**
     * Loads a sound using XHMLHttpRequest object.
     * @method jibo.sound.Sound#loadUrl
     * @private
     */

    /**
     * Loads using the file system (NodeJS's fs module).
     * @method jibo.sound.Sound#loadPath
     * @private
     */

    /**
     * Decodes the array buffer.
     * @method jibo.sound.Sound#decode
     * @param {ArrayBuffer} arrayBuffer From load.
     * @private
     */