Mirror Engine API

---

Mirror Engine API / SoundInstance3d

Class: SoundInstance3d

A SoundInstance3d plays a Sound in 3D.

Extends

• SoundInstance

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

SoundManager

The sound manager.

sound

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?

Vec3

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

SoundInstance3d

Overrides

SoundInstance.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.

Inherited from

SoundInstance.source

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

SoundInstance.currentTime

---

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

SoundInstance.duration

---

isPaused

Get Signature

get isPaused(): boolean

Gets whether the instance is currently paused.

Returns

boolean

Inherited from

SoundInstance.isPaused

---

isPlaying

Get Signature

get isPlaying(): boolean

Gets whether the instance is currently playing.

Returns

boolean

Inherited from

SoundInstance.isPlaying

---

isStopped

Get Signature

get isStopped(): boolean

Gets whether the instance is currently stopped.

Returns

boolean

Inherited from

SoundInstance.isStopped

---

isSuspended

Get Signature

get isSuspended(): boolean

Gets whether the instance is currently suspended because the window is not focused.

Returns

boolean

Inherited from

SoundInstance.isSuspended

---

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

SoundInstance.loop

---

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

SoundInstance.pitch

---

position

Get Signature

get position(): Vec3

Gets the position of the sound in 3D space.

Returns

Vec3

Set Signature

set position(value: Vec3): void

Sets the position of the sound in 3D space.

Parameters

value

Vec3

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

Sound

Set Signature

set sound(value: Sound): void

Sets the sound resource that the instance will play.

Parameters

value

Sound

Returns

void

Inherited from

SoundInstance.sound

---

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

SoundInstance.startTime

---

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

SoundInstance.volume

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

EventHandler

Self for chaining.

Example

obj.fire('test', 'This is the message')

Inherited from

SoundInstance.fire

---

getExternalNodes()

getExternalNodes(): AudioNode[]

Gets any external nodes set by SoundInstance#setExternalNodes.

Returns

AudioNode[]

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

SoundInstance.hasEvent

---

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

EventHandler

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

SoundInstance.off

---

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

EventHandle

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

SoundInstance.on

---

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

EventHandle

• 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

SoundInstance.once

---

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

SoundInstance.pause

---

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

SoundInstance.play

---

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

SoundInstance.resume

---

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

AudioNode

The first node that will be connected to the audio source of sound instances.

lastNode?

AudioNode

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

SoundInstance.stop

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

SoundInstance.EVENT_END

---

EVENT_PAUSE

static EVENT_PAUSE: string = 'pause';

Fired when the instance is paused.

Example

instance.on('pause', () => {
  console.log('Instance paused')
})

Inherited from

SoundInstance.EVENT_PAUSE

---

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

SoundInstance.EVENT_PLAY

---

EVENT_RESUME

static EVENT_RESUME: string = 'resume';

Fired when the instance is resumed.

Example

instance.on('resume', () => {
  console.log('Instance resumed')
})

Inherited from

SoundInstance.EVENT_RESUME

---

EVENT_STOP

static EVENT_STOP: string = 'stop';

Fired when the instance is stopped.

Example

instance.on('stop', () => {
  console.log('Instance stopped')
})

Inherited from

SoundInstance.EVENT_STOP