Mirror Engine API / SoundInstance
Class: SoundInstance
A SoundInstance plays a Sound.
Extends
Extended by
Constructors
new SoundInstance()
new SoundInstance(
manager: SoundManager,
sound: Sound,
options: {
duration: number;
loop: boolean;
onEnd: Function;
onPause: Function;
onPlay: Function;
onResume: Function;
onStop: Function;
pitch: number;
startTime: number;
volume: number;
}): SoundInstance
Create a new SoundInstance instance.
Parameters
manager
The sound manager.
sound
The sound to play.
options
Options for the instance.
duration?
number
The total time after the startTime in seconds when playback will stop or restart if loop is true. Defaults to 0.
loop?
boolean
Whether the sound should loop when it reaches the end or not. Defaults to false.
onEnd?
Function called when the instance ends.
onPause?
Function called when the instance is paused.
onPlay?
Function called when the instance starts playing.
onResume?
Function called when the instance is resumed.
onStop?
Function called when the instance is stopped.
pitch?
number
The relative pitch. Defaults to 1 (plays at normal pitch).
startTime?
number
The time from which the playback will start in seconds. Default is 0 to start at the beginning. Defaults to 0.
volume?
number
The playback volume, between 0 and 1. Defaults to 1.
Returns
Overrides
EventHandler.constructor
Properties
source
source: AudioBufferSourceNode = null
Gets the source that plays the sound resource. If the Web Audio API is not supported the type of source is Audio. Source is only available after calling play.
currentTime
Get Signature
get currentTime(): number
Gets the current time of the sound that is playing.
Returns
number
Set Signature
set currentTime(value: number): void
Sets the current time of the sound that is playing. If the value provided is bigger than the duration of the instance it will wrap from the beginning.
Parameters
value
number
Returns
void
duration
Get Signature
get duration(): number
Gets the duration of the sound that the instance will play starting from startTime.
Returns
number
Set Signature
set duration(value: number): void
Sets the duration of the sound that the instance will play starting from startTime.
Parameters
value
number
Returns
void
isPaused
Get Signature
get isPaused(): boolean
Gets whether the instance is currently paused.
Returns
boolean
isPlaying
Get Signature
get isPlaying(): boolean
Gets whether the instance is currently playing.
Returns
boolean
isStopped
Get Signature
get isStopped(): boolean
Gets whether the instance is currently stopped.
Returns
boolean
isSuspended
Get Signature
get isSuspended(): boolean
Gets whether the instance is currently suspended because the window is not focused.
Returns
boolean
loop
Get Signature
get loop(): boolean
Gets whether the instance will restart when it finishes playing.
Returns
boolean
Set Signature
set loop(value: boolean): void
Sets whether the instance will restart when it finishes playing.
Parameters
value
boolean
Returns
void
pitch
Get Signature
get pitch(): number
Gets the pitch modifier to play the sound with.
Returns
number
Set Signature
set pitch(pitch: number): void
Sets the pitch modifier to play the sound with. Must be larger than 0.01.
Parameters
pitch
number
Returns
void
sound
Get Signature
get sound(): Sound
Gets the sound resource that the instance will play.
Returns
Set Signature
set sound(value: Sound): void
Sets the sound resource that the instance will play.
Parameters
value
Returns
void
startTime
Get Signature
get startTime(): number
Gets the start time from which the sound will start playing.
Returns
number
Set Signature
set startTime(value: number): void
Sets the start time from which the sound will start playing.
Parameters
value
number
Returns
void
volume
Get Signature
get volume(): number
Gets the volume modifier to play the sound with. In range 0-1.
Returns
number
Set Signature
set volume(volume: number): void
Sets the volume modifier to play the sound with. In range 0-1.
Parameters
volume
number
Returns
void
Methods
clearExternalNodes()
clearExternalNodes(): void
Clears any external nodes set by SoundInstance#setExternalNodes.
Returns
void
fire()
fire(
name: string,
arg1?: any,
arg2?: any,
arg3?: any,
arg4?: any,
arg5?: any,
arg6?: any,
arg7?: any,
arg8?: any): EventHandler
Fire an event, all additional arguments are passed on to the event listener.
Parameters
name
string
Name of event to fire.
arg1?
any
First argument that is passed to the event handler.
arg2?
any
Second argument that is passed to the event handler.
arg3?
any
Third argument that is passed to the event handler.
arg4?
any
Fourth argument that is passed to the event handler.
arg5?
any
Fifth argument that is passed to the event handler.
arg6?
any
Sixth argument that is passed to the event handler.
arg7?
any
Seventh argument that is passed to the event handler.
arg8?
any
Eighth argument that is passed to the event handler.
Returns
Self for chaining.
Example
obj.fire('test', 'This is the message')
Inherited from
getExternalNodes()
getExternalNodes(): AudioNode[]
Gets any external nodes set by SoundInstance#setExternalNodes.
Returns
Returns an array that contains the two nodes set by SoundInstance#setExternalNodes.
hasEvent()
hasEvent(name: string): boolean
Test if there are any handlers bound to an event name.
Parameters
name
string
The name of the event to test.
Returns
boolean
True if the object has handlers bound to the specified event name.
Example
obj.on('test', () => {}) // bind an event to 'test'
obj.hasEvent('test') // returns true
obj.hasEvent('hello') // returns false
Inherited from
off()
off(
name?: string,
callback?: HandleEventCallback,
scope?: any): EventHandler
Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.
Parameters
name?
string
Name of the event to unbind.
callback?
HandleEventCallback
Function to be unbound.
scope?
any
Scope that was used as the this when the event is fired.
Returns
Self for chaining.
Example
const handler = () => {}
obj.on('test', handler)
obj.off() // Removes all events
obj.off('test') // Removes all events called 'test'
obj.off('test', handler) // Removes all handler functions, called 'test'
obj.off('test', handler, this) // Removes all handler functions, called 'test' with scope this
Inherited from
on()
on(
name: string,
callback: HandleEventCallback,
scope?: any): EventHandle
Attach an event handler to an event.
Parameters
name
string
Name of the event to bind the callback to.
callback
HandleEventCallback
Function that is called when event is fired. Note the callback is limited to 8 arguments.
scope?
any = ...
Object to use as 'this' when the event is fired, defaults to current this.
Returns
Can be used for removing event in the future.
Examples
obj.on('test', (a, b) => {
console.log(a + b)
})
obj.fire('test', 1, 2) // prints 3 to the console
const evt = obj.on('test', (a, b) => {
console.log(a + b)
})
// some time later
evt.off()
Inherited from
once()
once(
name: string,
callback: HandleEventCallback,
scope?: any): EventHandle
Attach an event handler to an event. This handler will be removed after being fired once.
Parameters
name
string
Name of the event to bind the callback to.
callback
HandleEventCallback
Function that is called when event is fired. Note the callback is limited to 8 arguments.
scope?
any = ...
Object to use as 'this' when the event is fired, defaults to current this.
Returns
- can be used for removing event in the future.
Example
obj.once('test', (a, b) => {
console.log(a + b)
})
obj.fire('test', 1, 2) // prints 3 to the console
obj.fire('test', 1, 2) // not going to get handled
Inherited from
pause()
pause(): boolean
Pauses playback of sound. Call resume() to resume playback from the same position.
Returns
boolean
Returns true if the sound was paused.
play()
play(): boolean
Attempt to begin playback the sound. If the AudioContext is suspended, the audio will only start once it's resumed. If the sound is already playing, this will restart the sound.
Returns
boolean
True if the sound was started immediately.
resume()
resume(): boolean
Resumes playback of the sound. Playback resumes at the point that the audio was paused.
Returns
boolean
Returns true if the sound was resumed.
setExternalNodes()
setExternalNodes(firstNode: AudioNode, lastNode?: AudioNode): void
Connects external Web Audio API nodes. You need to pass the first node of the node graph that you created externally and the last node of that graph. The first node will be connected to the audio source and the last node will be connected to the destination of the AudioContext (e.g. speakers). Requires Web Audio API support.
Parameters
firstNode
The first node that will be connected to the audio source of sound instances.
lastNode?
The last node that will be connected to the destination of the AudioContext. If unspecified then the firstNode will be connected to the destination instead.
Returns
void
Example
const context = app.systems.sound.context
const analyzer = context.createAnalyzer()
const distortion = context.createWaveShaper()
const filter = context.createBiquadFilter()
analyzer.connect(distortion)
distortion.connect(filter)
instance.setExternalNodes(analyzer, filter)
stop()
stop(): boolean
Stops playback of sound. Calling play() again will restart playback from the beginning of the sound.
Returns
boolean
Returns true if the sound was stopped.
Events
EVENT_END
static EVENT_END: string = 'end';
Fired when the sound currently played by the instance ends.
Example
instance.on('end', () => {
console.log('Instance ended')
})
EVENT_PAUSE
static EVENT_PAUSE: string = 'pause';
Fired when the instance is paused.
Example
instance.on('pause', () => {
console.log('Instance paused')
})
EVENT_PLAY
static EVENT_PLAY: string = 'play';
Fired when the instance starts playing its source.
Example
instance.on('play', () => {
console.log('Instance started playing')
})
EVENT_RESUME
static EVENT_RESUME: string = 'resume';
Fired when the instance is resumed.
Example
instance.on('resume', () => {
console.log('Instance resumed')
})
EVENT_STOP
static EVENT_STOP: string = 'stop';
Fired when the instance is stopped.
Example
instance.on('stop', () => {
console.log('Instance stopped')
})