API Documentation for: 0.6.2
Show:

AbstractSoundInstance Class

Extends EventDispatcher
Module: SoundJS

A AbstractSoundInstance is created when any calls to the Sound API method play or createInstance are made. The AbstractSoundInstance 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 AbstractSoundInstance is created, a reference can be stored that can be used to control the audio directly through the AbstractSoundInstance. If the reference is not stored, the AbstractSoundInstance 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.on("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.on("complete", handleComplete);
 myInstance.on("loop", handleLoop);
 myInstance.on("failed", handleFailed);

Constructor

AbstractSoundInstance

(
  • src
  • startTime
  • duration
  • playbackResource
)

Parameters:

  • src String

    The path to and file name of the sound.

  • startTime Number

    Audio sprite property used to apply an offset, in milliseconds.

  • duration Number

    Audio sprite property used to set the time the clip plays for, in milliseconds.

  • playbackResource Object

    Any resource needed by plugin to support audio playback.

Methods

_addLooping

(
  • value
)
protected

Defined in _addLooping:869

Available since 0.6.0

Internal function called when looping is added during playback.

Parameters:

  • value Number

    The number of times to loop after play.

_beginPlaying

(
  • playProps
)
Boolean protected

Defined in _beginPlaying:714

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:

Returns:

Boolean:

If playback succeeded.

_calculateCurrentPosition

() protected

Defined in _calculateCurrentPosition:838

Available since 0.6.0

Internal function that calculates the current position of the playhead and sets this._position to that value

_cleanUp

() protected

Defined in _cleanUp:690

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

_dispatchEvent

(
  • eventObj
  • eventPhase
)
protected

Parameters:

_handleCleanUp

() protected

Defined in _handleCleanUp:910

Available since 0.6.0

Internal function called when AbstractSoundInstance is being cleaned up

_handleLoop

() protected

Defined in _handleLoop:920

Available since 0.6.0

Internal function called when AbstractSoundInstance has played to end and is looping

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

_handleStop

() protected

Defined in _handleStop:900

Available since 0.6.0

Internal function called when stopping playback

_interrupt

() protected

Defined in _interrupt:703

The sound has been interrupted.

_pause

() protected

Defined in _pause:880

Available since 0.6.0

Internal function called when pausing playback

_playFailed

() private

Defined in _playFailed:745

Play has failed, which can happen for a variety of reasons. Cleans up instance and dispatches failed event

_removeLooping

(
  • value
)
protected

Defined in _removeLooping:858

Available since 0.6.0

Internal function called when looping is removed during playback.

Parameters:

  • value Number

    The number of times to loop after play.

_resume

() protected

Defined in _resume:890

Available since 0.6.0

Internal function called when resuming playback

_sendEvent

(
  • type
)
protected

Defined in _sendEvent:679

A helper method that dispatches all events for AbstractSoundInstance.

Parameters:

_updateDuration

() protected

Defined in _updateDuration:828

Available since 0.6.0

Internal function used to get the duration of the audio from the source we'll be playing.

_updateDuration

() protected

Defined in _updateDuration:818

Available since 0.6.0

Internal function used to update the duration of the audio.

_updatePan

() protected

Defined in _updatePan:798

Available since 0.6.0

Internal function used to update the pan

_updatePosition

() protected

Defined in _updatePosition:848

Available since 0.6.0

Internal function used to update the position of the playhead.

_updateStartTime

() protected

Defined in _updateStartTime:808

Available since 0.6.1

Internal function used to update the startTime of the audio.

_updateVolume

() protected

Defined in _updateVolume:788

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

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.

applyPlayProps

(
  • playProps
)
AbstractSoundInstance

Defined in applyPlayProps:392

Available since 0.6.1

Takes an PlayPropsConfig or Object with the same properties and sets them on this instance.

Parameters:

Returns:

AbstractSoundInstance:

A reference to itself, intended for chaining calls.

destroy

()

Defined in destroy:379

Available since 0.6.0

Remove all external references and resources from AbstractSoundInstance. Note this is irreversible and AbstractSoundInstance will no longer work

dispatchEvent

(
  • eventObj
  • [bubbles]
  • [cancelable]
)
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 if necessary with the specified type. This latter approach can be used to avoid event object instantiation for non-bubbling events that may not have any listeners.

  • [bubbles] Boolean optional

    Specifies the bubbles value when a string was passed to eventObj.

  • [cancelable] Boolean optional

    Specifies the cancelable value when a string was passed to eventObj.

Returns:

Boolean:

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

getDuration

() Number deprecated

Defined in getDuration:588

DEPRECATED, please use duration directly as a property

Returns:

Number:

The duration of the sound instance in milliseconds.

getLoop

() Number deprecated

Defined in getLoop:643

Available since 0.6.0

DEPRECATED, please use loop directly as a property

Returns:

getMuted

() Boolean deprecated

Defined in getMuted:494

Available since 0.6.0

DEPRECATED, please use muted directly as a property

Returns:

Boolean:

If the sound is muted.

getPan

() Number deprecated

Defined in getPan:521

DEPRECATED, please use pan directly as a property

Returns:

Number:

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

getPaused

() Boolean deprecated

Defined in getPaused:416

Available since 0.6.0

DEPRECATED, please use paused directly as a property,

Returns:

Boolean:

If the instance is currently paused

getPosition

() Number deprecated

Defined in getPosition:532

DEPRECATED, please use position directly as a property

Returns:

Number:

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

getStartTime

() Number deprecated

Defined in getStartTime:562

DEPRECATED, please use startTime directly as a property

Returns:

Number:

The startTime of the sound instance in milliseconds.

getVolume

() Number deprecated

Defined in getVolume:467

DEPRECATED, please use volume directly as a property

Returns:

Number:

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

() deprecated protected

REMOVED. Removed in favor of using MySuperClass_constructor. See extend and promote for details.

There is an inheritance tutorial distributed with EaselJS in /tutorials/Inheritance.

off

(
  • type
  • listener
  • [useCapture]
)

Inherited from EventDispatcher: off:263

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:

  • 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:187

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 use remove. 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:

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

play

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

Defined in play:307

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({interrupt:createjs.Sound.INTERRUPT_ANY, loop:2, pan:0.5});

Note that if this sound is already playing, this call will still set the passed in parameters.

Parameters Deprecated
The parameters for this method are deprecated in favor of a single parameter that is an Object or PlayPropsConfig.

Parameters:

  • [interrupt="none"|options] String | Object optional

    This parameter will be renamed playProps in the next release.
    This parameter can be an instance of PlayPropsConfig or an Object that contains any or all optional properties by name, including: interrupt, delay, offset, loop, volume, pan, startTime, and duration (see the above code sample).
    OR
    Deprecated 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 defaultInterruptBehavior.

  • [delay=0] Number optional

    Deprecated The amount of time to delay the start of audio playback, in milliseconds.

  • [offset=0] Number optional

    Deprecated The offset from the start of the audio to begin playback, in milliseconds.

  • [loop=0] Number optional

    Deprecated How many times the audio loops when it reaches the end of playback. The default is 0 (no loops), and -1 can be used for infinite playback.

  • [volume=1] Number optional

    Deprecated The volume of the sound, between 0 and 1. Note that the master volume is applied against the individual volume.

  • [pan=0] Number optional

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

Returns:

AbstractSoundInstance:

A reference to itself, intended for chaining calls.

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.

setDuration

(
  • value
)
AbstractSoundInstance deprecated

Defined in setDuration:599

Available since 0.6.0

DEPRECATED, please use duration directly as a property

Parameters:

  • value Number

    The new duration time in milli seconds.

Returns:

AbstractSoundInstance:

Returns reference to itself for chaining calls

setLoop

(
  • value
)
deprecated

Defined in setLoop:655

Available since 0.6.0

DEPRECATED, please use loop directly as a property,

Parameters:

  • value Number

    The number of times to loop after play.

setMuted

(
  • value
)
AbstractSoundInstance deprecated

Defined in setMuted:478

Available since 0.6.0

DEPRECATED, please use muted directly as a property

Parameters:

  • value Boolean

    If the sound should be muted.

Returns:

AbstractSoundInstance:

A reference to itself, intended for chaining calls.

setPan

(
  • value
)
AbstractSoundInstance deprecated

Defined in setPan:506

DEPRECATED, please use pan directly as a property

Parameters:

  • value Number

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

Returns:

AbstractSoundInstance:

Returns reference to itself for chaining calls

setPaused

(
  • value
)
AbstractSoundInstance deprecated

Defined in setPaused:428

Available since 0.6.0

DEPRECATED, please use paused directly as a property

Parameters:

Returns:

AbstractSoundInstance:

A reference to itself, intended for chaining calls.

setPlayback

(
  • value
)
AbstractSoundInstance deprecated

Defined in setPlayback:615

Available since 0.6.0

DEPRECATED, please use playbackResource directly as a property

Parameters:

  • value Object

    The new playback resource.

Returns:

AbstractSoundInstance:

Returns reference to itself for chaining calls

setPlayback

(
  • value
)
Object deprecated

Defined in setPlayback:630

Available since 0.6.0

DEPRECATED, please use playbackResource directly as a property

Parameters:

  • value Object

    The new playback resource.

Returns:

Object:

playback resource used for playing audio

setPosition

(
  • value
)
AbstractSoundInstance deprecated

Defined in setPosition:546

DEPRECATED, please use position directly as a property

Parameters:

  • value Number

    The position to place the playhead, in milliseconds.

Returns:

AbstractSoundInstance:

Returns reference to itself for chaining calls

setStartTime

(
  • value
)
AbstractSoundInstance deprecated

Defined in setStartTime:573

DEPRECATED, please use startTime directly as a property

Parameters:

  • value Number

    The new startTime time in milli seconds.

Returns:

AbstractSoundInstance:

Returns reference to itself for chaining calls

setVolume

(
  • value
)
AbstractSoundInstance deprecated

Defined in setVolume:450

DEPRECATED, please use volume directly as a property

Parameters:

  • value Number

    The volume to set, between 0 and 1.

Returns:

AbstractSoundInstance:

A reference to itself, intended for chaining calls.

stop

() AbstractSoundInstance

Defined in stop:357

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

If you don't want to lose your position use yourSoundInstance.paused = true instead. AbstractSoundInstance/paused.

Example

myInstance.stop();

Returns:

AbstractSoundInstance:

A reference to itself, intended for chaining calls.

toString

() String

Inherited from EventDispatcher: toString:384

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

_listeners

Object protected

Inherited from EventDispatcher: _listeners:99

delayTimeoutId

TimeoutVariable protected

Defined in delayTimeoutId:108

Available since 0.4.0

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

Default: null

duration

Number

Defined in duration:168

Available since 0.6.0

Sets or gets the length of the audio clip, value is in milliseconds.

Default: 0

loop

Number public

Defined in loop:212

Available since 0.6.0

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

Default: 0

muted

Boolean

Defined in muted:227

Available since 0.6.0

Mutes or unmutes the current audio instance.

Default: false

pan

Number

Defined in pan:140

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


Note in WebAudioPlugin this only gives us the "x" value of what is actually 3D audio.

Default: 0

paused

Boolean

Defined in paused:241

Pauses or resumes the current audio instance.

playbackResource

Object

Object that holds plugin specific resource need for audio playback. This is set internally by the plugin. For example, WebAudioPlugin will set an array buffer, HTMLAudioPlugin will set a tag, FlashAudioPlugin will set a flash reference.

Default: null

playState

String

Defined in playState:100

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

Default: null

position

Number

Defined in position:198

Available since 0.6.0

The position of the playhead in milliseconds. This can be set while a sound is playing, paused, or stopped.

Default: 0

src

String

Defined in src:84

The source of the sound.

Default: null

startTime

Number

Defined in startTime:155

Available since 0.6.1

Audio sprite property used to determine the starting offset.

Default: 0

uniqueId

String | Number

Defined in uniqueId:92

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

Default: -1

volume

Number

Defined in volume:124

The volume of the sound, between 0 and 1.

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

Default: 1

Events

complete

Defined in complete:290

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

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

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

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

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.