API Documentation for: 0.5.1
Show:

SoundInstance Class

Defined in: SoundInstance:503
Module: SoundJS

A SoundInstance is created when any calls to the Sound API method play or createInstance are made. The SoundInstance is returned by the active plugin for control by the user.

Example

 var myInstance = createjs.Sound.play("myAssetPath/mySrcFile.mp3");

A number of additional parameters provide a quick way to determine how a sound is played. Please see the Sound API method play for a list of arguments.

Once a SoundInstance is created, a reference can be stored that can be used to control the audio directly through the SoundInstance. If the reference is not stored, the SoundInstance will play out its audio (and any loops), and is then de-referenced from the Sound class so that it can be cleaned up. If audio playback has completed, a simple call to the play instance method will rebuild the references the Sound class need to control it.

 var myInstance = createjs.Sound.play("myAssetPath/mySrcFile.mp3");
 myInstance.addEventListener("complete", playAgain);
 function playAgain(event) {
     myInstance.play();
 }

Events are dispatched from the instance to notify when the sound has completed, looped, or when playback fails

 var myInstance = createjs.Sound.play("myAssetPath/mySrcFile.mp3");
 myInstance.addEventListener("complete", handleComplete);
 myInstance.addEventListener("loop", handleLoop);
 myInstance.addEventListener("failed", handleFailed);

Constructor

SoundInstance

(
  • src
  • owner
)

Defined in SoundInstance:503

Parameters:

  • src String

    The path to and file name of the sound.

  • owner Object

    The plugin instance that created this SoundInstance.

Methods

_dispatchEvent

(
  • eventObj
  • eventPhase
)
protected

Parameters:

addEventListener

(
  • type
  • listener
  • [useCapture]
)
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.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

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

beginPlaying

(
  • offset
  • loop
  • volume
  • pan
)
protected

Defined in beginPlaying:1073

Called by the Sound class when the audio is ready to play (delay has completed). Starts sound playing if the src is loaded, otherwise playback will fail.

Parameters:

  • offset Number

    How far into the sound to begin playback, in milliseconds.

  • loop Number

    The number of times to loop the audio. Use -1 for infinite loops.

  • volume Number

    The volume of the sound, between 0 and 1.

  • pan Number

    The pan of the sound between -1 (left) and 1 (right). Note that pan does not work for HTML Audio.

cleanup

() protected

Defined in cleanup:931

Clean up the instance. Remove references and clean up any additional properties such as timers.

createAudioNode

(
  • startTime
  • offset
)
AudioNode protected

Defined in createAudioNode:1021

Available since 0.4.1

Creates an audio node using the current src and context, connects it to the gain node, and starts playback.

Parameters:

  • startTime Number

    The time to add this to the web audio context, in seconds.

  • offset Number

    The amount of time into the src audio to start playback, in seconds.

Returns:

AudioNode:

dispatchEvent

(
  • eventObj
  • [target]
)
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:

  • eventObj Object | String | Event

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

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

Boolean: Returns the value of eventObj.defaultPrevented.

getDuration

() Number

Defined in getDuration:1356

Get the duration of the instance, in milliseconds. Note in most cases, you need to play a sound using play or the Sound API Sound.play method before its duration can be reported accurately.

Example

var soundDur = myInstance.getDuration();

Returns:

Number: The duration of the sound instance in milliseconds.

getMute

() Boolean

Defined in getMute:1256

Available since 0.4.0

Get the mute value of the instance.

Example

 var isMuted = myInstance.getMute();

Returns:

Boolean: If the sound is muted.

getPan

() Number

Defined in getPan:1291

NOTE that you can get volume directly, and getPan remains to allow support for IE8 with FlashPlugin.

Get the left/right pan of the instance. Note in WebAudioPlugin this only gives us the "x" value of what is actually 3D audio.

Example

var myPan = myInstance.getPan();

Returns:

Number: The value of the pan, between -1 (left) and 1 (right).

getPosition

() Number

