EZ Web Audio / SoundController

Class: SoundController

Defined in: packages/core/src/controllers/sound-controller.ts:9

Parameter controller for Sound and Track instances.

Manages gain and detune parameters. Created automatically by Sound's constructor.

Extends

• BaseParamController

Implements

• ParamController

Constructors

Constructor

new SoundController(bufferSourceNode, gainNode, pannerNode): SoundController

Defined in: packages/core/src/controllers/sound-controller.ts:10

Parameters

bufferSourceNode

AudioBufferSourceNode

gainNode

GainNode

pannerNode

StereoPannerNode

Returns

SoundController

Overrides

BaseParamController.constructor

Properties

audioSource

protected audioSource: AudioSource

Defined in: packages/core/src/controllers/base-param-controller.ts:110

Inherited from

BaseParamController.audioSource

---

exponentialValues

protected exponentialValues: ValueAtTime[] = []

Defined in: packages/core/src/controllers/base-param-controller.ts:114

Inherited from

BaseParamController.exponentialValues

---

gainNode

protected gainNode: GainNode

Defined in: packages/core/src/controllers/sound-controller.ts:10

Inherited from

BaseParamController.gainNode

---

linearValues

protected linearValues: ValueAtTime[] = []

Defined in: packages/core/src/controllers/base-param-controller.ts:115

Inherited from

BaseParamController.linearValues

---

pannerNode

protected pannerNode: StereoPannerNode

Defined in: packages/core/src/controllers/sound-controller.ts:10

Inherited from

BaseParamController.pannerNode

---

startingValues

protected startingValues: ParamValue[] = []

Defined in: packages/core/src/controllers/base-param-controller.ts:112

Inherited from

BaseParamController.startingValues

---

valuesAtTime

protected valuesAtTime: ValueAtTime[] = []

Defined in: packages/core/src/controllers/base-param-controller.ts:113

Inherited from

BaseParamController.valuesAtTime

Accessors

gain

Get Signature

get gain(): number

Defined in: packages/core/src/controllers/base-param-controller.ts:120

Current gain value (0-1 typical range).

Returns

number

Set Signature

set gain(value): void

Defined in: packages/core/src/controllers/base-param-controller.ts:124

Parameters

value

number

Returns

void

Implementation of

ParamController.gain

Inherited from

BaseParamController.gain

---

pan

Get Signature

get pan(): number

Defined in: packages/core/src/controllers/base-param-controller.ts:128

Returns

number

Set Signature

set pan(value): void

Defined in: packages/core/src/controllers/base-param-controller.ts:132

Parameters

value

number

Returns

void

Implementation of

ParamController.pan

Inherited from

BaseParamController.pan

Methods

_update()

protected _update(type, value): void

Defined in: packages/core/src/controllers/base-param-controller.ts:178

Parameters

type

ControlType

value

number

Returns

void

Inherited from

BaseParamController._update

---

applyRampToParam()

protected applyRampToParam(param, value, time, rampType): void

Defined in: packages/core/src/controllers/base-param-controller.ts:453

Apply a ramp to an AudioParam using the specified ramp type. Shared helper to eliminate duplication between controllers.

Parameters

param

AudioParam

The AudioParam to apply the ramp to

value

number

The target value

time

number

The absolute audio context time to reach the target value

rampType

'exponential' or 'linear' ramp

"linear" | "exponential"

Returns

void

Inherited from

BaseParamController.applyRampToParam

---

applyRampValues()

protected applyRampValues(values, currentTime, rampType): void

Defined in: packages/core/src/controllers/base-param-controller.ts:367

Apply a list of ramped parameter values relative to the current time. Uses resolveParam() to map control types to AudioParams.

Parameters

values

ValueAtTime[]

Array of ValueAtTime to apply

currentTime

number

The audio context current time

rampType

The ramp curve type ('exponential' or 'linear')

"linear" | "exponential"

Returns

void

Inherited from

BaseParamController.applyRampValues

---

applyValues()

protected applyValues(values, currentTime): void

Defined in: packages/core/src/controllers/base-param-controller.ts:352

Apply a list of immediate parameter values at the current time. Uses resolveParam() to map control types to AudioParams.

Parameters

values

ParamValue[]

Array of ParamValue to apply

currentTime

number

The audio context current time

Returns

void

Inherited from

BaseParamController.applyValues

---

clampPendingZeroBeforeExponentialRamp()

protected clampPendingZeroBeforeExponentialRamp(): void

Defined in: packages/core/src/controllers/base-param-controller.ts:392

Clamp any zero-valued startingValues/valuesAtTime entries that share a control type with a pending exponential ramp, to SAFE_NEAR_ZERO.

An exponentialRampToValueAtTime whose previous scheduled value is exactly 0 holds the param at 0 for the entire ramp duration and then jumps to the target right at the end — an audible pop. onPlayRamp()'s .from() already guards this (see SAFE_NEAR_ZERO above), but the documented two-call fade-in idiom — onPlaySet('gain').to(0).at(0) followed by onPlaySet('gain').to(1).endingAt(1) (default exponential) — pushes a raw, unclamped 0 via .at() and reproduces the same pop. Call this before applying startingValues/valuesAtTime so every path into an exponential ramp is protected consistently.

Returns

void

See

onPlaySet

Inherited from

BaseParamController.clampPendingZeroBeforeExponentialRamp

---

clearScheduledValues()

protected clearScheduledValues(): void

Defined in: packages/core/src/controllers/base-param-controller.ts:419

Clear all scheduled parameter arrays after they have been applied.

Called at the end of setValuesAtTimes() in each controller subclass to ensure that parameter schedules set via onPlaySet() and onPlayRamp() are consumed once per play() call. If the same schedule is needed on every play, call onPlaySet() or onPlayRamp() before each play() call.

