API Documentation for: 0.4.1
Show:

Sound Class

Defined in: Sound:77
Module: SoundJS

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.setVolume(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.
Safari limitations
  • Safari requires Quicktime to be installed for audio playback.
iOS 6 Web Audio 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 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.
Android Chrome 26.0.1410.58 specific limitations
  • Chrome reports true when you run createjs.Sound.BrowserDetect.isChrome, but is a different browser with different abilities.
  • Can only play 1 sound at a time.
  • Sound is not cached.
  • Sound can only be loaded in a user initiated touch/click event.
  • There is a delay before a sound is played, presumably while the src is loaded.

Methods

addEventListener

(
  • type
  • listener
)
Function | Object

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 String

    The string type of the event.

  • listener Function | Object

    An object with a handleEvent method, or a function that will be called when the event is dispatched.

Returns:

Function | Object: Returns the listener for chaining or assignment.

beginPlaying

(
  • instance
  • [interrupt=none]
  • [offset]
  • [loop=0]
  • [volume]
  • [pan=instance.pan]
)
Boolean protected static

Defined in beginPlaying:1272

Begin playback. This is called immediately or after delay by playInstance.

Parameters:

  • instance SoundInstance

    A SoundInstance to begin playback.

  • [interrupt=none] String optional

    How this sound interrupts other instances with the same source. Defaults to Sound.INTERRUPTNONE. Interrupts are defined as INTERRUPTTYPE constants on Sound.

  • [offset] Number optional

    Time in milliseconds into the sound to begin playback. Defaults to the current value on the instance.

  • [loop=0] Number optional

    The number of times to loop the audio. Use 0 for no loops, and -1 for an infinite loop.

  • [volume] Number optional

    The volume of the sound between 0 and 1. Defaults to the current value on the instance.

  • [pan=instance.pan] Number optional

    The pan of the sound between -1 and 1. Defaults to current instance value.

Returns:

Boolean: If the sound can start playing. If there are no available channels, or the instance fails to start, this will return false.

createInstance

(
  • src
)
SoundInstance

Defined in createInstance:1047

Available since 0.4.0

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 Sound.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 String

    The src or ID of the audio.

Returns:

SoundInstance: A SoundInstance that can be controlled after it is created. Unsupported extensions will return the default SoundInstance.

dispatchEvent

(
  • eventObj
  • [target]
)
Boolean

Dispatches the specified event to all listeners.

Example

 // Use a string event
 this.dispatchEvent("complete");

 // Use an object
 var event = {
     type: "complete",
     foo: "bar"
 };
 this.dispatchEvent(event);

Parameters:

  • eventObj Object | String

    An object with a "type" property, or a string type. If a string is used, dispatchEvent will construct a generic event object with the specified type.

  • [target] Object optional

    The object to use as the target property of the event object. This will default to the dispatching object.

Returns:

Boolean: Returns true if any listener returned true.

getCapabilities

() Object static

Defined in getCapabilities:642

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:

Object: An object containing the capabilities of the active plugin.

getCapability

(
  • key
)
Number | Boolean static

Defined in getCapability:670

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 String

    The capability to retrieve

Returns:

Number | Boolean: The value of the capability.

getMute

() Boolean static

Defined in getMute:1180

Available since 0.4.0

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:

Boolean: The mute value of Sound.

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:

Object: An object containing:
  • 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
)
String protected static

Defined in getSrcById:1304

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 String

    The ID the sound was registered with.

Returns:

String: The source of the sound. Returns null if src has been registered with this id.

getVolume

() Number static

Defined in getVolume:1119

Get the master volume of Sound. The master volume is multiplied against each sound's individual volume. To get individual sound volume, use SoundInstance getVolume instead.

Example

var masterVolume = createjs.Sound.getVolume();

Returns:

Number: The master volume, in a range of 0-1.

hasEventListener

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean: Returns true if there is at least one listener for the specified event.

initialize

() protected

Inherited from EventDispatcher: initialize:98

Initialization method.

initializeDefaultPlugins

() Boolean

Defined in initializeDefaultPlugins:597

Available since 0.4.0

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:

Boolean: If a plugin is initialized (true) or not (false). If the browser does not have the capabilities to initialize any available plugins, this will return false.

initLoad

(
  • src
  • [type]
  • [id]
  • [data]
)
Boolean | Object protected static

Defined in initLoad:690

Process manifest items from PreloadJS. This method is intended for usage by a plugin, and not for direct interaction.

Parameters:

  • src String | Object

    The src or object to load. This is usually a string path, but can also be an HTMLAudioElement or similar audio playback object.

  • [type] String optional

    The type of object. Will likely be "sound" or null.

  • [id] String optional

    An optional user-specified id that is used to play sounds.

  • [data] Number | String | Boolean | Object optional

    Data 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.

Returns:

Boolean | Object: An object with the modified values of those that were passed in, or false if the active plugin can not play the audio type.

isReady

() Boolean static

Defined in isReady:623

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:

Boolean: If Sound has initialized a plugin.

