API Documentation for: 0.4.1
Show:

SoundInstance Class

Defined in: SoundInstance:420
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:420

Parameters:

  • src String

    The path to and file name of the sound.

  • owner Object

    The plugin instance that created this SoundInstance.

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

(
  • offset
  • loop
  • volume
  • pan
)
protected

Defined in beginPlaying:959

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

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

createAudioNode

(
  • startTime
  • offset
)
AudioNode protected

Defined in createAudioNode:912

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

getDuration

() Number

Defined in getDuration:1252

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

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

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

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

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.

init

(
  • src
  • owner
)
protected

Defined in init:791

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

Inherited from EventDispatcher: initialize:98

Initialization method.

interrupt

() protected

Defined in interrupt:859

The sound has been interrupted.

mute

(
  • value
)
Boolean deprecated

Defined in mute:1114

Deprecated: This method has been replaced by setMute.

Mute and unmute the sound. Please use setMute instead.

Parameters:

  • value Boolean

    If the sound should be muted or not.

Returns:

Boolean: If the mute call succeeds.

pause

() Boolean

Defined in pause:994

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]
  • [delay=0]
  • [offset=0]
  • [loop=0]
  • [volume=1]
  • [pan=0]
)

Defined in play:935

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

Parameters:

  • [interrupt=none] String optional

    How this sound interrupts other instances with the same source. Interrupt values are defined as constants on Sound. The default value is Sound.INTERRUPT_NONE.

  • [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
)

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.

resume

() Boolean

Defined in resume:1024

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

A helper method that dispatches all events for SoundInstance.

Parameters:

setMute

(
  • value
)
Boolean

Defined in setMute:1127

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

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

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

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

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

Returns:

String: a string representation of the instance.

updateVolume

() Boolean protected

Defined in updateVolume:1087

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

_listeners

Object protected

Inherited from EventDispatcher: _listeners:90

delay

Number protected

Defined in delay:509

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

Default: 0

delayTimeoutId

TimeoutVariable protected

Defined in delayTimeoutId:560

Available since 0.4.0

A Timout 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:593

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

Default: null

muted

Boolean protected

Defined in muted:628

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

Default: false

offset

Number protected

Defined in offset:498

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

Deprecated: In favor of the "complete" event. Will be removed in a future version.

The callback that is fired when a sound has completed playback.

onLoop

Function deprecated

Defined in onLoop:767

Deprecated: In favor of the "loop" event. Will be removed in a future version.

The callback that is fired when a sound has completed playback, but has loops remaining.

onPlayFailed

Function deprecated

Defined in onPlayFailed:751

Deprecated: In favor of the "failed" event. Will be removed in a future version.

The callback that is fired when a sound has failed to start.

onPlayInterrupted

Function deprecated

Defined in onPlayInterrupted:743

Deprecated: Deprecated in favor of the "interrupted" event. Will be removed in a future version.

The callback that is fired when a sound has been interrupted.

onPlaySucceeded

Function deprecated

Defined in onPlaySucceeded:735

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

The callback that is fired when playback has started successfully.

onReady

Function deprecated

Defined in onReady:727

Deprecated: In favor of the "ready" event. Will be removed in a future version.

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

owner

WebAudioPlugin protected

Defined in owner:489

The plugin that created the instance

Default: null

pan

Number protected

Defined in pan:530

The pan of the sound, between -1 (left) and 1 (right). Note that pan does not work for HTML Audio. Use getPan and setPan to access.

Default: 0

pan

Number protected

Defined in pan:541

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

Default: 0

panNode

AudioPannerNode

Defined in panNode:582

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 our WebAudioPlugin.gainNode that sequences to context.destination.

Default: null

paused

Boolean protected

Defined in paused:638

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

Default: false

playState

String

Defined in playState:481

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

Default: null

remainingLoops

Number protected

Defined in remainingLoops:551

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

Default: 0

soundCompleteTimeout

TimeoutVariable protected

Defined in soundCompleteTimeout:571

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

AudioSourceNode

Defined in sourceNode:604

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

AudioSourceNode protected

Defined in sourceNodeNext:615

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

The source of the sound.

Default: null

startTime

Number protected

Defined in startTime:648

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

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

Default: -1

volume

Number protected

Defined in volume:520

The volume of the sound, between 0 and 1. Use getVolume and setVolume to access.

Default: 0

Events

complete

Defined in complete:717

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

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

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

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

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

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.