Mirror Engine
V5
How To
Mirror Engine Logo

Mirror Engine API


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

SoundManager

The sound manager.

sound

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

Function called when the instance ends.

onPause?

Function

Function called when the instance is paused.

onPlay?

Function

Function called when the instance starts playing.

onResume?

Function

Function called when the instance is resumed.

onStop?

Function

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

SoundInstance

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

Sound

Set Signature

set sound(value: Sound): void

Sets the sound resource that the instance will play.

Parameters
value

Sound

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

EventHandler

Self for chaining.

Example

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

Inherited from

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


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

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

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

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

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


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

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)

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')
})
Mirror Engine Logo