WebAudioPlugin Class
Play sounds using Web Audio in the browser. The WebAudio plugin has been successfully tested with:
- Google Chrome, version 23+ on OS X and Windows
- Safari 6+ on OS X
- Mobile Safari on iOS 6+
The WebAudioPlugin is currently the default plugin, and will be used anywhere that it is supported. Currently Chrome and Safari offer support. Firefox and Android Chrome both offer support for web audio in upcoming releases. To change plugin priority, check out the Sound API registerPlugins method.
Known Browser and OS issues for Web Audio Plugin
Firefox 25
- mp3 audio files do not load properly on all windows machines, reported here. For this reason it is recommended to pass ogg file first until this bug is resolved, if possible.
Webkit (Chrome and Safari)
- AudioNode.disconnect does not always seem to work. This can cause the file size to grow over time if you are playing a lot of audio files.
iOS 6 limitations
- Sound is initially muted and will only unmute through play being called inside a user initiated event (touch/click).
- Despite suggestions to the opposite, we have relative control over audio volume through the gain nodes.
- A bug exists that will distort uncached audio when a video element is present in the DOM.
Constructor
WebAudioPlugin
()
Item Index
Methods
- addPreloadResults
- compatibilitySetUp
- create
- generateCapabiities static
- getVolume
- handlePreloadComplete
- init
- isFileXHRSupported static
- isPreloadComplete
- isPreloadStarted
- isSupported static
- playEmptySound
- preload
- register
- removeAllSounds
- removeFromPreload deprecated
- removeSound
- setMute
- setVolume
- updateVolume
Properties
Methods
addPreloadResults
-
src
Add loaded results to the preload object hash.
Parameters:
-
src
StringThe sound URI to unload.
Returns:
compatibilitySetUp
()
protected
Set up compatibility if only deprecated web audio calls are supported. See http://www.w3.org/TR/webaudio/#DeprecationNotes Needed so we can support new browsers that don't support deprecated calls (Firefox) as well as old browsers that don't support new calls.
create
-
src
Create a sound instance. If the sound has not been preloaded, it is internally preloaded here.
Parameters:
-
src
StringThe sound source to use.
Returns:
generateCapabiities
()
protected
static
Determine the capabilities of the plugin. Used internally. Please see the Sound API getCapabilities method for an overview of plugin capabilities.
getVolume
()
Get the master volume of the plugin, which affects all SoundInstances.
Returns:
handlePreloadComplete
()
protected
Handles internal preload completion.
init
()
protected
An initialization function run by the constructor
isFileXHRSupported
()
Boolean
protected
static
Determine if XHR is supported, which is necessary for web audio.
Returns:
isPreloadComplete
-
src
Checks if preloading has finished for a specific source.
Parameters:
-
src
StringThe sound URI to load.
Returns:
isPreloadStarted
-
src
Checks if preloading has started for a specific source. If the source is found, we can assume it is loading, or has already finished loading.
Parameters:
-
src
StringThe sound URI to check.
Returns:
isSupported
()
Boolean
static
Determine if the plugin can be used in the current browser/OS.
Returns:
playEmptySound
()
Plays an empty sound in the web audio context. This is used to enable web audio on iOS devices, as they require the first sound to be played inside of a user initiated event (touch/click). This is called when WebAudioPlugin is initialized (by Sound initializeDefaultPlugins for example).
Example
function handleTouch(event) {
createjs.WebAudioPlugin.playEmptySound();
}
preload
-
src
-
instance
-
basePath
Internally preload a sound. Loading uses XHR2 to load an array buffer for use with WebAudio.
register
-
src
-
instances
Pre-register a sound for preloading and setup. This is called by Sound.
Note that WebAudio provides a Loader
instance, which PreloadJS
can use to assist with preloading.
Parameters:
Returns:
removeAllSounds
-
src
Remove all sounds added using register. Note this does not cancel a preload.
Parameters:
-
src
StringThe sound URI to unload.
removeFromPreload
-
src
Remove a source from our preload list. Note this does not cancel a preload.
Parameters:
-
src
StringThe sound URI to unload.
removeSound
-
src
Remove a sound added using register. Note this does not cancel a preload.
Parameters:
-
src
StringThe sound URI to unload.
setMute
-
value
Mute all sounds via the plugin.
Parameters:
Returns:
setVolume
-
value
Set the master volume of the plugin, which affects all SoundInstances.
Parameters:
-
value
NumberThe volume to set, between 0 and 1.
Returns:
updateVolume
()
protected
Set the gain value for master audio. Should not be called externally.
Properties
arrayBuffers
Object
protected
An object hash used internally to store ArrayBuffers, indexed by the source URI used to load it. This
prevents having to load and decode audio files more than once. If a load has been started on a file,
arrayBuffers[src]
will be set to true. Once load is complete, it is set the the loaded
ArrayBuffer instance.
capabilities
Object
protected
static
The capabilities of the plugin. This is generated via the WebAudioPlugin/generateCapabilities:method method and is used internally.
Default: null
context
AudioContext
The web audio context, which WebAudio uses to play audio. All nodes that interact with the WebAudioPlugin need to be created within this context.
dynamicsCompressorNode
AudioNode
A DynamicsCompressorNode, which is used to improve sound quality and prevent audio distortion according to
http://www.w3.org/TR/webaudio/#DynamicsCompressorNode. It is connected to context.destination
.
gainNode
AudioGainNode
A GainNode for controlling master volume. It is connected to dynamicsCompressorNode.
panningModel
Number / String
protected
Value to set panning model to equal power for SoundInstance. Can be "equalpower" or 0 depending on browser implementation.