
Mirror Engine API / SoundInstance3d
Class: SoundInstance3d
A SoundInstance3d plays a Sound in 3D.
Extends
Constructors
new SoundInstance3d()
new SoundInstance3d(
manager: SoundManager,
sound: Sound,
options: {
distanceModel: string;
duration: number;
loop: boolean;
maxDistance: number;
pitch: number;
position: Vec3;
refDistance: number;
rollOffFactor: number;
startTime: number;
volume: number;
}): SoundInstance3d
Create a new SoundInstance3d instance.
Parameters
manager
The sound manager.
sound
The sound to play.
options
Options for the instance.
distanceModel?
string
Determines which algorithm to use to reduce the volume of the audio as it moves away from the listener. Can be:
- DISTANCE_LINEAR
- DISTANCE_INVERSE
- DISTANCE_EXPONENTIAL
Defaults to DISTANCE_LINEAR.
duration?
number
The total time after the startTime when playback will stop or restart if loop is true.
loop?
boolean
Whether the sound should loop when it reaches the end or not. Defaults to false.
maxDistance?
number
The maximum distance from the listener at which audio falloff stops. Note the volume of the audio is not 0 after this distance, but just doesn't fall off anymore. Defaults to 10000.
pitch?
number
The relative pitch. Defaults to 1 (plays at normal pitch).
position?
The position of the sound in 3D space.
refDistance?
number
The reference distance for reducing volume as the sound source moves further from the listener. Defaults to 1.
rollOffFactor?
number
The factor used in the falloff equation. Defaults to 1.
startTime?
number
The time from which the playback will start. Default is 0 to start at the beginning.
volume?
number
The playback volume, between 0 and 1. Defaults to 1.
Returns
Overrides
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.
Inherited from
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
Inherited from
distanceModel
Get Signature
get distanceModel(): string
Gets which algorithm to use to reduce the volume of the audio as it moves away from the listener.
Returns
string
Set Signature
set distanceModel(value: string): void
Sets which algorithm to use to reduce the volume of the audio as it moves away from the listener. Can be:
- DISTANCE_LINEAR
- DISTANCE_INVERSE
- DISTANCE_EXPONENTIAL
Default is DISTANCE_LINEAR.
Parameters
value
string
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
Inherited from
isPaused
Get Signature
get isPaused(): boolean
Gets whether the instance is currently paused.
Returns
boolean
Inherited from
isPlaying
Get Signature
get isPlaying(): boolean
Gets whether the instance is currently playing.
Returns
boolean
Inherited from
isStopped
Get Signature
get isStopped(): boolean
Gets whether the instance is currently stopped.
Returns
boolean
Inherited from
isSuspended
Get Signature
get isSuspended(): boolean
Gets whether the instance is currently suspended because the window is not focused.
Returns
boolean
Inherited from
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
Inherited from
maxDistance
Get Signature
get maxDistance(): number
Gets the maximum distance from the listener at which audio falloff stops.
Returns
number
Set Signature
set maxDistance(value: number): void
Sets the maximum distance from the listener at which audio falloff stops. Note that the volume of the audio is not 0 after this distance, but just doesn't fall off anymore.
Parameters
value
number
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
Inherited from
position
Get Signature
get position(): Vec3
Gets the position of the sound in 3D space.
Returns
Set Signature
set position(value: Vec3): void
Sets the position of the sound in 3D space.
Parameters
value
Returns
void
refDistance
Get Signature
get refDistance(): number
Gets the reference distance for reducing volume as the sound source moves further from the listener.
Returns
number
Set Signature
set refDistance(value: number): void
Sets the reference distance for reducing volume as the sound source moves further from the listener.
Parameters
value
number
Returns
void
rollOffFactor
Get Signature
get rollOffFactor(): number
Gets the factor used in the falloff equation.
Returns
number
Set Signature
set rollOffFactor(value: number): void
Sets the factor used in the falloff equation.
Parameters
value
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
Inherited from
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
Inherited from
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
Inherited from
Methods
clearExternalNodes()
clearExternalNodes(): void
Clears any external nodes set by SoundInstance#setExternalNodes.
Returns
void
Inherited from
SoundInstance
.clearExternalNodes
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.
Inherited from
SoundInstance
.getExternalNodes
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.
Inherited from
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.
Inherited from
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.
Inherited from
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)
Inherited from
SoundInstance
.setExternalNodes
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.
Inherited from
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')
})
Inherited from
EVENT_PAUSE
static EVENT_PAUSE: string = 'pause';
Fired when the instance is paused.
Example
instance.on('pause', () => {
console.log('Instance paused')
})
Inherited from
EVENT_PLAY
static EVENT_PLAY: string = 'play';
Fired when the instance starts playing its source.
Example
instance.on('play', () => {
console.log('Instance started playing')
})
Inherited from
EVENT_RESUME
static EVENT_RESUME: string = 'resume';
Fired when the instance is resumed.
Example
instance.on('resume', () => {
console.log('Instance resumed')
})
Inherited from
EVENT_STOP
static EVENT_STOP: string = 'stop';
Fired when the instance is stopped.
Example
instance.on('stop', () => {
console.log('Instance stopped')
})