SoundJS v1.0.0 API Documentation : Sound (original) (raw)

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 registerSounds. 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 usePreloadJS, registration 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 AbstractSoundInstance which can be paused, resumed, muted, etc. Please see the AbstractSoundInstance documentation for more on the instance control APIs.

Plugins
By default, the WebAudioPlugin or the HTMLAudioPluginare used (when available), although developers can change plugin priority or add new plugins (such as the provided FlashAudioPlugin). 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.FlashAudioPlugin.swfPath = "../src/soundjs/flashaudio";
 createjs.Sound.registerPlugins([createjs.WebAudioPlugin, createjs.FlashAudioPlugin]);
 createjs.Sound.alternateExtensions = ["mp3"];
 createjs.Sound.on("fileload", this.loadHandler, this);
 createjs.Sound.registerSound("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.on("complete", 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 FlashAudioPlugin 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 fail to play the first time play is called if the audio is not finished loading. Use the fileload event to determine when a sound has finished internally preloading. It is recommended that all audio is preloaded before it is played.

 var queue = new createjs.LoadQueue();
    queue.installPlugin(createjs.Sound);

Audio Sprites
SoundJS has added support for AudioSprite, available as of version 0.6.0. For those unfamiliar with audio sprites, they are much like CSS sprites or sprite sheets: multiple audio assets grouped into a single file.

Example

    var assetsPath = "./assets/";
    var sounds = [{
        src:"MyAudioSprite.ogg", data: {
            audioSprite: [
                {id:"sound1", startTime:0, duration:500},
                {id:"sound2", startTime:1000, duration:400},
                {id:"sound3", startTime:1700, duration: 1000}
            ]}
        }
    ];
    createjs.Sound.alternateExtensions = ["mp3"];
    createjs.Sound.on("fileload", loadSound);
    createjs.Sound.registerSounds(sounds, assetsPath);
    // after load is complete
    createjs.Sound.play("sound2");

Mobile Playback
Devices running iOS require the WebAudio context to be "unlocked" by playing at least one sound inside of a user- initiated event (such as touch/click). Earlier versions of SoundJS included a "MobileSafe" sample, but this is no longer necessary as of SoundJS 0.6.2.

Loading Alternate Paths and Extension-less Files
SoundJS supports loading alternate paths and extension-less files by passing an object instead of a string for the src property, which is a hash using the format {extension:"path", extension2:"path2"}. These labels are how SoundJS determines if the browser will support the sound. This also enables multiple formats to live in different folders, or on CDNs, which often has completely different filenames for each file.

Priority is determined by the property order (first property is tried first). This is supported by both internal loading and loading with PreloadJS.

Note: an id is required for playback.

Example

    var sounds = {path:"./audioPath/",
            manifest: [
            {id: "cool", src: {mp3:"mp3/awesome.mp3", ogg:"noExtensionOggFile"}}
    ]};

    createjs.Sound.alternateExtensions = ["mp3"];
    createjs.Sound.addEventListener("fileload", handleLoad);
    createjs.Sound.registerSounds(sounds);

Known Browser and OS issues

IE 9 HTML Audio limitations

Firefox 25 Web Audio limitations

Safari limitations

iOS 6 Web Audio limitations

Android HTML Audio limitations

Web Audio and PreloadJS

Item Index

Methods

Properties

Methods

_beginPlaying

Boolean private static

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

Returns:

Boolean:

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

_getMasterVolume

() Number private static

Use the volume property instead.

Returns:

_getMute

() Boolean private static

Use the muted property instead.

Returns:

_getSrcById

String private static

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:

Returns:

String:

The source of the sound if it has been registered with this ID or the value that was passed in.

_handleLoadComplete

private static

Used to dispatch fileload events from internal loading.

Parameters:

_parsePath

Object private static

Parse the path of a sound. Alternate extensions will be attempted in order if the current extension is not supported

Parameters:

Returns:

_parseSrc

Object private static

Parse the path of a sound based on properties of src matching with supported extensions. Returns false if none of the properties are supported

Parameters:

Returns:

_playFinished

private static

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.

_playInstance

Boolean private static

Play an instance. This is called by the static API, as well as from plugins. This allows the core class to control delays.

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.

_registerPlugin

Boolean private static

Parameters:

Returns:

Boolean:

Whether the plugin was successfully initialized.

_registerSound

Object private static

Internal method for loading sounds. This should not be called directly.

Parameters:

Returns:

Object:

An object with the modified values that were passed in, which defines the sound. Returns false if the source cannot be parsed or no plugins can be initialized. Returns true if the source is already loaded.

_setMasterVolume

() private static

Use the volume property instead.

_setMute

private static

Use the muted property instead.

Parameters:

addEventListener

(

)

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:

Returns:

createInstance

(

)

AbstractSoundInstance static

Creates a AbstractSoundInstance using the passed in src. If the src does not have a supported extension or if there is no available plugin, a default AbstractSoundInstance will be returned that can be called safely but does nothing.

Example

 var myInstance = null;
 createjs.Sound.on("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");
 }

