Mirror Engine API / SoundSlot
Class: SoundSlot
The SoundSlot controls playback of an audio asset.
Extends
Constructors
new SoundSlot()
new SoundSlot(
component: SoundComponent,
name?: string,
options?: {
asset: number;
autoPlay: boolean;
duration: number;
loop: boolean;
overlap: boolean;
pitch: number;
startTime: number;
volume: number;
}): SoundSlot
Create a new SoundSlot.
Parameters
component
The Component that created this slot.
name?
string = 'Untitled'
The name of the slot. Defaults to 'Untitled'.
options?
Settings for the slot.
asset?
number
The asset id of the audio asset that is going to be played by this slot.
autoPlay?
boolean
If true, the slot will start playing as soon as its audio asset is loaded.
duration?
number
The duration of the sound that the slot will play starting from startTime.
loop?
boolean
If true, the sound will restart when it reaches the end.
overlap?
boolean
If true, then sounds played from slot will be played independently of each other. Otherwise the slot will first stop the current sound before starting the new one.
pitch?
number
The relative pitch, default of 1, plays at normal pitch.
startTime?
number
The start time from which the sound will start playing.
volume?
number
The playback volume, between 0 and 1.
Returns
Overrides
EventHandler.constructor
Properties
instances
instances: SoundInstance[] = [];
An array that contains all the SoundInstances currently being played by the slot.
name
name: string
The name of the slot.
asset
Get Signature
get asset(): null | number
Gets the asset id.
Returns
null | number
Set Signature
set asset(value: null | number): void
Sets the asset id.
Parameters
value
null | number
Returns
void
autoPlay
Get Signature
get autoPlay(): boolean
Gets whether the slot will begin playing as soon as it is loaded.
Returns
boolean
Set Signature
set autoPlay(value: boolean): void
Sets whether the slot will begin playing as soon as it is loaded.
Parameters
value
boolean
Returns
void
duration
Get Signature
get duration(): number
Gets the duration of the sound that the slot will play starting from startTime.
Returns
number
Set Signature
set duration(value: number): void
Sets the duration of the sound that the slot will play starting from startTime.
Parameters
value
number
Returns
void
isLoaded
Get Signature
get isLoaded(): boolean
Gets whether the asset of the slot is loaded.
Returns
boolean
isPaused
Get Signature
get isPaused(): boolean
Gets whether the slot is currently paused.
Returns
boolean
isPlaying
Get Signature
get isPlaying(): boolean
Gets whether the slot is currently playing.
Returns
boolean
isStopped
Get Signature
get isStopped(): boolean
Gets whether the slot is currently stopped.
Returns
boolean
loop
Get Signature
get loop(): boolean
Gets whether the slot will restart when it finishes playing.
Returns
boolean
Set Signature
set loop(value: boolean): void
Sets whether the slot will restart when it finishes playing.
Parameters
value
boolean
Returns
void
overlap
Get Signature
get overlap(): boolean
Gets whether the sounds played from this slot will be played independently of each other.
Returns
boolean
Set Signature
set overlap(value: boolean): void
Sets whether the sounds played from this slot will be played independently of each other. Otherwise, the slot will first stop the current sound before starting the new one.
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(value: number): void
Sets the pitch modifier to play the sound with. Must be larger than 0.01.
Parameters
value
number
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.
Returns
number
Set Signature
set volume(value: number): void
Sets the volume modifier to play the sound with. In range 0-1.
Parameters
value
number
Returns
void
Methods
clearExternalNodes()
clearExternalNodes(): void
Clears any external nodes set by SoundSlot#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 an array that contains the two external nodes set by SoundSlot#setExternalNodes.
Returns
An array of 2 elements that contains the first and last nodes set by SoundSlot#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
load()
load(): void
Loads the asset assigned to this slot.
Returns
void
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 all sound instances. To continue playback call SoundSlot#resume.
Returns
boolean
True if the sound instances paused successfully, false otherwise.
play()
play(): SoundInstance
Plays a sound. If SoundSlot#overlap is true the new sound instance will be played independently of any other instances already playing. Otherwise existing sound instances will stop before playing the new sound.
Returns
The new sound instance.
resume()
resume(): boolean
Resumes playback of all paused sound instances.
Returns
boolean
True if any instances were resumed.
setExternalNodes()
setExternalNodes(firstNode: AudioNode, lastNode?: AudioNode): void
Connect external Web Audio API nodes. Any sound played by this slot will automatically attach the specified nodes to the source that plays the sound. 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).
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)
slot.setExternalNodes(analyzer, filter)
stop()
stop(): boolean
Stops playback of all sound instances.
Returns
boolean
True if any instances were stopped.
Events
EVENT_LOAD
static EVENT_LOAD: string = 'load';
Fired when the sound Asset assigned to the slot is loaded. The handler is passed the loaded Sound resource.
Example
slot.on('load', (sound) => {
console.log('Sound resource loaded')
})
EVENT_PAUSE
static EVENT_PAUSE: string = 'pause';
Fired when a SoundInstance is paused on a slot. The handler is passed the sound instance that is paused.
Example
slot.on('pause', (instance) => {
console.log('Sound instance paused')
})
EVENT_PLAY
static EVENT_PLAY: string = 'play';
Fired when a SoundInstance starts playing on a slot. The handler is passed the sound instance that started playing.
Example
slot.on('play', (instance) => {
console.log('Sound instance started playing')
})
EVENT_RESUME
static EVENT_RESUME: string = 'resume';
Fired when a SoundInstance is resumed on a slot. The handler is passed the sound instance that is resumed.
Example
slot.on('resume', (instance) => {
console.log('Sound instance resumed')
})
EVENT_STOP
static EVENT_STOP: string = 'stop';
Fired when a SoundInstance is stopped on a slot. The handler is passed the sound instance that is stopped.
Example
slot.on('stop', (instance) => {
console.log('Sound instance stopped')
})