initial commit

docs/sound/ChainBuilder.js

@@ -0,0 +1,79 @@
+/**
+ * @class ChainBuilder
+ * @private
+ * @param {AudioContext} audioContext The audio context.
+ */
+
+    /**
+     * Cleans up.
+     * @method ChainBuilder#destroy
+     */
+
+    /**
+     * Gets the nodes.
+     * @method ChainBuilder#nodes
+     * @return {Object}
+     */
+
+    /**
+     * Gets the first node.
+     * @method ChainBuilder#first
+     * @return {Object}
+     */
+
+    /**
+     * Gets the last node.
+     * @method ChainBuilder#last
+     * @return {Object}
+     */
+
+    /**
+     * Adds a node to the chain.
+     * @method ChainBuilder#_addNode
+     * @private
+     * @param {*} node
+     * @param {*} properties
+     */
+
+    /**
+     * Clones the bufferSource. Used just before playing a sound.
+     * @method ChainBuilder#cloneBufferSource
+     * @returns {AudioBufferSourceNode} The clone AudioBufferSourceNode.
+     */
+
+    /**
+     * Adds a bufferSource.
+     * @method ChainBuilder#bufferSrouce
+     * @param {Object} [properties] Properties to set in the created node.
+     */
+
+    /**
+     * Adds a createMediaStreamSource.
+     * @method ChainBuilder#mediaStreamSource
+     * @param {Object} [properties] Properties to set in the created node.
+     */
+
+    /**
+     * Adds a createMediaElementSource.
+     * @method ChainBuilder#mediaElementSource
+     * @param  {HTMLElement} element    The element to add.
+     * @param {Object} [properties] Properties to set in the created node.
+     */
+
+    /**
+     * Adds a panner.
+     * @method ChainBuilder#panner
+     * @param {Object} [properties] Properties to set in the created node.
+     */
+
+    /**
+     * Adds an analyser.
+     * @method ChainBuilder#analyser
+     * @param {Object} [properties] Properties to set in the created node.
+     */
+
+    /**
+     * Adds a gainNode.
+     * @method ChainBuilder#gainNode
+     * @param {Object} [properties] Properties to set in the created node.
+     */

docs/sound/Sound.js

@@ -0,0 +1,248 @@
+/**
+ * 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
+     */

docs/sound/SoundContext.js

@@ -0,0 +1,52 @@
+/**
+ * @description Main class to handle webkit audio.
+ *
+ * @class SoundContext
+ * @memberof jibo.sound
+ */
+
+        /**
+         * The instance of the AudioContext for WebAudio API.
+         * @private
+         * @property {AudioContext} _ctx
+         */
+
+    /**
+     * The WebAudio API AudioContext object.
+     * @property {AudioContext} context
+     * @private
+     * @name SoundContext#context
+     * @type {AudioContext}
+     */
+
+    /**
+     * Sets the muted state.
+     * @type {Boolean}
+     * @name SoundContext#muted
+     * @default false
+     */
+
+    /**
+     * Sets the volume from 0 to 1.
+     * @type {Number}
+     * @name SoundContext#volume
+     * @default 1
+     */
+
+    /**
+     * Pauses all sounds.
+     * @type {Boolean}
+     * @name SoundContext#paused
+     * @default false
+     */
+
+    /**
+     * Returns the entry node in the master node chains.
+     * @private
+     */
+
+    /**
+     * Toggles the muted state.
+     * @method SoundContext#toggleMute
+     * @return {Boolean} The current muted state.
+     */

docs/sound/SoundInstance.js

@@ -0,0 +1,83 @@
+    /**
+     * Recycle instance, because they will be created many times.
+     * @type {Array}
+     * @name jibo.sound.SoundInstance._pool
+     * @static
+     * @private
+     */
+
+    /**
+     * Recycle instance, because they will be created many times.
+     * @method jibo.sound.SoundInstance.create
+     * @static
+     * @private
+     */
+
+        /**
+         * The source node chain.
+         * @type {ChainBuilder}
+         * @name jibo.sound.SoundInstance#_chain
+         * @private
+         */
+
+        /**
+         * The starting time.
+         * @type {int}
+         * @name jibo.sound.SoundInstance#_startTime
+         * @private
+         */
+
+        /**
+         * true if paused.
+         * @type {Boolean}
+         * @name jibo.sound.SoundInstance#_paused
+         * @private
+         */
+
+        /**
+         * The time in milliseconds to wait.
+         * @type {int}
+         * @name jibo.sound.SoundInstance#_currentPosition
+         * @private
+         */
+
+    /**
+     * Initializes the instance.
+     * @method jibo.sound.SoundInstance#init
+     * @private
+     */
+
+    /**
+     * Stops the instance.
+     * @method jibo.sound.SoundInstance#stop
+     */
+
+    /**
+     * Plays the sound.
+     * @method jibo.sound.SoundInstance#play
+     * @param {Number} [offset=0] Number of seconds to offset playing.
+     */
+
+    /**
+     * Pauses the sound.
+     * @type {Boolean}
+     * @name jibo.sound.SoundInstance#paused
+     */
+
+    /**
+     * Callback when completed.
+     * @method jibo.sound.SoundInstance#_onComplete
+     * @private
+     */
+
+    /**
+     * Don't use after this.
+     * @method jibo.sound.SoundInstance#destroy
+     */
+
+    /**
+     * To string method for instance.
+     * @method SoundInstance#toString
+     * @return {String} The string representation of instance.
+     * @private
+     */

