Source: media/sound/SoundEcho.js

//------------------------------------------------------------------------------
// Constructor scope
//------------------------------------------------------------------------------

/**
 * Creates an optional echo for a sound channel.
 *
 * @constructor
 * @package
 * @param {AudioContext} context The channel's audio context.
 * @param {AudioNode} input Channel input, with a separate direct output path.
 * @param {AudioNode} output Channel volume node receiving the delayed signal.
 *
 * @class
 * @classdesc
 *
 * Adds delayed repetitions alongside the channel's unchanged original signal.
 * Audio nodes are created on first activation and reused until clear or dispose.
 * Enable, disable and parameter changes are smoothed over twenty milliseconds.
 * Disabling mutes the echo and its input; the delay buffer drains in the
 * background. Rapid reactivation can make a pending repetition audible again.
 */
rune.media.SoundEcho = function(context, input, output) {

    //--------------------------------------------------------------------------
    // Private properties
    //--------------------------------------------------------------------------

    /**
     * The audio context owned by the channel.
     * @type {AudioContext}
     * @private
     */
    this.m_context = context;

    /**
     * Channel input tapped without changing the direct sound path.
     * @type {AudioNode}
     * @private
     */
    this.m_input = input;

    /**
     * Channel volume node shared by original and delayed sound.
     * @type {AudioNode}
     * @private
     */
    this.m_output = output;

    /**
     * Whether echo is enabled.
     * @type {boolean}
     * @private
     */
    this.m_enabled = false;

    /**
     * Time between repetitions, in seconds.
     * @type {number}
     * @private
     */
    this.m_delay = 0.2;

    /**
     * Amount returned from the delay output to its input.
     * @type {number}
     * @private
     */
    this.m_feedback = 0.3;

    /**
     * Echo output volume relative to the unchanged original signal.
     * @type {number}
     * @private
     */
    this.m_mix = 0.25;

    /**
     * Gain controlling the input to the delay.
     * @type {GainNode}
     * @private
     */
    this.m_send = null;

    /**
     * Delay buffer, allocated only when first enabled.
     * @type {DelayNode}
     * @private
     */
    this.m_delayNode = null;

    /**
     * Gain limiting repeated feedback to a decaying level.
     * @type {GainNode}
     * @private
     */
    this.m_feedbackGain = null;

    /**
     * Gain controlling the delayed signal's output volume.
     * @type {GainNode}
     * @private
     */
    this.m_wet = null;
};

//------------------------------------------------------------------------------
// Public prototype getter and setter methods
//------------------------------------------------------------------------------

/**
 * Whether echo is enabled. Disabling fades the delayed signal out without
 * changing original playback, playback position or channel volume.
 *
 * @member {boolean} enabled
 * @memberof rune.media.SoundEcho
 * @instance
 * @default false
 * @throws {Error} If the controller is disposed.
 */
Object.defineProperty(rune.media.SoundEcho.prototype, "enabled", {
    /**
     * @this rune.media.SoundEcho
     * @ignore
     */
    get : function() {
        return this.m_enabled;
    },
    /**
     * @this rune.media.SoundEcho
     * @ignore
     */
    set : function(value) {
        if (this.m_context == null) throw new Error("SoundEcho is disposed.");
        value = Boolean(value);
        if (value === this.m_enabled) return;
        if (value && this.m_delayNode == null) this.m_constructNodes();
        this.m_enabled = value;
        this.m_updateGains();
    }
});

/**
 * Time between repetitions in seconds, clamped between 0.01 and 2.0.
 *
 * @member {number} delay
 * @memberof rune.media.SoundEcho
 * @instance
 * @default 0.2
 * @throws {RangeError} If the value is not a finite number.
 */
Object.defineProperty(rune.media.SoundEcho.prototype, "delay", {
    /**
     * @this rune.media.SoundEcho
     * @ignore
     */
    get : function() {
        return this.m_delay;
    },
    /**
     * @this rune.media.SoundEcho
     * @ignore
     */
    set : function(value) {
        this.m_delay = rune.util.Math.clamp(this.m_validateNumber(value), 0.01, 2.0);
        if (this.m_delayNode != null) this.m_ramp(this.m_delayNode.delayTime, this.m_delay);
    }
});

/**
 * Feedback strength, clamped between 0 and 0.95 so repetitions decay.
 * Zero produces a single delayed repetition.
 *
 * @member {number} feedback
 * @memberof rune.media.SoundEcho
 * @instance
 * @default 0.3
 * @throws {RangeError} If the value is not a finite number.
 */
Object.defineProperty(rune.media.SoundEcho.prototype, "feedback", {
    /**
     * @this rune.media.SoundEcho
     * @ignore
     */
    get : function() {
        return this.m_feedback;
    },
    /**
     * @this rune.media.SoundEcho
     * @ignore
     */
    set : function(value) {
        this.m_feedback = rune.util.Math.clamp(this.m_validateNumber(value), 0, 0.95);
        this.m_updateGains();
    }
});

