HTMLAudioSoundInstance Class
HTMLAudioSoundInstance extends the base api of AbstractSoundInstance and is used by HTMLAudioPlugin.
Constructor
HTMLAudioSoundInstance
-
src
-
startTime
-
duration
-
playbackResource
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
- _handleAudioSpriteLoop
- _handleCleanUp
- _handleLoop
- _handleSetPositionSeek
- _handleSoundComplete
- _handleSoundReady
- _handleStop
- _handleTagReady
- _interrupt
- _pause
- _playFailed
- _removeLooping
- _resume
- _sendEvent
- _updateDuration
- _updatePan
- _updatePosition
- _updateStartTime
- _updateVolume
- addEventListener
- applyPlayProps
- destroy
- dispatchEvent
- getDuration deprecated
- getLoop deprecated
- getMuted deprecated
- getPan deprecated
- getPaused deprecated
- getPosition deprecated
- getStartTime deprecated
- getVolume deprecated
- hasEventListener
- initialize deprecated
- off
- on
- play
- removeAllEventListeners
- removeEventListener
- setDuration deprecated
- setLoop deprecated
- setMuted deprecated
- setPan deprecated
- setPaused deprecated
- setPlayback deprecated
- setPosition deprecated
- setStartTime deprecated
- setVolume deprecated
- stop
- toString
- willTrigger
Properties
Events
Methods
_addLooping
-
value
Internal function called when looping is added during playback.
Parameters:
-
value
NumberThe 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:
-
playProps
PlayPropsConfigA 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
_handleAudioSpriteLoop
-
event
Timer used to loop audio sprites. NOTE because of the inaccuracies in the timeupdate event (15 - 250ms) and in setting the tag to the desired timed (up to 300ms), it is strongly recommended not to loop audio sprites with HTML Audio if smooth looping is desired
Parameters:
-
event
Object
_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
_handleSetPositionSeek
-
event
Used to enable setting position, as we need to wait for that seek to be done before we add back our loop handling seek listener
Parameters:
-
event
Object
_handleSoundComplete
-
event
Audio has finished playing. Manually loop it if required.
Parameters:
-
event
Object
_handleSoundReady
()
protected
Handles starting playback when the sound is ready for playing.
_handleStop
()
protected
Internal function called when stopping playback
_handleTagReady
-
event
Used to handle when a tag is not ready for immediate playback when it is returned from the HTMLAudioTagPool.
Parameters:
-
event
Object
_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:
-
value
NumberThe 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:
-
type
StringThe event type
_updateDuration
()
protected
Internal function used to update the duration of the audio.
_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:
-
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
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
()
Remove all external references and resources from AbstractSoundInstance. Note this is irreversible and AbstractSoundInstance will no longer work
dispatchEvent
-
eventObj
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:
Returns:
Returns the value of eventObj.defaultPrevented.
getDuration
()
Number
deprecated
DEPRECATED, please use duration directly as a property
Returns:
The duration of the sound instance in milliseconds.
getMuted
()
Boolean
deprecated
DEPRECATED, please use muted directly as a property
Returns:
If the sound is muted.
getPan
()
Number
deprecated
DEPRECATED, please use pan directly as a property
Returns:
The value of the pan, between -1 (left) and 1 (right).
getPaused
()
Boolean
deprecated
DEPRECATED, please use paused directly as a property,
Returns:
If the instance is currently paused
getPosition
()
Number
deprecated
DEPRECATED, please use position directly as a property
Returns:
The position of the playhead in the sound, in milliseconds.
getStartTime
()
Number
deprecated
DEPRECATED, please use startTime directly as a property
Returns:
The startTime of the sound instance in milliseconds.
getVolume
()
Number
deprecated
DEPRECATED, please use volume directly as a property
Returns:
The current volume of the sound instance.
hasEventListener
-
type
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.
initialize
()
deprecated
protected
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.
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 created anonymous function is returned for use with .removeEventListener (or .off).
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
-
[interrupt="none"|options]
-
[delay=0]
-
[offset=0]
-
[loop=0]
-
[volume=1]
-
[pan=0]
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 optionalThis 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 asINTERRUPT_TYPE
constants on the Sound class, with the default defined by defaultInterruptBehavior. -
[delay=0]
Number optionalDeprecated The amount of time to delay the start of audio playback, in milliseconds.
-
[offset=0]
Number optionalDeprecated The offset from the start of the audio to begin playback, in milliseconds.
-
[loop=0]
Number optionalDeprecated 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 optionalDeprecated The volume of the sound, between 0 and 1. Note that the master volume is applied against the individual volume.
-
[pan=0]
Number optionalDeprecated 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:
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);
setDuration
-
value
DEPRECATED, 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
DEPRECATED, please use loop directly as a property,
Parameters:
-
value
NumberThe number of times to loop after play.
setMuted
-
value
DEPRECATED, 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
DEPRECATED, 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
DEPRECATED, please use paused directly as a property
Parameters:
-
value
Boolean
Returns:
A reference to itself, intended for chaining calls.
setPlayback
-
value
DEPRECATED, please use playbackResource directly as a property
Parameters:
-
value
ObjectThe new playback resource.
Returns:
Returns reference to itself for chaining calls
setPosition
-
value
DEPRECATED, 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
DEPRECATED, 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
DEPRECATED, 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.
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.
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:
-
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
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.