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
Parameters:
-
srcStringThe path to and file name of the sound.
-
startTimeNumberAudio sprite property used to apply an offset, in milliseconds.
-
durationNumberAudio sprite property used to set the time the clip plays for, in milliseconds.
-
playbackResourceObjectAny 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
Internal function called when looping is added during playback.
Parameters:
-
valueNumberThe number of times to loop after play.
_beginPlaying
-
playProps
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:
-
playPropsPlayPropsConfigA PlayPropsConfig object.
Returns:
If playback succeeded.
_calculateCurrentPosition
()
protected
Internal function that calculates the current position of the playhead and sets this._position to that value
_cleanUp
()
protected
Clean up the instance. Remove references and clean up any additional properties such as timers.
_dispatchEvent
-
eventObj -
eventPhase
_getDuration
()
Number
protected
Please use duration directly as a property
Returns:
The duration of the sound instance in milliseconds.
_getMuted
()
Boolean
protected
Please use muted directly as a property
Returns:
If the sound is muted.
_getPan
()
Number
protected
Please use pan directly as a property
Returns:
The value of the pan, between -1 (left) and 1 (right).
_getPaused
()
Boolean
protected
Please use paused directly as a property.
Returns:
If the instance is currently paused
_getPlaybackResource
-
value
Please use playbackResource directly as a property
Parameters:
-
valueObjectThe new playback resource.
Returns:
playback resource used for playing audio
_getPosition
()
Number
protected
Please use position directly as a property
Returns:
The position of the playhead in the sound, in milliseconds.
_getStartTime
()
Number
protected
Please use startTime directly as a property
Returns:
The startTime of the sound instance in milliseconds.
_getVolume
()
Number
protected
Please use volume directly as a property
Returns:
The current volume of the sound instance.
_handleCleanUp
()
protected
Internal function called when AbstractSoundInstance is being cleaned up
_handleLoop
()
protected
Internal function called when AbstractSoundInstance has played to end and is looping
_handleSoundComplete
-
event
Audio has finished playing. Manually loop it if required.
Parameters:
-
eventObject
_handleSoundReady
()
protected
Handles starting playback when the sound is ready for playing.
_handleStop
()
protected
Internal function called when stopping playback
_interrupt
()
protected
The sound has been interrupted.
_pause
()
protected
Internal function called when pausing playback
_playFailed
()
private
Play has failed, which can happen for a variety of reasons. Cleans up instance and dispatches failed event
_removeLooping
-
value
Internal function called when looping is removed during playback.
Parameters:
-
valueNumberThe number of times to loop after play.
_resume
()
protected
Internal function called when resuming playback
_sendEvent
-
type
A helper method that dispatches all events for AbstractSoundInstance.
Parameters:
-
typeStringThe event type
_setDuration
-
value
Please use duration directly as a property
Parameters:
-
valueNumberThe new duration time in milli seconds.
Returns:
Returns reference to itself for chaining calls
_setLoop
-
value
Please use loop directly as a property
Parameters:
-
valueNumberThe number of times to loop after play.
_setMuted
-
value
Please use muted directly as a property
Parameters:
-
valueBooleanIf the sound should be muted.
Returns:
A reference to itself, intended for chaining calls.
_setPan
-
value
Please use pan directly as a property
Parameters:
-
valueNumberThe pan value, between -1 (left) and 1 (right).
Returns:
Returns reference to itself for chaining calls
_setPaused
-
value
Please use paused directly as a property
Parameters:
-
valueBoolean
Returns:
A reference to itself, intended for chaining calls.
_setPlaybackResource
-
value
Please use playbackResource directly as a property
Parameters:
-
valueObjectThe new playback resource.
Returns:
Returns reference to itself for chaining calls
_setPosition
-
value
Please use position directly as a property
Parameters:
-
valueNumberThe position to place the playhead, in milliseconds.
Returns:
Returns reference to itself for chaining calls
_setStartTime
-
value
Please use startTime directly as a property
Parameters:
-
valueNumberThe new startTime time in milli seconds.
Returns:
Returns reference to itself for chaining calls
_setVolume
-
value
Please use volume directly as a property
Parameters:
-
valueNumberThe volume to set, between 0 and 1.
Returns:
A reference to itself, intended for chaining calls.
_updateDuration
()
protected
Internal function used to update the duration of the audio.
_updateDuration
()
protected
Internal function used to get the duration of the audio from the source we'll be playing.
_updatePan
()
protected
Internal function used to update the pan
_updatePosition
()
protected
Internal function used to update the position of the playhead.
_updateStartTime
()
protected
Internal function used to update the startTime of the audio.
_updateVolume
()
protected
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]
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:
-
typeStringThe string type of the event.
-
listenerFunction | 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
Takes an PlayPropsConfig or Object with the same properties and sets them on this instance.
Parameters:
-
playPropsPlayPropsConfig | ObjectA PlayPropsConfig or object containing the same properties.
Returns:
A reference to itself, intended for chaining calls.
destroy
()
Remove all external references and resources from AbstractSoundInstance. Note this is irreversible and AbstractSoundInstance will no longer work
dispatchEvent
-
eventObj -
[bubbles] -
[cancelable]
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:
-
eventObjObject | 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
bubblesvalue when a string was passed to eventObj. -
[cancelable]Boolean optionalSpecifies the
cancelablevalue when a string was passed to eventObj.
Returns:
Returns false if preventDefault() was called on a cancelable event, true otherwise.
hasEventListener
-
type
Indicates whether there is at least one listener for the specified event type.
Parameters:
-
typeStringThe string type of the event.
Returns:
Returns true if there is at least one listener for the specified event.
off
-
type -
listener -
[useCapture]
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]
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:
-
typeStringThe string type of the event.
-
listenerFunction | 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
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:
-
propsObject | 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]
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]
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
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.
willTrigger
-
type
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:
-
typeStringThe string type of the event.
Returns:
Returns true if there is at least one listener for the specified event.
Properties
delayTimeoutId
TimeoutVariable
protected
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
loop
Number
public
The number of play loops remaining. Negative values will loop infinitely.
Default: 0
pan
Number
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
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
The play state of the sound. Play states are defined as constants on Sound.
Default: null
position
Number
The position of the playhead in milliseconds. This can be set while a sound is playing, paused, or stopped.
Default: 0
volume
Number
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
The event that is fired when playback completes. This means that the sound has finished playing in its entirety, including its loop iterations.
failed
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
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
The event that is fired when a sound has completed playing but has loops remaining.