EZ Web Audio

Appearance

EZ Web Audio / Envelope

Class: Envelope ​

Defined in: packages/core/src/envelope.ts:60

ADSR Envelope class for managing amplitude envelope scheduling.

The envelope controls how a sound's amplitude evolves over time:

  • Attack: Ramp from 0 to peak (the sound's target gain, 1.0 by default)
  • Decay: Ramp from peak to sustain level
  • Sustain: Hold at sustain level until release() called
  • Release: Exponential decay to silence

Supports clickless retriggering: when a note is retriggered while the envelope is still active, it picks up from the current value instead of jumping to zero, preventing audible clicks.

Example ​

typescript
const envelope = new Envelope({
  attack: 0.05,
  decay: 0.1,
  sustain: 0.7,
  release: 0.3
})

// Apply on note start
envelope.applyTo(gainNode.gain, audioContext.currentTime)

// Release on note end
envelope.triggerRelease(gainNode.gain, audioContext.currentTime)

Constructors ​

Constructor ​

new Envelope(options): Envelope

Defined in: packages/core/src/envelope.ts:99

Creates a new Envelope with the specified ADSR parameters.

Parameters ​

options ​

EnvelopeOptions = {}

ADSR configuration options

Returns ​

Envelope

Properties ​

attack ​

readonly attack: number

Defined in: packages/core/src/envelope.ts:62

Duration in seconds to ramp from 0 to peak (1.0)

decay ​

readonly decay: number

Defined in: packages/core/src/envelope.ts:65

Duration in seconds to ramp from peak to sustain level

release ​

readonly release: number

Defined in: packages/core/src/envelope.ts:71

Duration in seconds for release to silence

sustain ​

readonly sustain: number

Defined in: packages/core/src/envelope.ts:68

Amplitude level (0-1) held during sustain phase

Accessors ​

isActive ​

Get Signature ​

get isActive(): boolean

Defined in: packages/core/src/envelope.ts:109

Whether the envelope is currently active (between applyTo and release).

Returns ​

boolean

Methods ​

applyTo() ​

applyTo(gainParam, startTime, peak): void

Defined in: packages/core/src/envelope.ts:200

Applies the attack-decay-sustain phases to an AudioParam.

Schedules:

  1. setValueAtTime(startValue, startTime) - Start from current value (0 for first trigger)
  2. linearRampToValueAtTime(peak, startTime + attackTime) - Attack to peak
  3. linearRampToValueAtTime(sustain * peak, startTime + attackTime + decayTime) - Decay to sustain

If retriggering (envelope already active), cancels scheduled values and starts the attack from the current estimated value to prevent clicks.

Parameters ​

gainParam ​

AudioParam

The AudioParam to schedule the envelope on (typically gainNode.gain)

startTime ​

number

The audio context time to start the envelope

peak ​

number = 1

Absolute amplitude the attack ramps to — the sound's target gain (default: 1)

Returns ​

void

estimateCurrentValue() ​

estimateCurrentValue(currentTime): number

Defined in: packages/core/src/envelope.ts:122

Estimates the current envelope value at a given time.

Used for retriggering to determine where to pick up from. Returns 0 if envelope is not active.

Parameters ​

currentTime ​

number

The time to estimate the value at

Returns ​

number

The estimated absolute envelope value (0 to peak)

triggerRelease() ​

triggerRelease(gainParam, startTime): void

Defined in: packages/core/src/envelope.ts:254

Applies the release phase to an AudioParam.

Cancels any in-progress attack/decay automation (preserving the current value via cancelAndHoldAtTime) and schedules a linear ramp to zero over the release duration. A linear ramp is used instead of setTargetAtTime because setTargetAtTime is an asymptotic exponential that never reaches zero — the residual amplitude causes an audible click when the oscillator node is stopped, especially on smooth waveforms (sine, triangle).

Parameters ​

gainParam ​

AudioParam

The AudioParam to schedule the release on

startTime ​

number

The audio context time to start the release phase

Returns ​

void