API Documentation for: 0.5.2
Show:

SoundInstance Class

Extends EventDispatcher
Defined in: SoundInstance:485
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", {loop:2});
 myInstance.addEventListener("loop", handleLoop);
 function handleLoop(event) {
     myInstance.volume = myInstance.volume * 0.5;
 }

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

Parameters:

  • src String

    The path to and file name of the sound.

  • owner Object

    The plugin instance that created this SoundInstance.

Methods

_beginPlaying

(
  • offset
  • loop
  • volume
  • pan
)
protected

Defined in _beginPlaying:1019

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

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

_cleanUpAudioNode

(
  • audioNode
)
AudioNode protected

Defined in _cleanUpAudioNode:908

Available since 0.4.1

Turn off and disconnect an audioNode, then set reference to null to release it for garbage collection

Parameters:

Returns:

AudioNode:

_createAndPlayAudioNode

(
  • startTime
  • offset
)
AudioNode protected

Defined in _createAndPlayAudioNode:971

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
  • eventPhase
)
protected

Parameters:

_handleSoundComplete

(
  • event
)
protected

Audio has finished playing. Manually loop it if required.

Parameters:

_handleSoundReady

() protected

Handles starting playback when the sound is ready for playing.

_init

(
  • src
  • owner
)
protected

Defined in _init:857

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.

_interrupt

() protected

Defined in _interrupt:925

The sound has been interrupted.

_sendEvent

(
  • type
)
protected

Defined in _sendEvent:845

A helper method that dispatches all events for SoundInstance.

Parameters:

_updateVolume

() Boolean protected

Defined in _updateVolume:1142

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.

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.

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

Get the duration of the instance, in milliseconds. Note in most cases, you need to play a sound using play or the Sound API 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:1194

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

NOTE that you can access pan directly as a property, 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:1246

Get the position of the playhead of 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:1158

NOTE that you can access volume directly as a property, 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.

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

Initialization method.

off

(
  • type
  • listener
  • [useCapture]
)

Inherited from EventDispatcher: off:247

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

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

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

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({offset:1, loop:2, pan:0.5});    // options as object properties
 myInstance.play(createjs.Sound.INTERRUPT_ANY);    // options as parameters

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

 // 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:1083

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.

setMute

(
  • value
)
Boolean

Defined in setMute:1171

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

NOTE that you can set pan directly as a property, 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:1266

Set the position of the playhead in the instance. This can be set while a sound is playing, paused, or 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:1122

NOTE that you can set volume directly as a property, 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:1104

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

Returns:

String: a string representation of the instance.

willTrigger

(
  • type
)
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:

  • type String

    The string type of the event.

Returns:

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

Properties

_captureListeners

Object protected

_delay

Number protected

Defined in _delay:573

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

Default: 0

_delayTimeoutId

TimeoutVariable protected

Defined in _delayTimeoutId:664

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

_duration

Number protected

Defined in _duration:645

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

Default: 0

_listeners

Object protected

_muted

Boolean protected

Defined in _muted:729

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

Default: false

_offset

Number protected

Defined in _offset:562

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

_owner

WebAudioPlugin protected

Defined in _owner:553

The plugin that created the instance

Default: null

_paused

Boolean protected

Defined in _paused:739

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

Default: false

_remainingLoops

Number protected

Defined in _remainingLoops:655

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

Default: 0

_soundCompleteTimeout

TimeoutVariable protected

Defined in _soundCompleteTimeout:675

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

_sourceNodeNext

AudioNode protected

Defined in _sourceNodeNext:716

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

_startTime

Number protected

Defined in _startTime:749

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

gainNode

AudioGainNode

Defined in gainNode:686

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.

onComplete

Function deprecated

Defined in onComplete:830

Deprecated: Use addEventListener and the "complete" event.

REMOVED. Use addEventListener and the complete event.

onLoop

Function deprecated

Defined in onLoop:837

Deprecated: Use addEventListener and the "loop" event.

REMOVED. Use addEventListener and the loop event.

onPlayFailed

Function deprecated

Defined in onPlayFailed:823

Deprecated: Use addEventListener and the "failed" event.

REMOVED. Use addEventListener and the failed event.

onPlayInterrupted

Function deprecated

Defined in onPlayInterrupted:816

Deprecated: Use addEventListener and the "interrupted" event.

REMOVED. Use addEventListener and the interrupted event.

onPlaySucceeded

Function deprecated

Defined in onPlaySucceeded:809

Deprecated: Use addEventListener and the "succeeded" event.

REMOVED. Use addEventListener and the succeeded event.

pan

Number

Defined in pan:613

The pan of the sound, between -1 (left) and 1 (right). Note that pan is not supported by 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

panNode

AudioPannerNode

Defined in panNode:697

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.

playState

String

Defined in playState:545

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

Default: null

sourceNode

AudioNode

Defined in sourceNode:706

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

src

String

Defined in src:529

The source of the sound.

Default: null

uniqueId

String | Number

Defined in uniqueId:537

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

Default: -1

volume

Number

Defined in volume:583

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

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

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

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

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.

succeeded

Defined in succeeded:764

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.