Defined in getPosition:1308

Get the position of the playhead in the instance in milliseconds.

Example

var currentOffset = myInstance.getPosition();

Returns:

Number: The position of the playhead in the sound, in milliseconds.

getVolume

()

Defined in getVolume:1212

NOTE that you can get volume directly, and getVolume remains to allow support for IE8 with FlashPlugin.

Get the volume of the instance. The actual output volume of a sound can be calculated using: myInstance.getVolume() * createjs.Sound.getVolume();

Returns:

The current volume of the sound instance.

hasEventListener

(
  • type
)
Boolean

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

Parameters:

  • type String

    The string type of the event.

Returns:

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

init

(
  • src
  • owner
)
protected

Defined in init:905

Initialize the SoundInstance. This is called from the constructor.

Parameters:

  • src String

    The source of the audio.

  • owner Class

    The plugin that created this instance.

initialize

() protected

Initialization method.

interrupt

() protected

Defined in interrupt:974

The sound has been interrupted.

mute

(
  • value
)
Boolean deprecated

Defined in mute:1225

Deprecated: This method has been replaced by setMute.

REMOVED. Please use setMute instead.

Parameters:

  • value Boolean

    If the sound should be muted or not.

Returns:

Boolean: If the mute call succeeds.

off

(
  • type
  • listener
  • [useCapture]
)

Inherited from EventDispatcher: off:246

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

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

on

(
  • type
  • listener
  • [scope]
  • [once=false]
  • [data]
  • [useCapture=false]
)
Function

Inherited from EventDispatcher: on:174

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

  • [scope] Object optional

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

    If true, the listener will remove itself after the first time it is triggered.

  • [data] optional

    Arbitrary data that will be included as the second parameter when the listener is called.

  • [useCapture=false] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

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

pause

() Boolean

Defined in pause:1107

Pause the instance. Paused audio will stop at the current time, and can be resumed using resume.

Example

 myInstance.pause();

Returns:

Boolean: If the pause call succeeds. This will return false if the sound isn't currently playing.

play

(
  • [interrupt="none"|options]
  • [delay=0]
  • [offset=0]
  • [loop=0]
  • [volume=1]
  • [pan=0]
)

Defined in play:1044

Play an instance. This method is intended to be called on SoundInstances that already exist (created with the Sound API createInstance or play).

Example

 var myInstance = createjs.Sound.createInstance(mySrc);
 myInstance.play(createjs.Sound.INTERRUPT_ANY);
 // alternatively, we can pass in options we want to set in an object
 myInstance.play({offset:1, loop:2, pan:0.5});

Parameters:

  • [interrupt="none"|options] String | Object 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.
    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 optional

    The delay in milliseconds before the sound starts

  • [offset=0] Number optional

    How far into the sound to begin playback, in milliseconds.

  • [loop=0] Number optional

    The number of times to loop the audio. Use -1 for infinite loops.

  • [volume=1] Number optional

    The volume of the sound, between 0 and 1.

  • [pan=0] Number optional

    The pan of the sound between -1 (left) and 1 (right). Note that pan is not supported for HTML Audio.

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.

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

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

resume

() Boolean

Defined in resume:1137

Resume an instance that has been paused using pause. Audio that has not been paused will not playback when this method is called.

Example

myInstance.pause();
// do some stuff
myInstance.resume();

Returns:

Boolean: If the resume call succeeds. This will return false if called on a sound that is not paused.

sendEvent

(
  • type
)
protected

Defined in sendEvent:893

A helper method that dispatches all events for SoundInstance.

Parameters:

setMute

(
  • value
)
Boolean

Defined in setMute:1233

Available since 0.4.0

Mute and unmute the sound. Muted sounds will still play at 0 volume. Note that an unmuted sound may still be silent depending on Sound volume, instance volume, and Sound mute.

Example

myInstance.setMute(true);

Parameters:

  • value Boolean

    If the sound should be muted.

Returns:

Boolean: If the mute call succeeds.

