Mirror Engine
V5
How To
Mirror Engine Logo

Mirror Engine API


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

SoundComponent

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

SoundSlot

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

EventHandler

Self for chaining.

Example

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

Inherited from

EventHandler.fire


getExternalNodes()

getExternalNodes(): AudioNode[]

Gets an array that contains the two external nodes set by SoundSlot#setExternalNodes.

Returns

AudioNode[]

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

EventHandler.hasEvent


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

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

SoundInstance

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

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