Sound Class
The Sound class is the public API for creating sounds, controlling the overall sound levels, and managing plugins. All Sound APIs on this class are static.
Registering and Preloading
Before you can play a sound, it must be registered. You can do this with registerSound,
or register multiple sounds using registerManifest. If you don't register a
sound prior to attempting to play it using play or create it using createInstance,
the sound source will be automatically registered but playback will fail as the source will not be ready. If you use
PreloadJS, this is handled for you when the sound is
preloaded. It is recommended to preload sounds either internally using the register functions or externally using
PreloadJS so they are ready when you want to use them.
Playback
To play a sound once it's been registered and preloaded, use the play method.
This method returns a SoundInstance which can be paused, resumed, muted, etc.
Please see the SoundInstance documentation for more on the instance control APIs.
Plugins
By default, the WebAudioPlugin or the HTMLAudioPlugin
are used (when available), although developers can change plugin priority or add new plugins (such as the
provided FlashPlugin). Please see the Sound API
methods for more on the playback and plugin APIs. To install plugins, or specify a different plugin order, see
Sound/installPlugins.
Example
createjs.Sound.registerPlugins([createjs.WebAudioPlugin, createjs.FlashPlugin]);
createjs.Sound.addEventListener("fileload", createjs.proxy(this.loadHandler, (this));
createjs.Sound.registerSound("path/to/mySound.mp3|path/to/mySound.ogg", "sound");
function loadHandler(event) {
// This is fired for each sound that is registered.
var instance = createjs.Sound.play("sound"); // play using id. Could also use full source path or event.src.
instance.addEventListener("complete", createjs.proxy(this.handleComplete, this));
instance.volume = 0.5;
}
The maximum number of concurrently playing instances of the same sound can be specified in the "data" argument of registerSound. Note that if not specified, the active plugin will apply a default limit. Currently HTMLAudioPlugin sets a default limit of 2, while WebAudioPlugin and FlashPlugin set a default limit of 100.
createjs.Sound.registerSound("sound.mp3", "soundId", 4);
Sound can be used as a plugin with PreloadJS to help preload audio properly. Audio preloaded with PreloadJS is automatically registered with the Sound class. When audio is not preloaded, Sound will do an automatic internal load. As a result, it may not play immediately the first time play is called. Use the Sound/fileload event to determine when a sound has finished internally preloading. It is recommended that all audio is preloaded before it is played.
createjs.PreloadJS.installPlugin(createjs.Sound);
Mobile Safe Approach
Mobile devices require sounds to be played inside of a user initiated event (touch/click) in varying degrees.
As of SoundJS 0.4.1, you can launch a site inside of a user initiated event and have audio playback work. To
enable as broadly as possible, the site needs to setup the Sound plugin in its initialization (for example via
createjs.Sound.initializeDefaultPlugins();
), and all sounds need to be played in the scope of the
application. See the MobileSafe demo for a working example.
Example
document.getElementById("status").addEventListener("click", handleTouch, false); // works on Android and iPad
function handleTouch(event) {
document.getElementById("status").removeEventListener("click", handleTouch, false); // remove the listener
var thisApp = new myNameSpace.MyApp(); // launch the app
}
Known Browser and OS issues
IE 9 HTML Audio limitations
- There is a delay in applying volume changes to tags that occurs once playback is started. So if you have muted all sounds, they will all play during this delay until the mute applies internally. This happens regardless of when or how you apply the volume change, as the tag seems to need to play to apply it.
- MP3 encoding will not always work for audio tags, particularly in Internet Explorer. We've found default encoding with 64kbps works.
- There is a limit to how many audio tags you can load and play at once, which appears to be determined by hardware and browser settings. See HTMLAudioPlugin.MAX_INSTANCES for a safe estimate.
- 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.
- Safari requires Quicktime to be installed for audio playback.
- 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 control over audio volume through our gain nodes.
- A bug exists that will distort un-cached web audio when a video element is present in the DOM.
- Note HTMLAudioPlugin is not supported on iOS by default. See HTMLAudioPlugin for more details.
Android HTML Audio limitations
- We have no control over audio volume. Only the user can set volume on their device.
- We can only play audio inside a user event (touch/click). This currently means you cannot loop sound or use a delay.
Item Index
Methods
- _dispatchEvent
- addEventListener
- beginPlaying static
- createInstance
- dispatchEvent
- getCapabilities static
- getCapability static
- getMute static
- getPreloadHandlers static
- getSrcById static
- getVolume static
- hasEventListener
- initialize
- initializeDefaultPlugins
- initLoad static
- isReady static
- loadComplete
- mute static deprecated
- off
- on
- parsePath
- play static
- playFinished static
- playInstance static
- proxy static deprecated
- registerManifest static
- registerPlugin static
- registerPlugins static
- registerSound static
- removeAllEventListeners
- removeAllSounds static
- removeEventListener
- removeManifest static
- removeSound static
- sendFileLoadEvent static
- setMute static
- setVolume static
- stop static
- toString
Properties
- _captureListeners
- _listeners
- activePlugin static
- AUDIO_TIMEOUT static
- defaultInterruptBehavior static
- defaultSoundInstance static
- DELIMITER static
- EXTENSION_MAP
- FILE_PATTERN static
- idHash static
- instances static
- INTERRUPT_ANY static
- INTERRUPT_EARLY static
- INTERRUPT_LATE static
- INTERRUPT_NONE static
- lastID static
- masterMute static
- masterVolume
- onLoadComplete deprecated
- PLAY_FAILED static
- PLAY_FINISHED static
- PLAY_INITED static
- PLAY_INTERRUPTED static
- PLAY_SUCCEEDED static
- pluginsRegistered static
- preloadHash static
- SUPPORTED_EXTENSIONS
Events
Methods
_dispatchEvent
-
eventObj
-
eventPhase
addEventListener
-
type
-
listener
-
[useCapture]
Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.
Example
displayObject.addEventListener("click", handleClick);
function handleClick(event) {
// Click happened.
}
Parameters:
-
type
StringThe string type of the event.
-
listener
Function | ObjectAn object with a handleEvent method, or a function that will be called when the event is dispatched.
-
[useCapture]
Boolean optionalFor events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
beginPlaying
-
instance
-
[interrupt=none]
-
[offset]
-
[loop=0]
-
[volume]
-
[pan=instance.pan]
Begin playback. This is called immediately or after delay by playInstance.
Parameters:
-
instance
SoundInstanceA SoundInstance to begin playback.
-
[interrupt=none]
String optionalHow this sound interrupts other instances with the same source. Defaults to Sound/INTERRUPTNONE:property. Interrupts are defined as
INTERRUPT
TYPE constants on Sound. -
[offset]
Number optionalTime in milliseconds into the sound to begin playback. Defaults to the current value on the instance.
-
[loop=0]
Number optionalThe number of times to loop the audio. Use 0 for no loops, and -1 for an infinite loop.
-
[volume]
Number optionalThe volume of the sound between 0 and 1. Defaults to the current value on the instance.
-
[pan=instance.pan]
Number optionalThe pan of the sound between -1 and 1. Defaults to current instance value.
Returns:
createInstance
-
src
Creates a SoundInstance using the passed in src. If the src does not have a supported extension or if there is no available plugin, a defaultSoundInstance will be returned that can be called safely but does nothing.
Example
var myInstance = null;
createjs.Sound.addEventListener("fileload", handleLoad);
createjs.Sound.registerSound("myAudioPath/mySound.mp3", "myID", 3);
function handleLoad(event) {
myInstance = createjs.Sound.createInstance("myID");
// alternately we could call the following
myInstance = createjs.Sound.createInstance("myAudioPath/mySound.mp3");
}
Parameters:
-
src
StringThe src or ID of the audio.
Returns:
dispatchEvent
-
eventObj
-
[target]
Dispatches the specified event to all listeners.
Example
// Use a string event
this.dispatchEvent("complete");
// Use an Event instance
var event = new createjs.Event("progress");
this.dispatchEvent(event);
Parameters:
-
eventObj
Object | String | EventAn object with a "type" property, or a string type. While a generic object will work, it is recommended to use a CreateJS Event instance. If a string is used, dispatchEvent will construct an Event instance with the specified type.
-
[target]
Object optionalThe object to use as the target property of the event object. This will default to the dispatching object. This parameter is deprecated and will be removed.
Returns:
getCapabilities
()
Object
static
Get the active plugins capabilities, which help determine if a plugin can be used in the current environment, or if the plugin supports a specific feature. Capabilities include:
- panning: If the plugin can pan audio from left to right
- volume; If the plugin can control audio volume.
- mp3: If MP3 audio is supported.
- ogg: If OGG audio is supported.
- wav: If WAV audio is supported.
- mpeg: If MPEG audio is supported.
- m4a: If M4A audio is supported.
- mp4: If MP4 audio is supported.
- aiff: If aiff audio is supported.
- wma: If wma audio is supported.
- mid: If mid audio is supported.
- tracks: The maximum number of audio tracks that can be played back at a time. This will be -1 if there is no known limit.
Returns:
getCapability
-
key
Get a specific capability of the active plugin. See getCapabilities for a full list of capabilities.
Example
var maxAudioInstances = createjs.Sound.getCapability("tracks");
Parameters:
-
key
StringThe capability to retrieve
getMute
()
Boolean
static
Returns the global mute value. To get the mute value of an individual instance, use SoundInstance getMute instead.
Example
var masterMute = createjs.Sound.getMute();
Returns:
getPreloadHandlers
()
Object
protected
static
Get the preload rules to allow Sound to be used as a plugin by PreloadJS. Any load calls that have the matching type or extension will fire the callback method, and use the resulting object, which is potentially modified by Sound. This helps when determining the correct path, as well as registering the audio instance(s) with Sound. This method should not be called, except by PreloadJS.
Returns:
- callback: A preload callback that is fired when a file is added to PreloadJS, which provides Sound a mechanism to modify the load parameters, select the correct file format, register the sound, etc.
- types: A list of file types that are supported by Sound (currently supports "sound").
- extensions: A list of file extensions that are supported by Sound (see Sound.SUPPORTED_EXTENSIONS).
getSrcById
-
value
Get the source of a sound via the ID passed in with a register call. If no ID is found the value is returned instead.
Parameters:
-
value
StringThe ID the sound was registered with.
Returns:
getVolume
()
Number
static
Get the master volume of Sound. The master volume is multiplied against each sound's individual volume. To get individual sound volume, use SoundInstance SoundInstance/volume instead.
Example
var masterVolume = createjs.Sound.getVolume();
Returns:
hasEventListener
-
type
Indicates whether there is at least one listener for the specified event type and useCapture
value.
Parameters:
-
type
StringThe string type of the event.
Returns:
initialize
()
protected
Initialization method.
initializeDefaultPlugins
()
Boolean
Initialize the default plugins. This method is automatically called when any audio is played or registered before the user has manually registered plugins, and enables Sound to work without manual plugin setup. Currently, the default plugins are WebAudioPlugin followed by HTMLAudioPlugin.
Example
if (!createjs.initializeDefaultPlugins()) { return; }
Returns:
initLoad
-
src
-
[type]
-
[id]
-
[data]
Process manifest items from PreloadJS. This method is intended for usage by a plugin, and not for direct interaction.
Parameters:
-
src
String | ObjectThe src or object to load. This is usually a string path, but can also be an HTMLAudioElement or similar audio playback object.
-
[type]
String optionalThe type of object. Will likely be "sound" or null.
-
[id]
String optionalAn optional user-specified id that is used to play sounds.
-
[data]
Number | String | Boolean | Object optionalData associated with the item. Sound uses the data parameter as the number of channels for an audio instance, however a "channels" property can be appended to the data object if this property is used for other information. The audio channels will default to 1 if no value is found.
isReady
()
Boolean
static
Determines if Sound has been initialized, and a plugin has been activated.
Example
This example sets up a Flash fallback, but only if there is no plugin specified yet.
if (!createjs.Sound.isReady()) {
createjs.FlashPlugin.BASE_PATH = "../src/SoundJS/";
createjs.Sound.registerPlugins([createjs.WebAudioPlugin, createjs.HTMLAudioPlugin, createjs.FlashPlugin]);
}
Returns:
loadComplete
-
src
Check if a source has been loaded by internal preloaders. This is necessary to ensure that sounds that are not completed preloading will not kick off a new internal preload if they are played.
Example
var mySound = "assetPath/asset0.mp3|assetPath/asset0.ogg";
if(createjs.Sound.loadComplete(mySound) {
createjs.Sound.play(mySound);
}
Parameters:
-
src
StringThe src or id that is being loaded.
Returns:
mute
-
value
REMOVED. Please see setMute.
Parameters:
-
value
BooleanWhether the audio should be muted or not.
off
-
type
-
listener
-
[useCapture]
A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the .on method.
on
-
type
-
listener
-
[scope]
-
[once=false]
-
[data]
-
[useCapture=false]
A shortcut method for using addEventListener that makes it easier to specify an execution scope, have a listener only run once, associate arbitrary data with the listener, and remove the listener.
This method works by creating an anonymous wrapper function and subscribing it with addEventListener. The created anonymous function is returned for use with .removeEventListener (or .off).
Example
var listener = myBtn.on("click", handleClick, null, false, {count:3});
function handleClick(evt, data) {
data.count -= 1;
console.log(this == myBtn); // true - scope defaults to the dispatcher
if (data.count == 0) {
alert("clicked 3 times!");
myBtn.off("click", listener);
// alternately: evt.remove();
}
}
Parameters:
-
type
StringThe string type of the event.
-
listener
Function | ObjectAn object with a handleEvent method, or a function that will be called when the event is dispatched.
-
[scope]
Object optionalThe scope to execute the listener in. Defaults to the dispatcher/currentTarget for function listeners, and to the listener itself for object listeners (ie. using handleEvent).
-
[once=false]
Boolean optionalIf true, the listener will remove itself after the first time it is triggered.
-
[data]
optionalArbitrary data that will be included as the second parameter when the listener is called.
-
[useCapture=false]
Boolean optionalFor events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
Returns:
parsePath
-
value
-
[type]
-
[id]
-
[data]
Parse the path of a sound, usually from a manifest item. Manifest items support single file paths, as well as composite paths using DELIMITER, which defaults to "|". The first path supported by the current browser/plugin will be used.
Parameters:
-
value
StringThe path to an audio source.
-
[type]
String optionalThe type of path. This will typically be "sound" or null.
-
[id]
String optionalThe user-specified sound ID. This may be null, in which case the src will be used instead.
-
[data]
Number | String | Boolean | Object optionalArbitrary data appended to the sound, usually denoting the number of channels for the sound. This method doesn't currently do anything with the data property.
Returns:
play
-
src
-
[interrupt="none"|options]
-
[delay=0]
-
[offset=0]
-
[loop=0]
-
[volume=1]
-
[pan=0]
Play a sound and get a SoundInstance to control. If the sound fails to play, a SoundInstance will still be returned, and have a playState of PLAY_FAILED. Note that even on sounds with failed playback, you may still be able to call SoundInstance play, since the failure could be due to lack of available channels. If the src does not have a supported extension or if there is no available plugin, defaultSoundInstance will be returned, which will not play any audio, but will not generate errors.
Example
createjs.Sound.addEventListener("fileload", handleLoad);
createjs.Sound.registerSound("myAudioPath/mySound.mp3", "myID", 3);
function handleLoad(event) {
createjs.Sound.play("myID");
// alternately we could call the following
var myInstance = createjs.Sound.play("myAudioPath/mySound.mp3", createjs.Sound.INTERRUPT_ANY, 0, 0, -1, 1, 0);
// another alternative is to pass in just the options we want to set inside of an object
var myInstance = createjs.Sound.play("myAudioPath/mySound.mp3", {interrupt: createjs.Sound.INTERRUPT_ANY, loop:-1});
}
Parameters:
-
src
StringThe src or ID of the audio.
-
[interrupt="none"|options]
String | Object optionalHow to interrupt any currently playing instances of audio with the same source, if the maximum number of instances of the sound are already playing. Values are defined as
INTERRUPT_TYPE
constants on the Sound class, with the default defined by defaultInterruptBehavior.
OR
This parameter can be an object that contains any or all optional properties by name, including: interrupt, delay, offset, loop, volume, and pan (see the above code sample). -
[delay=0]
Number optionalThe amount of time to delay the start of audio playback, in milliseconds.
-
[offset=0]
Number optionalThe offset from the start of the audio to begin playback, in milliseconds.
-
[loop=0]
Number optionalHow many times the audio loops when it reaches the end of playback. The default is 0 (no loops), and -1 can be used for infinite playback.
-
[volume=1]
Number optionalThe volume of the sound, between 0 and 1. Note that the master volume is applied against the individual volume.
-
[pan=0]
Number optionalThe left-right pan of the sound (if supported), between -1 (left) and 1 (right).
Returns:
playFinished
-
instance
A sound has completed playback, been interrupted, failed, or been stopped. This method removes the instance from Sound management. It will be added again, if the sound re-plays. Note that this method is called from the instances themselves.
Parameters:
-
instance
SoundInstanceThe instance that finished playback.
playInstance
-
instance
-
[interrupt="none"|options]
-
[delay=0]
-
[offset=instance.offset]
-
[loop=0]
-
[volume]
-
[pan]
Play an instance. This is called by the static API, as well as from plugins. This allows the core class to control delays.
Parameters:
-
instance
SoundInstanceThe SoundInstance to start playing.
-
[interrupt="none"|options]
String | Object optionalHow to interrupt any currently playing instances of audio with the same source, if the maximum number of instances of the sound are already playing. Values are defined as
INTERRUPT_TYPE
constants on the Sound class, with the default defined by Sound/defaultInterruptBehavior.
OR
This parameter can be an object that contains any or all optional properties by name, including: interrupt, delay, offset, loop, volume, and pan (see the above code sample). -
[delay=0]
Number optionalTime in milliseconds before playback begins.
-
[offset=instance.offset]
Number optionalTime into the sound to begin playback in milliseconds. Defaults to the current value on the instance.
-
[loop=0]
Number optionalThe number of times to loop the audio. Use 0 for no loops, and -1 for an infinite loop.
-
[volume]
Number optionalThe volume of the sound between 0 and 1. Defaults to current instance value.
-
[pan]
Number optionalThe pan of the sound between -1 and 1. Defaults to current instance value.
Returns:
proxy
-
method
-
scope
REMOVED. Please use createjs.proxy instead
registerManifest
-
manifest
-
basePath
Register a manifest of audio files for loading and future playback in Sound. It is recommended to register all sounds that need to be played back in order to properly prepare and preload them. Sound does internal preloading when required.
Example
var manifest = [
{src:"asset0.mp3|asset0.ogg", id:"example"}, // Note the Sound.DELIMITER '|'
{src:"asset1.mp3|asset1.ogg", id:"1", data:6},
{src:"asset2.mp3", id:"works"}
];
createjs.Sound.addEventListener("fileload", handleLoad); // call handleLoad when each sound loads
createjs.Sound.registerManifest(manifest, assetPath);
Parameters:
-
manifest
ArrayAn array of objects to load. Objects are expected to be in the format needed for registerSound:
{src:srcURI, id:ID, data:Data, preload:UseInternalPreloader}
with "id", "data", and "preload" being optional. -
basePath
StringSet a path that will be prepending to each src when loading.
Returns:
registerPlugin
-
plugin
Register a Sound plugin. Plugins handle the actual playback of audio. The default plugins are (WebAudioPlugin followed by HTMLAudioPlugin), and are installed if no other plugins are present when the user attempts to start playback or register sound.
Example
createjs.FlashPlugin.BASE_PATH = "../src/SoundJS/";
createjs.Sound.registerPlugin(createjs.FlashPlugin);
To register multiple plugins, use registerPlugins.
Parameters:
-
plugin
ObjectThe plugin class to install.
Returns:
registerPlugins
-
plugins
Register a list of Sound plugins, in order of precedence. To register a single plugin, use registerPlugin.
Example
createjs.FlashPlugin.BASE_PATH = "../src/SoundJS/";
createjs.Sound.registerPlugins([createjs.WebAudioPlugin, createjs.HTMLAudioPlugin, createjs.FlashPlugin]);
Parameters:
-
plugins
ArrayAn array of plugins classes to install.
Returns:
registerSound
-
src
-
[id]
-
[data]
-
[preload=true]
-
basePath
Register an audio file for loading and future playback in Sound. This is automatically called when using PreloadJS. It is recommended to register all sounds that need to be played back in order to properly prepare and preload them. Sound does internal preloading when required.
Example
createjs.Sound.addEventListener("fileload", handleLoad); // add an event listener for when load is completed
createjs.Sound.registerSound("myAudioPath/mySound.mp3|myAudioPath/mySound.ogg", "myID", 3);
Parameters:
-
src
String | ObjectThe source or an Objects with a "src" property
-
[id]
String optionalAn id specified by the user to play the sound later.
-
[data]
Number | Object optionalData associated with the item. Sound uses the data parameter as the number of channels for an audio instance, however a "channels" property can be appended to the data object if it is used for other information. The audio channels will set a default based on plugin if no value is found.
-
[preload=true]
Boolean optionalIf the sound should be internally preloaded so that it can be played back without an external preloader.
-
basePath
StringSet a path that will be prepending to src for loading.
Returns:
removeAllEventListeners
-
[type]
Removes all listeners for the specified type, or all listeners of all types.
Example
// Remove all listeners
displayObject.removeAllEvenListeners();
// Remove all click listeners
displayObject.removeAllEventListeners("click");
Parameters:
-
[type]
String optionalThe string type of the event. If omitted, all listeners for all types will be removed.
removeAllSounds
()
static
Remove all sounds that have been registered with registerSound or registerManifest. Note this will stop playback on all active sound instances before deleting them.
Example
createjs.Sound.removeAllSounds();
removeEventListener
-
type
-
listener
-
[useCapture]
Removes the specified event listener.
Important Note: that you must pass the exact function reference used when the event was added. If a proxy function, or function closure is used as the callback, the proxy/closure reference must be used - a new proxy or closure will not work.
Example
displayObject.removeEventListener("click", handleClick);
removeManifest
-
manifest
Remove a manifest of audio files that have been registered with registerSound or registerManifest. Note this will stop playback on active instances playing this audio before deleting them. Note if you passed in a basePath, you do not need to pass it or add it to the src here.
Example
var manifest = [
{src:"asset0.mp3|asset0.ogg", id:"example"}, // Note the Sound.DELIMITER '|'
{src:"asset1.mp3|asset1.ogg", id:"1", data:6},
{src:"asset2.mp3", id:"works"}
];
createjs.Sound.removeManifest(manifest);
Parameters:
-
manifest
ArrayAn array of objects to remove. Objects are expected to be in the format needed for removeSound:
{srcOrID:srcURIorID}
Returns:
removeSound
-
src
Remove a sound that has been registered with registerSound or registerManifest. Note this will stop playback on active instances playing this sound before deleting them. Note if you passed in a basePath, you do not need to pass it or add assetPath to the src here.
Example
createjs.Sound.removeSound("myAudioPath/mySound.mp3|myAudioPath/mySound.ogg");
createjs.Sound.removeSound("myID");
Returns:
sendFileLoadEvent
-
src
Used by external plugins to dispatch file load events.
Parameters:
-
src
StringA sound file has completed loading, and should be dispatched.
setMute
-
value
Mute/Unmute all audio. Note that muted audio still plays at 0 volume. This global mute value is maintained separately and when set will override, but not change the mute property of individual instances. To mute an individual instance, use SoundInstance setMute instead.
Example
createjs.Sound.setMute(true);
Parameters:
-
value
BooleanWhether the audio should be muted or not.
Returns:
setVolume
-
value
Set the master volume of Sound. The master volume is multiplied against each sound's individual volume. For example, if master volume is 0.5 and a sound's volume is 0.5, the resulting volume is 0.25. To set individual sound volume, use SoundInstance setVolume instead.
Example
createjs.Sound.setVolume(0.5);
Parameters:
-
value
NumberThe master volume value. The acceptable range is 0-1.
stop
()
static
Stop all audio (global stop). Stopped audio is reset, and not paused. To play audio that has been stopped, call SoundInstance.play.
Example
createjs.Sound.stop();
Properties
activePlugin
Object
static
The currently active plugin. If this is null, then no plugin could be initialized. If no plugin was specified, Sound attempts to apply the default plugins: WebAudioPlugin, followed by HTMLAudioPlugin.
AUDIO_TIMEOUT
Number
protected
static
The duration in milliseconds to determine a timeout.
Default: 8000
defaultInterruptBehavior
String
static
Determines the default behavior for interrupting other currently playing instances with the same source, if the maximum number of instances of the sound are already playing. Currently the default is INTERRUPT_NONE but this can be set and will change playback behavior accordingly. This is only used when play is called without passing a value for interrupt.
Default: none
defaultSoundInstance
Object
protected
static
An object that stands in for audio that fails to play. This allows developers to continue to call methods on the failed instance without having to check if it is valid first. The instance is instantiated once, and shared to keep the memory footprint down.
DELIMITER
String
static
The character (or characters) that are used to split multiple paths from an audio source.
Default: |
EXTENSION_MAP
Object
Some extensions use another type of extension support to play (one of them is a codex). This allows you to map that support so plugins can accurately determine if an extension is supported. Adding to this list can help plugins determine more accurately if an extension is supported.
FILE_PATTERN
RegExp
protected
static
The RegExp pattern used to parse file URIs. This supports simple file names, as well as full domain URIs with query strings. The resulting match is: protocol:$1 domain:$2 path:$3 file:$4 extension:$5 query:$6.
instances
Array
protected
static
An array containing all currently playing instances. This allows Sound to control the volume, mute, and playback of all instances when using static APIs like stop and setVolume. When an instance has finished playback, it gets removed via the Sound/finishedPlaying method. If the user replays an instance, it gets added back in via the beginPlaying method.
INTERRUPT_ANY
String
static
The interrupt value to interrupt any currently playing instance with the same source, if the maximum number of instances of the sound are already playing.
Default: any
INTERRUPT_EARLY
String
static
The interrupt value to interrupt the earliest currently playing instance with the same source that progressed the least distance in the audio track, if the maximum number of instances of the sound are already playing.
Default: early
INTERRUPT_LATE
String
static
The interrupt value to interrupt the currently playing instance with the same source that progressed the most distance in the audio track, if the maximum number of instances of the sound are already playing.
Default: late
INTERRUPT_NONE
String
static
The interrupt value to not interrupt any currently playing instances with the same source, if the maximum number of instances of the sound are already playing.
Default: none
masterMute
Boolean
protected
static
The master mute value, which affects all sounds. This is applies to all sound instances. This value can be set through setMute and accessed via getMute.
Default: false
masterVolume
Number
protected
The master volume value, which affects all sounds. Use getVolume and setVolume to modify the volume of all audio.
Default: 1
PLAY_FAILED
String
static
Defines the playState of an instance that failed to play. This is usually caused by a lack of available channels when the interrupt mode was "INTERRUPT_NONE", the playback stalled, or the sound could not be found.
Default: playFailed
PLAY_FINISHED
String
static
Defines the playState of an instance that completed playback.
Default: playFinished
PLAY_INITED
String
static
Defines the playState of an instance that is still initializing.
Default: playInited
PLAY_INTERRUPTED
String
static
Defines the playState of an instance that was interrupted by another instance.
Default: playInterrupted
PLAY_SUCCEEDED
String
static
Defines the playState of an instance that is currently playing or paused.
Default: playSucceeded
pluginsRegistered
Boolean
protected
static
Determines if the plugins have been registered. If false, the first call to play() will instantiate the default plugins (WebAudioPlugin, followed by HTMLAudioPlugin). If plugins have been registered, but none are applicable, then sound playback will fail.
Default: false
preloadHash
Object
protected
static
An object hash that stores preloading sound sources via the parsed source that is passed to the plugin. Contains the source, id, and data that was passed in by the user. Parsed sources can contain multiple instances of source, id, and data.
SUPPORTED_EXTENSIONS
ArrayString
A list of the default supported extensions that Sound will try to play. Plugins will check if the browser can play these types, so modifying this list before a plugin is initialized will allow the plugins to try to support additional media types.
NOTE this does not currently work for FlashPlugin.
More details on file formats can be found at http://en.wikipedia.org/wiki/Audiofileformat. A very detailed list of file formats can be found at http://www.fileinfo.com/filetypes/audio. A useful list of extensions for each format can be found at http://html5doctor.com/html5-audio-the-state-of-play/
Default: ["mp3", "ogg", "mpeg", "wav", "m4a", "mp4", "aiff", "wma", "mid"]
Events
fileload
This event is fired when a file finishes loading internally. This event is fired for each loaded sound,
so any handler methods should look up the event.src
to handle a particular sound.
Event Payload:
-
target
ObjectThe object that dispatched the event.
-
type
StringThe event type.
-
src
StringThe source of the sound that was loaded. Note this will only return the loaded part of a delimiter-separated source.
-
[id]
String optionalThe id passed in when the sound was registered. If one was not provided, it will be null.
-
[data]
Number | Object optionalAny additional data associated with the item. If not provided, it will be undefined.