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.
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);AbstractSoundInstancesrc
startTime
duration
playbackResource
Defined in
AbstractSoundInstance:33
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.
_addLoopingvalue
Defined in
_addLooping:845
Available since 0.6.0
Internal function called when looping is added during playback.
value
Number
The number of times to loop after play.
_beginPlayingplayProps
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.
playProps
PlayPropsConfig
A PlayPropsConfig object.
If playback succeeded.
_calculateCurrentPosition
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
Defined in
_cleanUp:666
Clean up the instance. Remove references and clean up any additional properties such as timers.
_getDuration
Defined in
_getDuration:570
Please use duration directly as a property
The duration of the sound instance in milliseconds.
_getLoop
Defined in
_getLoop:621
Available since 0.6.0
Please use loop directly as a property
_getMuted
Defined in
_getMuted:483
Available since 0.6.0
Please use muted directly as a property
If the sound is muted.
_getPan
Defined in
_getPan:508
Please use pan directly as a property
The value of the pan, between -1 (left) and 1 (right).
_getPaused
Defined in
_getPaused:410
Available since 0.6.0
Please use paused directly as a property.
If the instance is currently paused
_getPlaybackResourcevalue
Defined in
_getPlaybackResource:609
Available since 0.6.0
Please use playbackResource directly as a property
value
Object
The new playback resource.
playback resource used for playing audio
_getPosition
Defined in
_getPosition:518
Please use position directly as a property
The position of the playhead in the sound, in milliseconds.
_getStartTime
Defined in
_getStartTime:546
Please use startTime directly as a property
The startTime of the sound instance in milliseconds.
_getVolume
Defined in
_getVolume:458
Please use volume directly as a property
The current volume of the sound instance.
_handleCleanUp
Defined in
_handleCleanUp:886
Available since 0.6.0
Internal function called when AbstractSoundInstance is being cleaned up
_handleLoop
Defined in
_handleLoop:896
Available since 0.6.0
Internal function called when AbstractSoundInstance has played to end and is looping
_handleSoundCompleteevent
Defined in
_handleSoundComplete:733
Audio has finished playing. Manually loop it if required.
event
Object
_handleSoundReady
Defined in
_handleSoundReady:755
Handles starting playback when the sound is ready for playing.
_handleStop
Defined in
_handleStop:876
Available since 0.6.0
Internal function called when stopping playback
_pause
Defined in
_pause:856
Available since 0.6.0
Internal function called when pausing playback
_playFailed
Defined in
_playFailed:721
Play has failed, which can happen for a variety of reasons. Cleans up instance and dispatches failed event
_removeLoopingvalue
Defined in
_removeLooping:834
Available since 0.6.0
Internal function called when looping is removed during playback.
value
Number
The number of times to loop after play.
_resume
Defined in
_resume:866
Available since 0.6.0
Internal function called when resuming playback
_sendEventtype
Defined in
_sendEvent:655
A helper method that dispatches all events for AbstractSoundInstance.
type
String
The event type
_setDurationvalue
Defined in
_setDuration:580
Available since 0.6.0
Please use duration directly as a property
value
Number
The new duration time in milli seconds.
Returns reference to itself for chaining calls
_setLoopvalue
Defined in
_setLoop:632
Available since 0.6.0
Please use loop directly as a property
value
Number
The number of times to loop after play.
_setMutedvalue
Defined in
_setMuted:468
Available since 0.6.0
Please use muted directly as a property
value
Boolean
If the sound should be muted.
A reference to itself, intended for chaining calls.
_setPanvalue
Defined in
_setPan:494
Please use pan directly as a property
value
Number
The pan value, between -1 (left) and 1 (right).
Returns reference to itself for chaining calls
_setPausedvalue
Defined in
_setPaused:421
Available since 0.6.0
Please use paused directly as a property
value
Boolean
A reference to itself, intended for chaining calls.
_setPlaybackResourcevalue
Defined in
_setPlaybackResource:595
Available since 0.6.0
Please use playbackResource directly as a property
value
Object
The new playback resource.
Returns reference to itself for chaining calls
_setPositionvalue
Defined in
_setPosition:531
Please use position directly as a property
value
Number
The position to place the playhead, in milliseconds.
Returns reference to itself for chaining calls
_setStartTimevalue
Defined in
_setStartTime:556
Please use startTime directly as a property
value
Number
The new startTime time in milli seconds.
Returns reference to itself for chaining calls
_setVolumevalue
Defined in
_setVolume:442
Please use volume directly as a property
value
Number
The volume to set, between 0 and 1.
A reference to itself, intended for chaining calls.
_updateDuration
Defined in
_updateDuration:794
Available since 0.6.0
Internal function used to update the duration of the audio.
_updateDuration
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
Defined in
_updatePan:774
Available since 0.6.0
Internal function used to update the pan
_updatePosition
Defined in
_updatePosition:824
Available since 0.6.0
Internal function used to update the position of the playhead.
_updateStartTime
Defined in
_updateStartTime:784
Available since 0.6.1
Internal function used to update the startTime of the audio.
_updateVolume
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.
addEventListenertype
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.
displayObject.addEventListener("click", handleClick);
function handleClick(event) {
// Click happened.
}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.
applyPlayPropsplayProps
Defined in
applyPlayProps:386
Available since 0.6.1
Takes an PlayPropsConfig or Object with the same properties and sets them on this instance.
playProps
PlayPropsConfig | Object
A PlayPropsConfig or object containing the same properties.
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
dispatchEventeventObj
[bubbles]
[cancelable]
Inherited from
EventDispatcher:
dispatchEvent:285
Dispatches the specified event to all listeners.
// Use a string event
this.dispatchEvent("complete");
// Use an Event instance
var event = new createjs.Event("progress");
this.dispatchEvent(event);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 false if preventDefault() was called on a cancelable event, true otherwise.
hasEventListenertype
Inherited from
EventDispatcher:
hasEventListener:339
Indicates whether there is at least one listener for the specified event type.
type
String
The string type of the event.
Returns true if there is at least one listener for the specified event.
offtype
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.
ontype
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.
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();
}
}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 the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.
playprops
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).
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.
props
Object | PlayPropsConfig
A PlayPropsConfig instance, or an object that contains the parameters to play a sound. See the PlayPropsConfig for more info.
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.
// Remove all listeners
displayObject.removeAllEventListeners();
// Remove all click listeners
displayObject.removeAllEventListeners("click");[type]
String
optional
The string type of the event. If omitted, all listeners for all types will be removed.
removeEventListenertype
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.
displayObject.removeEventListener("click", handleClick);stop
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.
myInstance.stop();A reference to itself, intended for chaining calls.
toStringInherited from
EventDispatcher:
toString:370
a string representation of the instance.
willTriggertype
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.
type
String
The string type of the event.
Returns true if there is at least one listener for the specified event.
delayTimeoutId
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
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
Defined in
loop:223
Available since 0.6.0
The number of play loops remaining. Negative values will loop infinitely.
Default: 0
muted
Defined in
muted:240
Available since 0.6.0
Mutes or unmutes the current audio instance.
Default: false
pan
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
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
Defined in
playState:100
The play state of the sound. Play states are defined as constants on Sound.
Default: null
position
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
Defined in
startTime:158
Available since 0.6.1
Audio sprite property used to determine the starting offset.
Default: 0
uniqueId
Defined in
uniqueId:92
The unique ID of the instance. This is set by Sound.
Default: -1
volume
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
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.