Returns

void

See

• onPlaySet
• onPlayRamp

Inherited from

BaseParamController.clearScheduledValues

---

onPlayRamp()

onPlayRamp(type, rampType?): object

Defined in: packages/core/src/controllers/base-param-controller.ts:293

Schedule a parameter ramp when play() is called.

Parameters

type

ControlType

The parameter to ramp

rampType?

RampType

Ramp curve type ('linear' or 'exponential')

Returns

object

Fluent builder: .from(startValue).to(endValue).in(duration)

from()

from: (startValue) => object

Parameters

startValue

number

Returns

object

to()

to: (endValue) => object

Parameters

endValue

number

Returns

object

in()

in: (endTime) => void

Parameters

endTime

number

Returns

void

Example

// Fade out over 2 seconds
controller.onPlayRamp('gain', 'linear').from(1).to(0).in(2)

Implementation of

ParamController.onPlayRamp

Inherited from

BaseParamController.onPlayRamp

---

onPlaySet()

onPlaySet(type): object

Defined in: packages/core/src/controllers/base-param-controller.ts:256

Schedule a parameter value to be set when play() is called.

Parameters

type

ControlType

The parameter to schedule

Returns

object

Fluent builder: .to(value).at(time) or .to(value).endingAt(time, rampType)

to()

to: (value) => object

Parameters

value

number

Returns

object

at()

at: (time) => void

Parameters

time

number

Returns

void

endingAt()

endingAt: (time, rampType?) => void

Parameters

time

number

rampType?

RampType

Returns

void

Remarks

Schedules set via onPlaySet() are consumed (cleared) after each play() call by clearScheduledValues. Re-schedule before each play() if you need repeated automation.

Accumulate-vs-replace semantics differ by call shape: .to(value) alone (no .at()/.endingAt()) REPLACES any prior un-timed schedule for the same type — calling it twice before play() keeps only the latest value. .at(time) and .endingAt(time) ACCUMULATE instead — each call pushes a new timed/ramp event, so calling either twice before play() applies both the stale and the new event on the next play(). Call onPlaySet again per-type only once per play() cycle unless you intend to schedule multiple timed events for that type.

Example

// Set gain to 0 at start, ramp to 1 over 0.5s
controller.onPlaySet('gain').to(0).at(0)
controller.onPlaySet('gain').to(1).endingAt(0.5, 'linear')

Implementation of

ParamController.onPlaySet

Inherited from

BaseParamController.onPlaySet

---

resolveParam()

protected resolveParam(type): AudioParam

Defined in: packages/core/src/controllers/base-param-controller.ts:331

Resolve a control type to its corresponding AudioParam. Override in subclasses to add type-specific params (e.g., frequency for Oscillator).

Parameters

type

ControlType

The control type to resolve

Returns

AudioParam

The AudioParam corresponding to the control type

Throws

if the type is not supported by this controller

Inherited from

BaseParamController.resolveParam

---

setValuesAtTimes()

setValuesAtTimes(): void

Defined in: packages/core/src/controllers/sound-controller.ts:29

Apply all scheduled parameter values to the current audio nodes. Called by Sound.setup() before each play().

Returns

void

Implementation of

ParamController.setValuesAtTimes

---

transferDetuneTo()

protected transferDetuneTo(newSource): void

Defined in: packages/core/src/controllers/base-param-controller.ts:172

Carry the current detune value over to a replacement audio source node.

Unlike gain/pan (which live on the persistent gain/panner nodes and therefore survive node replacement automatically), detune lives on the audioSource itself — the single-use OscillatorNode/AudioBufferSourceNode that gets swapped out on every play(). Without this, update('detune') would silently revert to 0 the next time the source node is replaced. Mirrors the copy-before-swap pattern used by updateGainNode/updatePannerNode. Call this BEFORE reassigning this.audioSource to the new node.

Parameters

newSource

AudioSource

The replacement audio source node

Returns

void

Inherited from

BaseParamController.transferDetuneTo

---

update()

update(type): object

Defined in: packages/core/src/controllers/base-param-controller.ts:217

Update an audio parameter immediately.

Parameters

type

ControlType

The parameter to update ('gain', 'pan', 'detune', or 'frequency')

Returns

object

Fluent builder: .to(value).as(unit)

to()

to: (value) => object

Parameters

value

number

Returns

object

as()

as: (method) => void

Parameters

method

RatioType

Returns

void

Example

controller.update('gain').to(0.5).as('ratio')
controller.update('gain').to(50).as('percent')

Implementation of

ParamController.update

Inherited from

BaseParamController.update

---

updateAudioSource()

updateAudioSource(source): void

Defined in: packages/core/src/controllers/sound-controller.ts:19

Replace the audio source node (called on each play() since AudioBufferSourceNode is single-use).

Parameters

source

The new AudioBufferSourceNode

OscillatorNode | AudioBufferSourceNode

Returns

void

Implementation of

ParamController.updateAudioSource

---

updateGainNode()

updateGainNode(gainNode): void

Defined in: packages/core/src/controllers/base-param-controller.ts:142

Replace the gain node, preserving the current gain value. Called by Oscillator.setup() when recreating nodes for each play().

Parameters

gainNode

GainNode

The new GainNode to use

Returns

void

Implementation of

ParamController.updateGainNode

Inherited from

BaseParamController.updateGainNode

---

updatePannerNode()

updatePannerNode(pannerNode): void

Defined in: packages/core/src/controllers/base-param-controller.ts:153

Replace the panner node, preserving the current pan value. Called by Oscillator.setup() when recreating nodes for each play().

Parameters

pannerNode

StereoPannerNode

The new StereoPannerNode to use

Returns

void

Implementation of

ParamController.updatePannerNode

Inherited from

BaseParamController.updatePannerNode