setPan

(
  • value
)
Number

Defined in setPan:1271

NOTE that you can set pan directly, and getPan remains to allow support for IE8 with FlashPlugin.

Set the left(-1)/right(+1) pan of the instance. Note that HTMLAudioPlugin does not support panning, and only simple left/right panning has been implemented for WebAudioPlugin. The default pan value is 0 (center).

Example

myInstance.setPan(-1);  // to the left!

Parameters:

  • value Number

    The pan value, between -1 (left) and 1 (right).

Returns:

Number: If the setPan call succeeds.

setPosition

(
  • value
)

Defined in setPosition:1328

Set the position of the playhead in the instance. This can be set while a sound is playing, paused, or even stopped.

Example

 myInstance.setPosition(myInstance.getDuration()/2); // set audio to its halfway point.

Parameters:

  • value Number

    The position to place the playhead, in milliseconds.

setVolume

(
  • value
)
Boolean

Defined in setVolume:1176

NOTE that you can set volume directly, and setVolume remains to allow support for IE8 with FlashPlugin. Set the volume of the instance. You can retrieve the volume using getVolume.

Example

 myInstance.setVolume(0.5);

Note that the master volume set using the Sound API method setVolume will be applied to the instance volume.

Parameters:

  • value Object

    The volume to set, between 0 and 1.

Returns:

Boolean: If the setVolume call succeeds.

stop

() Boolean

Defined in stop:1158

Stop playback of the instance. Stopped sounds will reset their position to 0, and calls to resume will fail. To start playback again, call play.

Example

myInstance.stop();

Returns:

Boolean: If the stop call succeeds.

toString

() String

Inherited from EventDispatcher: toString:339

Returns:

String: a string representation of the instance.

updateVolume

() Boolean protected

Defined in updateVolume:1196

Internal function used to update the volume based on the instance volume, master volume, instance mute value, and master mute value.

Returns:

Boolean: if the volume was updated.

Properties

_captureListeners

Object protected

_listeners

Object protected

delay

Number protected

Defined in delay:592

The time in milliseconds before the sound starts. Note this is handled by Sound.

Default: 0

delayTimeoutId

TimeoutVariable protected

Defined in delayTimeoutId:683

Available since 0.4.0

A Timeout created by Sound when this SoundInstance is played with a delay. This allows SoundInstance to remove the delay if stop or pause or cleanup are called before playback begins.

Default: null

gainNode

AudioGainNode

Defined in gainNode:705

Available since 0.4.0

NOTE this only exists as a WebAudioPlugin property and is only intended for use by advanced users. GainNode for controlling SoundInstance volume. Connected to the WebAudioPlugin gainNode that sequences to context.destination.

Default: null

muted

Boolean protected

Defined in muted:751

Determines if the audio is currently muted. Use getMute and setMute to access.

Default: false

offset

Number protected

Defined in offset:581

How far into the sound to begin playback in milliseconds. This is passed in when play is called and used by pause and setPosition to track where the sound should be at. Note this is converted from milliseconds to seconds for consistency with the WebAudio API.

Default: 0

onComplete

Function deprecated

Defined in onComplete:878

Deprecated: Use addEventListener and the "complete" event.

REMOVED. Use addEventListener and the complete event.

onLoop

Function deprecated

Defined in onLoop:885

Deprecated: Use addEventListener and the "loop" event.

REMOVED. Use addEventListener and the loop event.

onPlayFailed

Function deprecated

Defined in onPlayFailed:871

Deprecated: Use addEventListener and the "failed" event.

REMOVED. Use addEventListener and the failed event.

onPlayInterrupted

Function deprecated

Defined in onPlayInterrupted:864

Deprecated: Use addEventListener and the "interrupted" event.

REMOVED. Use addEventListener and the interrupted event.

onPlaySucceeded

Function deprecated

Defined in onPlaySucceeded:857

Deprecated: Use addEventListener and the "succeeded" event.

REMOVED. Use addEventListener and the succeeded event.