loadComplete

(
  • src
)
Boolean

Defined in loadComplete:937

Available since 0.4.0

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 String

    The src or id that is being loaded.

Returns:

Boolean: If the src is already loaded.

mute

(
  • value
)
deprecated static

Defined in mute:1134

Deprecated: This function has been deprecated. Please use setMute instead.

Mute/Unmute all audio. Please see setMute.

Parameters:

  • value Boolean

    Whether the audio should be muted or not.

parsePath

(
  • value
  • [type]
  • [id]
  • [data]
)
Object protected

Defined in parsePath:962

Parse the path of a sound, usually from a manifest item. Manifest items support single file paths, as well as composite paths using Sound.DELIMITER, which defaults to "|". The first path supported by the current browser/plugin will be used.

Parameters:

  • value String

    The path to an audio source.

  • [type] String optional

    The type of path. This will typically be "sound" or null.

  • [id] String optional

    The user-specified sound ID. This may be null, in which case the src will be used instead.

  • [data] Number | String | Boolean | Object optional

    Arbitrary 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:

Object: A formatted object that can be registered with the Sound.activePlugin and returned to a preloader like PreloadJS.

play

(
  • src
  • [interrupt="none"]
  • [delay=0]
  • [offset=0]
  • [loop=0]
  • [volume=1]
  • [pan=0]
)
SoundInstance static

Defined in play:1005

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 Sound.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,Sound.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);
 }

Parameters:

  • src String

    The src or ID of the audio.

  • [interrupt="none"] String optional

    How 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.

  • [delay=0] Number optional

    The amount of time to delay the start of audio playback, in milliseconds.

  • [offset=0] Number optional

    The offset from the start of the audio to begin playback, in milliseconds.

  • [loop=0] Number optional

    How 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 optional

    The volume of the sound, between 0 and 1. Note that the master volume is applied against the individual volume.

  • [pan=0] Number optional

    The left-right pan of the sound (if supported), between -1 (left) and 1 (right).

Returns:

SoundInstance: A SoundInstance that can be controlled after it is created.

playFinished

(
  • instance
)
protected static

Defined in playFinished:1320

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:

playInstance

(
  • instance
  • [interrupt=none]
  • [delay=0]
  • [offset=instance.offset]
  • [loop=0]
  • [volume]
  • [pan]
)
Boolean protected static

Defined in playInstance:1217

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 SoundInstance

    The SoundInstance to start playing.

  • [interrupt=none] String optional

    How this sound interrupts other instances with the same source. Defaults to Sound.INTERRUPTNONE. All interrupt values are defined as INTERRUPTTYPEconstants on Sound.

  • [delay=0] Number optional

    Time in milliseconds before playback begins.

  • [offset=instance.offset] Number optional

    Time into the sound to begin playback in milliseconds. Defaults to the current value on the instance.

  • [loop=0] Number optional

    The number of times to loop the audio. Use 0 for no loops, and -1 for an infinite loop.

  • [volume] Number optional

    The volume of the sound between 0 and 1. Defaults to current instance value.

  • [pan] Number optional

    The pan of the sound between -1 and 1. Defaults to current instance value.

Returns:

Boolean: If the sound can start playing. Sounds that fail immediately will return false. Sounds that have a delay will return true, but may still fail to play.

proxy

(
  • method
  • scope
)
deprecated protected static

Defined in proxy:1337

Deprecated: Deprecated in favor of createjs.proxy.

A function proxy for Sound methods. By default, JavaScript methods do not maintain scope, so passing a method as a callback will result in the method getting called in the scope of the caller. Using a proxy ensures that the method gets called in the correct scope.

Parameters:

  • method Function

    The function to call

  • scope Object

    The scope to call the method name on

registerManifest

(
  • manifest
)
Object static

Defined in registerManifest:809

Available since 0.4.0

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:"assetPath/asset0.mp3|assetPath/asset0.ogg", id:"example"}, // Note the Sound.DELIMITER
     {src:"assetPath/asset1.mp3|assetPath/asset1.ogg", id:"1", data:6},
     {src:"assetPath/asset2.mp3", id:"works"}
 ];
 createjs.Sound.addEventListener("fileload", handleLoad); // call handleLoad when each sound loads
 createjs.Sound.registerManifest(manifest);

Parameters:

  • manifest Array

    An 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.

Returns:

Object: An array of objects with the modified values that were passed in, which defines each sound. It will return false for any values that the source cannot be parsed.

registerPlugin

(
  • plugin
)
Boolean static

Defined in registerPlugin:545

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 Object

    The plugin class to install.

Returns:

Boolean: Whether the plugin was successfully initialized.

registerPlugins

(
  • plugins
)
Boolean static

Defined in registerPlugins:574

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 Array

    An array of plugins classes to install.

Returns:

Boolean: Whether a plugin was successfully initialized.

registerSound

(
  • src
  • [id]
  • [data]
  • [preload=true]
)
Object static

Defined in registerSound:714

