AbstractSoundInstance Class
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
Defined in
AbstractSoundInstance:33
Parameters:
-
src
StringThe path to and file name of the sound.
-
startTime
NumberAudio sprite property used to apply an offset, in milliseconds.
-
duration
NumberAudio sprite property used to set the time the clip plays for, in milliseconds.
-
playbackResource
ObjectAny resource needed by plugin to support audio playback.
Item Index
Methods
- _addLooping
- _beginPlaying
- _calculateCurrentPosition
- _cleanUp
- _dispatchEvent
- _getDuration
- _getLoop
- _getMuted
- _getPan
- _getPaused
- _getPlaybackResource
- _getPosition
- _getStartTime
- _getVolume
- _handleCleanUp
- _handleLoop
- _handleSoundComplete
- _handleSoundReady
- _handleStop
- _interrupt
- _pause
- _playFailed
- _removeLooping
- _resume
- _sendEvent
- _setDuration
- _setLoop
- _setMuted
- _setPan
- _setPaused
- _setPlaybackResource
- _setPosition
- _setStartTime
- _setVolume
- _updateDuration
- _updateDuration
- _updatePan
- _updatePosition
- _updateStartTime
- _updateVolume
- addEventListener
- applyPlayProps
- destroy
- dispatchEvent
- hasEventListener
- off
- on
- play
- removeAllEventListeners
- removeEventListener
- stop
- toString
- willTrigger
Properties
Events
Methods
_addLooping
-
value
Defined in
_addLooping:845
Available since 0.6.0
Internal function called when looping is added during playback.
Parameters:
-
value
NumberThe number of times to loop after play.
_beginPlaying
-
playProps
Defined in
_beginPlaying:690
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:
-
playProps
PlayPropsConfigA PlayPropsConfig object.
Returns:
If playback succeeded.
_calculateCurrentPosition
()
protected
Defined in
_calculateCurrentPosition:814
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:666
Clean up the instance. Remove references and clean up any additional properties such as timers.
_getDuration
()
Number
protected
Defined in
_getDuration:570
Please use duration directly as a property
Returns:
The duration of the sound instance in milliseconds.
_getLoop
()
Number
protected
Defined in
_getLoop:621
Available since 0.6.0
Please use loop directly as a property
Returns:
_getMuted
()
Boolean
protected
Defined in
_getMuted:483
Available since 0.6.0
Please use muted directly as a property
Returns:
If the sound is muted.
_getPan
()
Number
protected
Defined in
_getPan:508
Please use pan directly as a property
Returns:
The value of the pan, between -1 (left) and 1 (right).
_getPaused
()
Boolean
protected
Defined in
_getPaused:410
Available since 0.6.0
Please use paused directly as a property.
Returns:
If the instance is currently paused
_getPlaybackResource
-
value
Defined in
_getPlaybackResource:609
Available since 0.6.0
Please use playbackResource directly as a property
Parameters:
-
value
ObjectThe new playback resource.
Returns:
playback resource used for playing audio
_getPosition
()
Number
protected
Defined in
_getPosition:518
Please use position directly as a property
Returns:
The position of the playhead in the sound, in milliseconds.
_getStartTime
()
Number
protected
Defined in
_getStartTime:546
Please use startTime directly as a property
Returns:
The startTime of the sound instance in milliseconds.
_getVolume
()
Number
protected
Defined in
_getVolume:458
Please use volume directly as a property
Returns:
The current volume of the sound instance.
_handleCleanUp
()
protected
Defined in
_handleCleanUp:886
Available since 0.6.0
Internal function called when AbstractSoundInstance is being cleaned up
_handleLoop
()
protected
Defined in
_handleLoop:896
Available since 0.6.0
Internal function called when AbstractSoundInstance has played to end and is looping
_handleSoundComplete
-
event
Defined in
_handleSoundComplete:733
Audio has finished playing. Manually loop it if required.
Parameters:
-
event
Object
_handleSoundReady
()
protected
Defined in
_handleSoundReady:755
Handles starting playback when the sound is ready for playing.
_handleStop
()
protected
Defined in
_handleStop:876
Available since 0.6.0
Internal function called when stopping playback
_pause
()
protected
Defined in
_pause:856
Available since 0.6.0
Internal function called when pausing playback
_playFailed
()
private
Defined in
_playFailed:721
Play has failed, which can happen for a variety of reasons. Cleans up instance and dispatches failed event
_removeLooping
-
value
Defined in
_removeLooping:834
Available since 0.6.0
Internal function called when looping is removed during playback.
Parameters:
-
value
NumberThe number of times to loop after play.
_resume
()
protected
Defined in
_resume:866
Available since 0.6.0
Internal function called when resuming playback
_sendEvent
-
type
Defined in
_sendEvent:655
A helper method that dispatches all events for AbstractSoundInstance.
Parameters:
-
type
StringThe event type
_setDuration
-
value
Defined in
_setDuration:580
Available since 0.6.0
Please use duration directly as a property
Parameters:
-
value
NumberThe new duration time in milli seconds.
Returns:
Returns reference to itself for chaining calls
_setLoop
-
value
Defined in
_setLoop:632
Available since 0.6.0
Please use loop directly as a property
Parameters:
-
value
NumberThe number of times to loop after play.
_setMuted
-
value
Defined in
_setMuted:468
Available since 0.6.0
Please use muted directly as a property
Parameters:
-
value
BooleanIf the sound should be muted.
Returns:
A reference to itself, intended for chaining calls.
_setPan
-
value
Defined in
_setPan:494
Please use pan directly as a property
Parameters:
-
value
NumberThe pan value, between -1 (left) and 1 (right).
Returns:
Returns reference to itself for chaining calls
_setPaused
-
value
Defined in
_setPaused:421
Available since 0.6.0
Please use paused directly as a property
Parameters:
-
value
Boolean
Returns:
A reference to itself, intended for chaining calls.
_setPlaybackResource
-
value
Defined in
_setPlaybackResource:595
Available since 0.6.0
Please use playbackResource directly as a property
Parameters:
-
value
ObjectThe new playback resource.
Returns:
Returns reference to itself for chaining calls
_setPosition
-
value
Defined in
_setPosition:531
Please use position directly as a property
Parameters:
-
value
NumberThe position to place the playhead, in milliseconds.
Returns:
Returns reference to itself for chaining calls
_setStartTime
-
value
Defined in
_setStartTime:556
Please use startTime directly as a property
Parameters:
-
value
NumberThe new startTime time in milli seconds.
Returns:
Returns reference to itself for chaining calls
_setVolume
-
value
Defined in
_setVolume:442
Please use volume directly as a property
Parameters:
-
value
NumberThe volume to set, between 0 and 1.
Returns:
A reference to itself, intended for chaining calls.
_updateDuration
()
protected
Defined in
_updateDuration:794
Available since 0.6.0
Internal function used to update the duration of the audio.
_updateDuration
()
protected
Defined in
_updateDuration:804
Available since 0.6.0
Internal function used to get the duration of the audio from the source we'll be playing.
_updatePan
()
protected
Defined in
_updatePan:774
Available since 0.6.0
Internal function used to update the pan
_updatePosition
()
protected
Defined in
_updatePosition:824
Available since 0.6.0
Internal function used to update the position of the playhead.
_updateStartTime
()
protected
Defined in
_updateStartTime:784
Available since 0.6.1
Internal function used to update the startTime of the audio.
_updateVolume
()
protected
Defined in
_updateVolume:764
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]
Inherited from
EventDispatcher:
addEventListener:140
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
StringThe string type of the event.
-
listener
Function | ObjectAn object with a handleEvent method, or a function that will be called when the event is dispatched.
-
[useCapture]
Boolean optionalFor events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
applyPlayProps
-
playProps
Defined in
applyPlayProps:386
Available since 0.6.1
Takes an PlayPropsConfig or Object with the same properties and sets them on this instance.
Parameters:
-
playProps
PlayPropsConfig | ObjectA PlayPropsConfig or object containing the same properties.
Returns:
A reference to itself, intended for chaining calls.
destroy
()
Defined in
destroy:373
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]
Inherited from
EventDispatcher:
dispatchEvent:285
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 | EventAn 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 optionalSpecifies the
bubbles
value when a string was passed to eventObj. -
[cancelable]
Boolean optionalSpecifies the
cancelable
value when a string was passed to eventObj.
Returns:
Returns false if preventDefault()
was called on a cancelable event, true otherwise.
hasEventListener
-
type
Inherited from
EventDispatcher:
hasEventListener:339
Indicates whether there is at least one listener for the specified event type.
Parameters:
-
type
StringThe string type of the event.
Returns:
Returns true if there is at least one listener for the specified event.
off
-
type
-
listener
-
[useCapture]
Inherited from
EventDispatcher:
off:249
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.
on
-
type
-
listener
-
[scope]
-
[once=false]
-
[data]
-
[useCapture=false]
Inherited from
EventDispatcher:
on:173
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
StringThe string type of the event.
-
listener
Function | ObjectAn object with a handleEvent method, or a function that will be called when the event is dispatched.
-
[scope]
Object optionalThe 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 optionalIf true, the listener will remove itself after the first time it is triggered.
-
[data]
optionalArbitrary data that will be included as the second parameter when the listener is called.
-
[useCapture=false]
Boolean optionalFor events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
Returns:
Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.
play
-
props
Defined in
play:320
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:
-
props
Object | PlayPropsConfigA PlayPropsConfig instance, or an object that contains the parameters to play a sound. See the PlayPropsConfig for more info.
Returns:
A reference to itself, intended for chaining calls.
removeAllEventListeners
-
[type]
Inherited from
EventDispatcher:
removeAllEventListeners:263
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 optionalThe string type of the event. If omitted, all listeners for all types will be removed.
removeEventListener
-
type
-
listener
-
[useCapture]
Inherited from
EventDispatcher:
removeEventListener:219
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);
stop
()
AbstractSoundInstance
Defined in
stop:351
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:
A reference to itself, intended for chaining calls.
toString
()
String
Inherited from
EventDispatcher:
toString:370
Returns:
a string representation of the instance.
willTrigger
-
type
Inherited from
EventDispatcher:
willTrigger:350
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
StringThe string type of the event.
Returns:
Returns true
if there is at least one listener for the specified event.
Properties
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:173
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:223
Available since 0.6.0
The number of play loops remaining. Negative values will loop infinitely.
Default: 0
muted
Boolean
Defined in
muted:240
Available since 0.6.0
Mutes or unmutes the current audio instance.
Default: false
pan
Number
Defined in
pan:142
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
playbackResource
Object
Defined in
playbackResource:189
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:207
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
startTime
Number
Defined in
startTime:158
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:307
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.
failed
Defined in
failed:289
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.
interrupted
Defined in
interrupted:280
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.
loop
Defined in
loop:299
Available since 0.4.0
The event that is fired when a sound has completed playing but has loops remaining.
succeeded
Defined in
succeeded:272
Available since 0.4.0
The event that is fired when playback has started successfully.