NOTE to create an audio sprite that has not already been registered, both startTime and duration need to be set. This is only when creating a new audio sprite, not when playing using the id of an already registered audio sprite.

Parameters:

Returns:

dispatchEvent

(

)

Boolean

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:

Returns:

Boolean:

Returns false if preventDefault() was called on a cancelable event, true otherwise.

getCapabilities

() deprecated

getDefaultPlayProps

PlayPropsConfig

Get the default playback properties for the passed in src or ID. These properties are applied to all new SoundInstances. Returns null if default does not exist.

Parameters:

Returns:

PlayPropsConfig:

returns an existing PlayPropsConfig or null if one does not exist

getMasterVolume

() deprecated

Use the volume property instead.

getMute

() deprecated

Use the muted property instead.

getPreloadHandlers

() Object private 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:

hasEventListener

Boolean

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

Parameters:

Returns:

Boolean:

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

initializeDefaultPlugins

() Boolean static

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:

True if a plugin was initialized, false otherwise.

initLoad

Object | AbstractLoader private static

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

Parameters:

Returns:

Object | AbstractLoader:

An instance of AbstractLoader.

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.FlashAudioPlugin.swfPath = "../src/soundjs/flashaudio/";
    createjs.Sound.registerPlugins([createjs.WebAudioPlugin, createjs.HTMLAudioPlugin, createjs.FlashAudioPlugin]);
}

Returns:

Boolean:

If Sound has initialized a plugin.

loadComplete