docs/sound/SoundPlugin.js

@@ -0,0 +1,163 @@
+/**
+ * @description Manages the playback of sounds.
+ * @class SoundLibrary
+ * @memberof jibo.sound
+ */
+
+    /**
+     * Sets the base path to prepend to all relative sound paths.
+     * @name jibo.sound#basePath
+     * @type {String}
+     */
+
+    /**
+     * Sets the base URL to prepend to all remote sound paths.
+     * @name jibo.sound#baseUrl
+     * @type {String}
+     */
+
+        /**
+         * The global context to use.
+         * @name jibo.sound#_context
+         * @type {jibo.sound.SoundContext}
+         * @private
+         */
+
+        /**
+         * The map of all sounds by alias.
+         * @name jibo.sound#_sounds
+         * @type {Object}
+         * @private
+         */
+
+    /**
+     * The global context to use.
+     * @name jibo.sound#context
+     * @readOnly
+     * @type {jibo.sound.SoundContext}
+     * @private
+     */
+
+    /**
+     * Adds a new sound by alias.
+     * @method jibo.sound#add
+     * @param {String} alias The sound alias reference.
+     * @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.
+     * @return {jibo.sound.Sound} Instance to the Sound object.
+     */
+
+    /**
+     * Adds multiple sounds.
+     * @method jibo.sound#addMap
+     * @param {Object} alias Map of sounds to add, the key is the alias, the value is the
+     *        string, ArrayBuffer or the list of options (see `add` method for options).
+     * @param {Object|String|ArrayBuffer} globalOptions The default options for all sounds.
+     *        if a property is defined, it will use the local property instead.
+     * @return {jibo.sound.Sound} Instance to the Sound object.
+     */
+
+    /**
+     * Removes a sound by alias.
+     * @method jibo.sound#remove
+     * @param {String} alias The sound alias reference.
+     * @return {jibo.sound} Instance for chaining.
+     */
+
+    /**
+     * Pauses any playing sounds.
+     * @method jibo.sound#pauseAll
+     * @return {jibo.sound} Instance for chaining.
+     */
+
+    /**
+     * Resumes any sounds.
+     * @method jibo.sound#resumeAll
+     * @return {jibo.sound} Instance for chaining.
+     */
+
+    /**
+     * Mutes all playing sounds.
+     * @method jibo.sound#muteAll
+     * @return {jibo.sound} Instance for chaining.
+     */
+
+    /**
+     * Unmutes all playing sounds.
+     * @method jibo.sound#unmuteAll
+     * @return {jibo.sound} Instance for chaining.
+     */
+
+    /**
+     * Stops and removes all sounds. They cannot be used after this.
+     * @method jibo.sound#removeAll
+     * @return {jibo.sound} Instance for chaining.
+     */
+
+    /**
+     * Stops all sounds.
+     * @method jibo.sound#stopAll
+     * @return {jibo.sound} Instance for chaining.
+     */
+
+    /**
+     * Checks if a sound by alias exists.
+     * @method jibo.sound#exists
+     * @param {String} alias Check for alias.
+     * @return {Boolean} true if the sound exists.
+     */
+
+    /**
+     * Gets a sound.
+     * @method jibo.sound#sound
+     * @param {String} alias The sound alias reference.
+     * @return {jibo.sound.Sound|null} Sound object or `null` if it doew not exist.
+     */
+
+    /**
+     * Plays a sound.
+     * @method jibo.sound#play
+     * @param {String} alias The sound alias reference.
+     * @param {Object|Function} options The options or callback when done.
+     * @param {Function} [options.complete] When completed.
+     * @param {Function} [options.loaded] If not already preloaded, callback when finishes load.
+     * @param {Number} [options.offset=0] Start time offset.
+     * @return {jibo.sound.SoundInstance|null} The sound instance, this cannot be reused
+     *         after it is done playing. Returns `null` if the sound has not yet loaded.
+     */
+
+    /**
+     * Stops a sound.
+     * @method jibo.sound#stop
+     * @param {String} alias The sound alias reference.
+     * @return {jibo.sound.Sound|null} Sound object or `null` if it does not exist.
+     */
+
+    /**
+     * Pauses a sound.
+     * @method jibo.sound#pause
+     * @param {String} alias The sound alias reference.
+     * @return {jibo.sound.Sound|null} Sound object or `null` if it does not exist.
+     */
+
+    /**
+     * Resumes a sound.
+     * @method jibo.sound#resume
+     * @param {String} alias The sound alias reference.
+     * @return {jibo.sound.Sound|null} Instance for chaining or `null` if it does not exist.
+     */
+
+    /**
+     * Destroys the sound module.
+     * @method jibo.sound#destroy
+     * @private
+     */

