API Documentation for: 0.4.0
Show:

SoundInstance Class

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

 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 = 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 = Sound.play("myAssetPath/mySrcFile.mp3");
 myInstance.addEventListener("complete", playAgain);
 myInstance.addEventListener("loop", handleLoop);
 myInstance.addEventListener("playbackFailed", handleFailed);

Constructor

SoundInstance

(
  • src
  • owner
)

Defined in SoundInstance:362

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.

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

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

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

dispatchEvent

(
  • eventObj
  • [target]
)
Boolean

Dispatches the specified event.

Parameters:

  • eventObj Object | String

    An object with a "type" property, or a string type. If a string is used, dispatchEvent will contstruct a generic event object with "type" and "params" properties.

  • [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:1107

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

Returns:

Number: The duration of the sound instance in milliseconds.

getMute

() Boolean

Defined in getMute:1024

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

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

Returns:

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

getPosition

() Number

Defined in getPosition:1067

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

Returns:

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

getVolume

()

Defined in getVolume:980

Get the volume of the instance. The actual output volume of a sound can be calculated using:

 instance.getVolume() x 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:720

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

The sound has been interrupted.

mute

(
  • value
)
Boolean deprecated

Defined in mute:992

Deprecated: This method has been replaced by setMute.

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

Parameters:

  • value Boolean

    If the sound should be muted or not.

Returns:

Boolean: If the mute call succeeds.

mute

(
  • value
)
Boolean

Defined in mute:1006

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 muted depending on the Sound volume, instance volume, and Sound mute.

Parameters:

  • value Boolean

    If the sound should be muted.

Returns:

Boolean: If the mute call succeeds.

pause

() Boolean

Defined in pause:886

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

Play an instance. This method is intended to be called on SoundInstances that already exist (were created with the Sound API CreateInstance, or have completed playback, and need to be played again.

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 does not work for HTML Audio.

removeAllEventListeners

(
  • [type]
)

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

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.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

resume

() Boolean

Defined in resume:914

Resume an instance that has been paused using pause. Audio that has not been started may not resume when this method is called.

Returns:

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

sendEvent

(
  • type
)
private

Defined in sendEvent:705

A helper method that dispatches all events for SoundInstance.

Parameters:

setPan

(
  • value
)
Number

Defined in setPan:1038

Set the left/right 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).

Parameters:

  • value Number

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

Returns:

Number: If the setPan call succeeds.

setPosition

(
  • value
)

Defined in setPosition:1082

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 it's halfway point.

Parameters:

  • value Number

    The position to place the playhead, in milliseconds.

setVolume

(
  • value
)
Boolean

Defined in setVolume:941

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 apply on top of 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:928

Stop playback of the instance. Stopped sounds will reset their position, and calls to resume may fail.

Returns:

Boolean: If the stop call succeeds.

toString

() String

Inherited from EventDispatcher: toString:191

Returns:

String: a string representation of the instance.

updateVolume

() Boolean protected

Defined in updateVolume:964

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

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

Default: 0

delayTimeoutId

TimeoutVariable protected

Defined in delayTimeoutId:502

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

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

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

Default: false

offset

Number protected

Defined in offset:440

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

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

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

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

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

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

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

The plugin that created the instance

Default: null

pan

Number protected

Defined in pan:472

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

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

Default: 0

panNode

AudioPannerNode

Defined in panNode:524

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

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

Default: false

playState

String

Defined in playState:423

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

Default: null

remainingLoops

Number protected

Defined in remainingLoops:493

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

Default: 0

soundCompleteTimeout

TimeoutVariable protected

Defined in soundCompleteTimeout:513

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

Available since 0.4.0

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

Default: null

src

String protected

Defined in src:406

The source of the sound.

Default: null

startTime

Number

Defined in startTime:578

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

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

Default: -1

volume

Number protected

Defined in volume:462

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

Default: 0

Events

complete

Defined in complete:646

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

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

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

Available since 0.4.0

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

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

ready

Defined in ready:603

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

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.