Available since 0.4.0

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 | Object

    The source or an Objects with a "src" property

  • [id] String optional

    An id specified by the user to play the sound later.

  • [data] Number | Object optional

    Data 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 optional

    If the sound should be internally preloaded so that it can be played back without an external preloader.

Returns:

Object: An object with the modified values that were passed in, which defines the sound. Returns false if the source cannot be parsed.

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 optional

    The string type of the event. If omitted, all listeners for all types will be removed.

removeAllSounds

() static

Defined in removeAllSounds:918

Available since 0.4.1

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
)

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);

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

removeManifest

(
  • manifest
)
Object static

Defined in removeManifest:889

Available since 0.4.1

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.

Example

 var manifest = [
     {src:"assetPath/asset0.mp3|assetPath/asset0.ogg", id:"example"}, // Note the Sound.DELIMITER
     {src:"assetPath/asset1.mp3|assetPath/asset1.ogg", id:"1", data:6},
     {src:"assetPath/asset2.mp3", id:"works"}
 ];
 createjs.Sound.removeManifest(manifest);

Parameters:

  • manifest Array

    An array of objects to remove. Objects are expected to be in the format needed for removeSound: {srcOrID:srcURIorID}

Returns:

Object: An array of Boolean values representing if the sounds with the same array index in manifest was successfully removed.

removeSound

(
  • src
)
Boolean static

Defined in removeSound:840

Available since 0.4.1

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.

Example

 createjs.Sound.removeSound("myAudioPath/mySound.mp3|myAudioPath/mySound.ogg");
 createjs.Sound.removeSound("myID");

Parameters:

  • src String | Object

    The src or ID of the audio, or an Object with a "src" property

Returns:

Boolean: True if sound is successfully removed.

sendFileLoadEvent

(
  • src
)
protected static

Defined in sendFileLoadEvent:486

Available since 0.4.1

Used by external plugins to dispatch file load events.

Parameters:

  • src String

    A sound file has completed loading, and should be dispatched.

setMute

(
  • value
)
Boolean static

Defined in setMute:1151

Available since 0.4.0

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 Boolean

    Whether the audio should be muted or not.

Returns:

Boolean: If the mute was set.

setVolume

(
  • value
)
static

Defined in setVolume:1093

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 Number

    The master volume value. The acceptable range is 0-1.

stop

() static

Defined in stop:1196

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();

toString

() String

Inherited from EventDispatcher: toString:231

Returns:

String: a string representation of the instance.

Properties

_listeners

Object protected

Inherited from EventDispatcher: _listeners:90

activePlugin

Object static

Defined in activePlugin:354

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

Defined in AUDIO_TIMEOUT:197

The duration in milliseconds to determine a timeout.

Default: 8000

defaultInterruptBehavior

String static

Defined in defaultInterruptBehavior:332

Available since 0.4.0

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 Sound.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

Defined in DELIMITER:188

The character (or characters) that are used to split multiple paths from an audio source.

Default: |

EXTENSION_MAP

Object

Defined in EXTENSION_MAP:310

Available since 0.4.0

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

Defined in FILE_PATTERN:322

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.

idHash

Object protected static

Defined in idHash:412

An object hash storing sound sources via there corresponding ID.

instances

Array protected static

Defined in instances:399

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

Defined in INTERRUPT_ANY:207

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

Defined in INTERRUPT_EARLY:217

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

Defined in INTERRUPT_LATE:227

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

Defined in INTERRUPT_NONE:237

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

lastID

Number protected static

Defined in lastID:345

Used internally to assign unique IDs to each SoundInstance.

masterMute

Boolean protected static

Defined in masterMute:387

Available since 0.4.0

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

Defined in masterVolume:376

Available since 0.4.0

The master volume value, which affects all sounds. Use getVolume and setVolume to modify the volume of all audio.

Default: 1

onLoadComplete

Function deprecated

Defined in onLoadComplete:477

Deprecated: In favour of the "fileload" event. Will be removed in a future version.

Available since 0.4.0

The callback that is fired when a file finishes loading internally. This is fired for each loaded sound.

PLAY_FAILED

String static

Defined in PLAY_FAILED:284

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

Defined in PLAY_FINISHED:275

Defines the playState of an instance that completed playback.

Default: playFinished

PLAY_INITED

String static

Defined in PLAY_INITED:248

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

Defined in PLAY_SUCCEEDED:257

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

Defined in preloadHash:421

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

Defined in fileload:463

Available since 0.4.1

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 Object

    The object that dispatched the event.

  • type String

    The event type.

  • src String

    The source of the sound that was loaded. Note this will only return the loaded part of a delimiter-separated source.

  • [id] String optional

    The id passed in when the sound was registered. If one was not provided, it will be null.

  • [data] Number | Object optional

    Any additional data associated with the item. If not provided, it will be undefined.

loadComplete

deprecated

Defined in loadComplete:456

Deprecated: In favor of the "fileload" event.

Available since 0.4.0

This event is fired when a file finishes loading internally. Please use the "fileload" event instead.