Boolean static

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.ogg";
if(createjs.Sound.loadComplete(mySound) {
    createjs.Sound.play(mySound);
}

Parameters:

Returns:

Boolean:

If the src is already loaded.

off

(

)

A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the .on method.

IMPORTANT: To remove a listener added with on, you must pass in the returned wrapper function as the listener. See on for an example.

Parameters:

on

(

)

Function

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 wrapper function is returned for use with removeEventListener (or off).

IMPORTANT: To remove a listener added with on, you must pass in the returned wrapper function as the listener, or useremove. Likewise, each time you call on a NEW wrapper function is subscribed, so multiple calls to on with the same params will create multiple listeners.

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:

Returns:

Function:

Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.

play

AbstractSoundInstance static

Play a sound and get a AbstractSoundInstance to control. If the sound fails to play, an AbstractSoundInstance 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 the play, method, 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, a default AbstractSoundInstance will still be returned, which will not play any audio, but will not generate errors.

Example

 createjs.Sound.on("fileload", handleLoad);
 createjs.Sound.registerSound("myAudioPath/mySound.mp3", "myID", 3);
 function handleLoad(event) {
     createjs.Sound.play("myID");
     // store off AbstractSoundInstance for controlling
     var myInstance = createjs.Sound.play("myID", {interrupt: createjs.Sound.INTERRUPT_ANY, loop:-1});
 }

NOTE: To create an audio sprite that has not already been registered, both startTime and duration need to be set. This is only when creating a new audio sprite, not when playing using the id of an already registered audio sprite.

Parameters:

Returns:

registerPlugins

Boolean static

Register a list of Sound plugins, in order of precedence. To register a single plugin, pass a single element in the array.

Example

 createjs.FlashAudioPlugin.swfPath = "../src/soundjs/flashaudio/";
 createjs.Sound.registerPlugins([createjs.WebAudioPlugin, createjs.HTMLAudioPlugin, createjs.FlashAudioPlugin]);

Parameters:

Returns:

Boolean:

Whether a plugin was successfully initialized.

registerSound

(

)

Object static

Register an audio file for loading and future playback in Sound. This is automatically called when usingPreloadJS. 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.alternateExtensions = ["mp3"];
 createjs.Sound.on("fileload", handleLoad); // add an event listener for when load is completed
 createjs.Sound.registerSound("myAudioPath/mySound.ogg", "myID", 3);
 createjs.Sound.registerSound({ogg:"path1/mySound.ogg", mp3:"path2/mySoundNoExtension"}, "myID", 3);

Parameters:

Returns:

Object:

An object with the modified values that were passed in, which defines the sound. Returns false if the source cannot be parsed or no plugins can be initialized. Returns true if the source is already loaded.

registerSounds

Object static

Register an array 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 assetPath = "./myAudioPath/";
 var sounds = [
     {src:"asset0.ogg", id:"example"},
     {src:"asset1.ogg", id:"1", data:6},
     {src:"asset2.mp3", id:"works"}
     {src:{mp3:"path1/asset3.mp3", ogg:"path2/asset3NoExtension"}, id:"better"}
 ];
 createjs.Sound.alternateExtensions = ["mp3"];    // if the passed extension is not supported, try this extension
 createjs.Sound.on("fileload", handleLoad); // call handleLoad when each sound loads
 createjs.Sound.registerSounds(sounds, assetPath);

Parameters:

Returns:

Object:

An array of objects with the modified values that were passed in, which defines each sound. Like registerSound, it will return false for any values when the source cannot be parsed or if no plugins can be initialized. Also, it will return true for any values when the source is already loaded.

removeAllEventListeners

Removes all listeners for the specified type, or all listeners of all types.

Example

 // Remove all listeners
 displayObject.removeAllEventListeners();

 // Remove all click listeners
 displayObject.removeAllEventListeners("click");

Parameters:

removeAllSounds

() static

Remove all sounds that have been registered with registerSound orregisterSounds.
Note this will stop playback on all active sound instances before deleting them.

Example

createjs.Sound.removeAllSounds();

removeEventListener

(

)

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:

removeSound

Boolean static

Remove a sound that has been registered with registerSound orregisterSounds.
Note this will stop playback on active instances playing this sound before deleting them.
Note if you passed in a basePath, you need to pass it or prepend it to the src here.

Example

 createjs.Sound.removeSound("myID");
 createjs.Sound.removeSound("myAudioBasePath/mySound.ogg");
 createjs.Sound.removeSound("myPath/myOtherSound.mp3", "myBasePath/");
 createjs.Sound.removeSound({mp3:"musicNoExtension", ogg:"music.ogg"}, "myBasePath/");

Parameters:

Returns:

Boolean:

True if sound is successfully removed.

removeSounds

Object static

Remove an array of audio files that have been registered with registerSound orregisterSounds.
Note this will stop playback on active instances playing this audio before deleting them.
Note if you passed in a basePath, you need to pass it or prepend it to the src here.

Example

    assetPath = "./myPath/";
 var sounds = [
     {src:"asset0.ogg", id:"example"},
     {src:"asset1.ogg", id:"1", data:6},
     {src:"asset2.mp3", id:"works"}
 ];
 createjs.Sound.removeSounds(sounds, assetPath);

Parameters:

Returns:

Object:

An array of Boolean values representing if the sounds with the same array index were successfully removed.

setDefaultPlayProps

Set the default playback properties for all new SoundInstances of the passed in src or ID. See PlayPropsConfig for available properties.

Parameters:

setMute

() deprecated

Use the muted property instead.

setVolume

() deprecated

Use the volume property instead.

stop

() static

Stop all audio (global stop). Stopped audio is reset, and not paused. To play audio that has been stopped, call AbstractSoundInstance play.

Example

createjs.Sound.stop();

toString

() String

Returns:

String:

a string representation of the instance.

willTrigger

Boolean

Indicates whether there is at least one listener for the specified event type on this object or any of its ancestors (parent, parent's parent, etc). A return value of true indicates that if a bubbling event of the specified type is dispatched from this object, it will trigger at least one listener.

This is similar to hasEventListener, but it searches the entire event flow for a listener, not just this object.

Parameters:

Returns:

Boolean:

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

Properties

_captureListeners

Object protected

_defaultPlayPropsHash

Object private static

_idHash

Object private static

An object hash storing objects with sound sources, startTime, and duration via there corresponding ID.

_instances

Array private 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 volume. 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 _beginPlayingmethod.

_lastID

Number private static

Used internally to assign unique IDs to each AbstractSoundInstance.

_masterVolume

Number private

The internal volume level. Use volume to adjust the master volume.

Default: 1

_pluginsRegistered

Boolean private 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 private 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.

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

alternateExtensions

Array static

An array of extensions to attempt to use when loading sound, if the default is unsupported by the active plugin. These are applied in order, so if you try to Load Thunder.ogg in a browser that does not support ogg, and your extensions array is ["mp3", "m4a", "wav"] it will check mp3 support, then m4a, then wav. The audio files need to exist in the same location, as only the extension is altered.

Note that regardless of which file is loaded, you can call createInstanceand play using the same id or full source path passed for loading.

Example

var sounds = [
    {src:"myPath/mySound.ogg", id:"example"},
];
createjs.Sound.alternateExtensions = ["mp3"]; // now if ogg is not supported, SoundJS will try asset0.mp3
createjs.Sound.on("fileload", handleLoad); // call handleLoad when each sound loads
createjs.Sound.registerSounds(sounds, assetPath);
// ...
createjs.Sound.play("myPath/mySound.ogg"); // works regardless of what extension is supported.  Note calling with ID is a better approach

capabilities

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:

An entry for each file type in SUPPORTED_EXTENSIONS:

You can get a specific capability of the active plugin using standard object notation

Example

 var mp3 = createjs.Sound.capabilities.mp3;

Note this property is read only.

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_NONEbut this can be set and will change playback behavior accordingly. This is only used when playis called without passing a value for interrupt.

Default: Sound.INTERRUPT_NONE, or "none"

EXTENSION_MAP

Object static

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.

A useful list of extensions for each format can be found at http://html5doctor.com/html5-audio-the-state-of-play/.

Default: {m4a:"mp4"}

FILE_PATTERN

RegExp private 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.

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

muted

Boolean static

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 AbstractSoundInstance muted instead.

Example

createjs.Sound.muted = true;

Default: false

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

SUPPORTED_EXTENSIONS

ArrayString static

Default: ["mp3", "ogg", "opus", "mpeg", "wav", "m4a", "mp4", "aiff", "wma", "mid"]

volume

Number static

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 AbstractSoundInstance volumeinstead.

Example

createjs.Sound.volume = 0.5;

Default: 1

Events

fileerror

This event is fired when a file fails 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:

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: