EZ Web Audio

Appearance

EZ Web Audio / LayeredSound

Class: LayeredSound ​

Defined in: layered-sound.ts:35

LayeredSound synchronizes multiple Sound/Oscillator instances for simultaneous playback with master gain/pan control and individual layer access.

All layers start at exactly the same audioContext.currentTime for precise sync. Layers end independently - LayeredSound emits 'end' when the last layer finishes.

Example ​

typescript
const bass = await createSound('bass.mp3')
const melody = await createSound('melody.mp3')
const synth = await createOscillator({ frequency: 440 })

const layered = new LayeredSound(audioContext, [bass, melody, synth])
layered.play() // All layers start at exact same time
layered.setGain(0.5) // Affects all layers
layered.getLayer(2)?.changeGainTo(0.8) // Control individual layer

Extends ​

  • EventTarget

Constructors ​

Constructor ​

new LayeredSound(audioContext, layers, opts?): LayeredSound

Defined in: layered-sound.ts:41

Parameters ​

audioContext ​

AudioContext

layers ​

(Sound | Oscillator | null | undefined)[]

opts? ​

LayeredSoundOptions

Returns ​

LayeredSound

Overrides ​

EventTarget.constructor

Properties ​

name ​

name: string

Defined in: layered-sound.ts:39

Accessors ​

layerCount ​

Get Signature ​

get layerCount(): number

Defined in: layered-sound.ts:93

Get the number of valid layers in this LayeredSound.

Returns ​

number

Methods ​

addEventListener() ​

Call Signature ​

addEventListener<K>(type, listener, options?): void

Defined in: layered-sound.ts:204

Add a typed event listener for LayeredSound lifecycle events. Overloaded to provide type safety for known event types while remaining compatible with EventTarget.

Type Parameters ​
K ​

K extends keyof LayeredSoundEventMap

Parameters ​
type ​

K

The event type ('play', 'stop', 'end', 'warning')

listener ​

(event) => void

The event handler function

options? ​

Standard addEventListener options

boolean | AddEventListenerOptions

Returns ​

void

Overrides ​

EventTarget.addEventListener

Call Signature ​

addEventListener(type, listener, options?): void

Defined in: layered-sound.ts:209

Add a typed event listener for LayeredSound lifecycle events. Overloaded to provide type safety for known event types while remaining compatible with EventTarget.

Parameters ​
type ​

string

The event type ('play', 'stop', 'end', 'warning')

listener ​

The event handler function

EventListenerOrEventListenerObject | null

options? ​

Standard addEventListener options

boolean | AddEventListenerOptions

Returns ​

void

Overrides ​

EventTarget.addEventListener

emit() ​

protected emit<K>(type, detail): void

Defined in: layered-sound.ts:255

Emit a typed event with the given detail.

Type Parameters ​

K ​

K extends keyof LayeredSoundEventMap

Parameters ​

type ​

K

The event type to emit

detail ​

LayeredSoundEventMap[K]["detail"]

The event detail object

Returns ​

void

getLayer() ​

getLayer(index): Sound | Oscillator | undefined

Defined in: layered-sound.ts:86

Get a layer by index for individual control.

Parameters ​

index ​

number

The layer index (0-based)

Returns ​

Sound | Oscillator | undefined

The Sound or Oscillator at that index, or undefined if out of bounds

off() ​

off<K>(type, listener): this

Defined in: layered-sound.ts:330

Unsubscribe from an event.

Note: Due to native EventTarget limitations, you must provide the same listener function reference that was used when subscribing. To remove listeners, store the function reference when adding it.

Type Parameters ​

K ​

K extends keyof LayeredSoundEventMap

Parameters ​

type ​

K

The event type to unsubscribe from

listener ​

(event) => void

The event handler function to remove

Returns ​

this

this for chaining

Example ​

typescript
const handler = (e) => console.log(e.detail);
layered.on('play', handler);
// later...
layered.off('play', handler);

on() ​

on<K>(type, listener): this

Defined in: layered-sound.ts:278

Subscribe to one or more events. Supports chaining.

Type Parameters ​

K ​

K extends keyof LayeredSoundEventMap

Parameters ​

type ​

The event type(s) to subscribe to

K | K[]

listener ​

(event) => void

The event handler function

Returns ​

this

this for chaining

Example ​

typescript
layered.on('play', handlePlay).on('stop', handleStop);
layered.on(['play', 'stop'], handleBoth);

once() ​

once<K>(type, listener): this

Defined in: layered-sound.ts:303

Subscribe to an event once. Handler is removed after first invocation.

Type Parameters ​

K ​

K extends keyof LayeredSoundEventMap

Parameters ​

type ​

K

The event type to subscribe to

listener ​

(event) => void

The event handler function

Returns ​

this

this for chaining

Example ​

typescript
layered.once('end', () => console.log('All layers finished'));

play() ​

play(): Promise<void>

Defined in: layered-sound.ts:101

Play all layers simultaneously at exactly the same audioContext.currentTime. This ensures perfect synchronization across all layers.

Returns ​

Promise<void>

playFor() ​

playFor(duration): Promise<void>

Defined in: layered-sound.ts:128

Play all layers simultaneously for a specified duration, then stop.

Parameters ​

duration ​

number

Duration in seconds before stopping all layers

Returns ​

Promise<void>

Example ​

typescript
const layered = await createLayeredSound([kick, snare])
layered.playFor(0.1) // Play for 100ms then auto-stop

removeEventListener() ​

Call Signature ​

removeEventListener<K>(type, listener, options?): void

Defined in: layered-sound.ts:231

Remove a typed event listener for LayeredSound lifecycle events. Overloaded to provide type safety for known event types while remaining compatible with EventTarget.

Type Parameters ​
K ​

K extends keyof LayeredSoundEventMap

Parameters ​
type ​

K

The event type ('play', 'stop', 'end', 'warning')

listener ​

(event) => void

The event handler function to remove

options? ​

Standard removeEventListener options

boolean | EventListenerOptions

Returns ​

void

Overrides ​

EventTarget.removeEventListener

Call Signature ​

removeEventListener(type, listener, options?): void

Defined in: layered-sound.ts:236

Remove a typed event listener for LayeredSound lifecycle events. Overloaded to provide type safety for known event types while remaining compatible with EventTarget.

Parameters ​
type ​

string

The event type ('play', 'stop', 'end', 'warning')

listener ​

The event handler function to remove

EventListenerOrEventListenerObject | null

options? ​

Standard removeEventListener options

boolean | EventListenerOptions

Returns ​

void

Overrides ​

EventTarget.removeEventListener

setGain() ​

setGain(value): void

Defined in: layered-sound.ts:149

Set the gain for all layers.

Parameters ​

value ​

number

The gain value (0-1 range typical)

Returns ​

void

setPan() ​

setPan(value): void

Defined in: layered-sound.ts:158

Set the pan for all layers.

Parameters ​

value ​

number

The pan value (-1 to 1, where -1 is full left, 1 is full right)

Returns ​

void

stop() ​

stop(): Promise<void>

Defined in: layered-sound.ts:136

Stop all layers.

Returns ​

Promise<void>