/**
 * Delayed signal volume relative to the original signal, clamped to 0..1.
 * The original signal remains unchanged rather than being crossfaded away.
 *
 * @member {number} mix
 * @memberof rune.media.SoundEcho
 * @instance
 * @default 0.25
 * @throws {RangeError} If the value is not a finite number.
 */
Object.defineProperty(rune.media.SoundEcho.prototype, "mix", {
    /**
     * @this rune.media.SoundEcho
     * @ignore
     */
    get : function() {
        return this.m_mix;
    },
    /**
     * @this rune.media.SoundEcho
     * @ignore
     */
    set : function(value) {
        this.m_mix = rune.util.Math.clamp(this.m_validateNumber(value), 0, 1);
        this.m_updateGains();
    }
});

//------------------------------------------------------------------------------
// Internal prototype methods
//------------------------------------------------------------------------------

/**
 * Empties delayed audio when the owning channel is cleared. Configuration and
 * activation are retained, but the delay buffer and its connections are reset.
 *
 * @returns {undefined}
 * @package
 * @ignore
 */
rune.media.SoundEcho.prototype.clear = function() {
    this.m_disposeNodes();
    if (this.m_enabled && this.m_context != null) {
        this.m_constructNodes();
        this.m_updateGains();
    }
};

/**
 * Disconnects echo nodes without closing the channel's shared audio context.
 *
 * @returns {undefined}
 * @package
 * @ignore
 */
rune.media.SoundEcho.prototype.dispose = function() {
    this.m_disposeNodes();
    this.m_enabled = false;
    this.m_context = null;
    this.m_input = null;
    this.m_output = null;
};

//------------------------------------------------------------------------------
// Private prototype methods
//------------------------------------------------------------------------------

/**
 * Creates a parallel delay path and a feedback loop. The direct channel path
 * remains connected. Gains start silent so activation can be faded in.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundEcho.prototype.m_constructNodes = function() {
    var context = this.m_context;
    var input = this.m_input;
    var output = this.m_output;
    if (context == null || input == null || output == null) throw new Error("SoundEcho is disposed.");
    try {
        this.m_send = context.createGain();
        this.m_delayNode = context.createDelay(2.0);
        this.m_feedbackGain = context.createGain();
        this.m_wet = context.createGain();
        this.m_send.gain.value = 0;
        this.m_feedbackGain.gain.value = 0;
        this.m_wet.gain.value = 0;
        this.m_delayNode.delayTime.value = this.m_delay;
        this.m_send.connect(this.m_delayNode);
        this.m_delayNode.connect(this.m_feedbackGain);
        this.m_feedbackGain.connect(this.m_delayNode);
        this.m_delayNode.connect(this.m_wet);
        this.m_wet.connect(output);
        input.connect(this.m_send);
    } catch (error) {
        this.m_disposeNodes();
        throw error;
    }
};

/**
 * Applies enabled state and configured strength without rebuilding the graph.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundEcho.prototype.m_updateGains = function() {
    if (this.m_send == null) return;
    this.m_ramp(this.m_send.gain, this.m_enabled ? 1 : 0);
    this.m_ramp(this.m_feedbackGain.gain, this.m_enabled ? this.m_feedback : 0);
    this.m_ramp(this.m_wet.gain, this.m_enabled ? this.m_mix : 0);
};

/**
 * Smoothly changes an audio parameter, including during a previous transition.
 * Uses cancel-and-hold when available, with a fallback for older contexts.
 *
 * @param {AudioParam} parameter Parameter to adjust.
 * @param {number} value Target value.
 * @returns {undefined}
 * @private
 */
rune.media.SoundEcho.prototype.m_ramp = function(parameter, value) {
    var now = this.m_context.currentTime;
    if (typeof parameter['cancelAndHoldAtTime'] === "function") {
        parameter['cancelAndHoldAtTime'](now);
    } else {
        var current = parameter.value;
        parameter.cancelScheduledValues(now);
        parameter.setValueAtTime(current, now);
    }
    parameter.linearRampToValueAtTime(value, now + 0.02);
};

/**
 * Validates numeric configuration before applying limits.
 *
 * @param {number} value Value to validate.
 * @returns {number} The validated value.
 * @throws {RangeError} If the value is not a finite number.
 * @private
 */
rune.media.SoundEcho.prototype.m_validateNumber = function(value) {
    if (typeof value !== "number" || !isFinite(value)) throw new RangeError("Expected a finite number.");
    return value;
};

/**
 * Breaks the feedback loop and removes only echo connections. The channel's
 * direct connection to its volume node remains intact.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundEcho.prototype.m_disposeNodes = function() {
    if (this.m_send != null) {
        try {
            this.m_input.disconnect(this.m_send);
        } catch (error) {}
        this.m_send.disconnect();
        this.m_send = null;
    }
    if (this.m_feedbackGain != null) {
        this.m_feedbackGain.disconnect();
        this.m_feedbackGain = null;
    }
    if (this.m_delayNode != null) {
        this.m_delayNode.disconnect();
        this.m_delayNode = null;
    }
    if (this.m_wet != null) {
        this.m_wet.disconnect();
        this.m_wet = null;
    }
};