onReady

Function deprecated

Defined in onReady:850

Deprecated: Use addEventListener and the "ready" event.

REMOVED. Use addEventListener and the ready event.

owner

WebAudioPlugin protected

Defined in owner:572

The plugin that created the instance

Default: null

pan

Number

Defined in pan:633

The pan of the sound, between -1 (left) and 1 (right). Note that pan does not work for HTML Audio. Note this uses a getter setter, which is not supported by Firefox versions 3.6 or lower, Opera versions 11.50 or lower, and Internet Explorer 8 or lower. Instead use setPan and getPan. Note in WebAudioPlugin this only gives us the "x" value of what is actually 3D audio.

Default: 0

pan

Number protected

Defined in pan:664

The length of the audio clip, in milliseconds. Use getDuration to access.

Default: 0

panNode

AudioPannerNode

Defined in panNode:717

Available since 0.4.0

NOTE this only exists as a WebAudioPlugin property and is only intended for use by advanced users. A panNode allowing left and right audio channel panning only. Connected to SoundInstance gainNode.

Default: null

paused

Boolean protected

Defined in paused:761

Determines if the audio is currently paused. Use pause and resume to set.

Default: false

playState

String

Defined in playState:564

The play state of the sound. Play states are defined as constants on Sound.

Default: null

remainingLoops

Number protected

Defined in remainingLoops:674

The number of play loops remaining. Negative values will loop infinitely.

Default: 0

soundCompleteTimeout

TimeoutVariable protected

Defined in soundCompleteTimeout:694

Available since 0.4.0

Timeout that is created internally to handle sound playing to completion. Stored so we can remove it when stop, pause, or cleanup are called

Default: null

sourceNode

AudioNode

Defined in sourceNode:727

Available since 0.4.0

NOTE this only exists as a WebAudioPlugin property and is only intended for use by advanced users. sourceNode is the audio source. Connected to gainNode.

Default: null

sourceNodeNext

AudioNode protected

Defined in sourceNodeNext:738

Available since 0.4.1

NOTE this only exists as a WebAudioPlugin property and is only intended for use by advanced users. sourceNodeNext is the audio source for the next loop, inserted in a look ahead approach to allow for smooth looping. Connected to gainNode.

Default: null

src

String protected

Defined in src:547

The source of the sound.

Default: null

startTime

Number protected

Defined in startTime:771

Available since 0.4.0

WebAudioPlugin only. Time audio started playback, in seconds. Used to handle set position, get position, and resuming from paused.

Default: 0

uniqueId

String | Number

Defined in uniqueId:556

The unique ID of the instance. This is set by Sound.

Default: -1

volume

Number

Defined in volume:603

The volume of the sound, between 0 and 1. Note this uses a getter setter, which is not supported by Firefox versions 3.6 or lower and Opera versions 11.50 or lower, and Internet Explorer 8 or lower. Instead use setVolume and getVolume.

The actual output volume of a sound can be calculated using: myInstance.volume * createjs.Sound.getVolume();

Default: 1

Events

complete

Defined in complete:840

Available since 0.4.0

The event that is fired when playback completes. This means that the sound has finished playing in its entirety, including its loop iterations.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

failed

Defined in failed:822

Available since 0.4.0

The event that is fired when playback has failed. This happens when there are too many channels with the same src property already playing (and the interrupt value doesn't cause an interrupt of another instance), or the sound could not be played, perhaps due to a 404 error.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

interrupted

Defined in interrupted:813

Available since 0.4.0

The event that is fired when playback is interrupted. This happens when another sound with the same src property is played using an interrupt value that causes this instance to stop playing.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

loop

Defined in loop:832

Available since 0.4.0

The event that is fired when a sound has completed playing but has loops remaining.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

ready

Defined in ready:797

Available since 0.4.0

The event that is fired when a sound is ready to play.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

succeeded

Defined in succeeded:805

Available since 0.4.0

The event that is fired when playback has started successfully.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.