ez-web-audio/dist/envelope.d.ts

Making the Web Audio API super EZ since 2024.

/**
 * Options for configuring an ADSR envelope.
 *
 * @property attackTime - Duration in seconds to ramp from 0 to peak (1.0). Default: 0.01
 * @property decayTime - Duration in seconds to ramp from peak to sustain level. Default: 0.1
 * @property sustainLevel - Amplitude level (0-1) held during sustain phase. Default: 0.7
 * @property releaseTime - Duration in seconds for release to silence. Default: 0.3
 */
export interface EnvelopeOptions {
    attackTime?: number;
    decayTime?: number;
    sustainLevel?: number;
    releaseTime?: number;
}
/**
 * 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 (1.0)
 * - **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({
 *   attackTime: 0.05,
 *   decayTime: 0.1,
 *   sustainLevel: 0.7,
 *   releaseTime: 0.3
 * })
 *
 * // Apply on note start
 * envelope.applyTo(gainNode.gain, audioContext.currentTime)
 *
 * // Release on note end
 * envelope.release(gainNode.gain, audioContext.currentTime)
 * ```
 */
export declare class Envelope {
    /** Duration in seconds to ramp from 0 to peak (1.0) */
    readonly attackTime: number;
    /** Duration in seconds to ramp from peak to sustain level */
    readonly decayTime: number;
    /** Amplitude level (0-1) held during sustain phase */
    readonly sustainLevel: number;
    /** Duration in seconds for release to silence */
    readonly releaseTime: number;
    /** Whether the envelope is currently active (between applyTo and release) */
    private _isActive;
    /** The time when the current attack phase started */
    private _attackStartTime;
    /** The value the attack started from (for retriggering) */
    private _attackStartValue;
    /**
     * Creates a new Envelope with the specified ADSR parameters.
     *
     * @param options - ADSR configuration options
     */
    constructor(options?: EnvelopeOptions);
    /**
     * Whether the envelope is currently active (between applyTo and release).
     */
    get isActive(): boolean;
    /**
     * 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.
     *
     * @param currentTime - The time to estimate the value at
     * @returns The estimated envelope value (0-1)
     */
    estimateCurrentValue(currentTime: number): number;
    /**
     * Applies the attack-decay-sustain phases to an AudioParam.
     *
     * Schedules:
     * 1. setValueAtTime(startValue, startTime) - Start from current value (0 for first trigger)
     * 2. linearRampToValueAtTime(1, startTime + attackTime) - Attack to peak
     * 3. linearRampToValueAtTime(sustainLevel, 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.
     *
     * @param gainParam - The AudioParam to schedule the envelope on (typically gainNode.gain)
     * @param startTime - The audio context time to start the envelope
     */
    applyTo(gainParam: AudioParam, startTime: number): void;
    /**
     * Applies the release phase to an AudioParam.
     *
     * Uses setTargetAtTime for smooth exponential decay to zero.
     * The time constant is calculated as releaseTime/5, which gives
     * approximately 99% completion within releaseTime seconds.
     *
     * @param gainParam - The AudioParam to schedule the release on
     * @param startTime - The audio context time to start the release phase
     */
    release(gainParam: AudioParam, startTime: number): void;
}
//# sourceMappingURL=envelope.d.ts.map