docs/sound/SoundUtils.js

@@ -0,0 +1,34 @@
+/**
+ * Utilities that work with sounds.
+ * @class SoundUtils
+ * @memberof jibo.sound
+ */
+
+    /**
+     * Create a new sound for a sine wave-based tone.
+     * @method jibo.sound.SoundUtils.sineTone
+     * @param {jibo.sound.SoundContext} soundContext
+     * @param {Number} hertz Frequency of sound.
+     * @param {Number} seconds Duration of sound in seconds.
+     * @return {jibo.sound.Sound} New sound.
+     */
+
+    /**
+     * Create a new "Audio" stream based on given audio path and project uri; returns the audio object.
+     * @method jibo.sound.SoundUtils.playOnce
+     * @static
+     * @param {String} fileName Full path of the file to play.
+     * @param {Function} callback Callback when complete.
+     * @return {string} New audio element alias.
+     */
+
+    /**
+     * Setup sounds to play automatically when hitting a frame label. For instance, a frame label of "playAudio-pop"
+     * will play the sound alias "pop" and "playAudio-breeze-1" will play the sound alias "breeze".
+     * @method jibo.sound.SoundUtils.addClipSounds
+     * @static
+     * @param {PIXI.animate.MovieClip} clip MovieClip to add sounds.
+     * @param {String} [labelPrefix=playAudio] Label name should start with this.
+     * @param {String} [separator=-] The separater between the labelPrefix, sound alias and the unique id (for playing multiple times)
+     * @return {PIXI.animate.MovieClip} MoveClip
+     */

docs/sound/index.js

@@ -0,0 +1,4 @@
+/**
+ * Playing sound files with WebAudio API
+ * @namespace jibo.sound
+ */

docs/sound/tasks/SoundTask.js

@@ -0,0 +1,68 @@
+/**
+ * Internal class for dealing with async load assets through Loader.
+ * @class SoundTask
+ * @extends jibo.loader.Task
+ * @memberof jibo.loader
+ * @constructor
+ * @private
+ * @param {Object} asset The data properties.
+ * @param {String} asset.src The source.
+ * @param {Boolean} [asset.cache=false] true to cache the result.
+ * @param {String} [asset.id] ID of asset.
+ */
+
+    /**
+     * Tests if tasks should be run.
+     * @method jibo.loader.SoundTask.test
+     * @static
+     * @param {Object} asset The asset to check.
+     * @return {Boolean} true if the asset is compatible with this asset.
+     */
+
+        /**
+         * The source URL to load.
+         * @type {String}
+         * @name jibo.loader.SoundTask#src
+         */
+
+        /**
+         * true to block the audio from being played more than once at a time.
+         * @type {Boolean}
+         * @name jibo.loader.SoundTask#block
+         */
+
+        /**
+         * The initial volume of the sound (0 to 1).
+         * @type {Number}
+         * @name jibo.loader.SoundTask#volume
+         */
+
+        /**
+         * The panning from -1 (left) to 1 (right). Default is 0 (center).
+         * @type {Number}
+         * @name jibo.loader.SoundTask#panning
+         */
+
+        /**
+         * true if the sound should play.
+         * @type {Boolean}
+         * @name jibo.loader.SoundTask#loop
+         */
+
+        /**
+         * true to start playing the sound immediately after loading.
+         * @type {Boolean}
+         * @name jibo.loader.SoundTask#autoPlay
+         */
+
+        /**
+         * true to use XMLHttpRequest to download file.
+         * @type {Boolean}
+         * @name jibo.loader.SoundTask#useXHR
+         */
+
+    /**
+     * Starts the task.
+     * @method  jibo.loader.SoundTask#start
+     * @param  {jibo.loader.Task~completeCallback} callback Callback when finished.
+     */