envelope_follower.hpp

Go to the documentation of this file.

// sbl/dsp/envelope_follower.hpp — Amplitude envelope extraction
//
// Rectifies and smooths an audio signal to extract its amplitude envelope.
// Full-wave rectification with asymmetric one-pole smoothing (fast attack,
// slow release). Output is a slowly-varying positive float representing
// "how loud the input is."
//
// Domain: Amplitude — makes the amplitude contour of a signal explicit.
// See docs/design-philosophy.md for the domain manipulation framework.
//
// Usage:
//   sbl::dsp::EnvelopeFollower ef;
//   ef.set_times(1.0f, 100.0f, 48000);   // 1ms attack, 100ms release
//   float level = ef.process(sample);     // Single sample
//   ef.process(in, out, frames);          // Block: in → envelope out
 
#pragma once
 
#include <cstdint>
 
namespace sbl::dsp {
 
class EnvelopeFollower {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /**
     * @brief Set attack and release times in milliseconds
     *
     * Computes one-pole coefficients from time constants.
     * Attack: how fast the follower rises to meet a transient.
     * Release: how fast it falls after the signal drops.
     *
     * @param attack_ms Attack time in milliseconds (typically 0.1–10)
     * @param release_ms Release time in milliseconds (typically 50–500)
     * @param sample_rate Audio sample rate (e.g. 48000)
     */
    void set_times(float attack_ms, float release_ms, uint32_t sample_rate) {
        float sr = static_cast<float>(sample_rate);
        // Time constant → coefficient: a = 1 - exp(-1 / (t * sr))
        // For t in seconds: t = ms / 1000
        // Approximation: 1 - exp(-x) ≈ x / (1 + x) for reasonable accuracy
        float attack_samples = (attack_ms / 1000.0f) * sr;
        float release_samples = (release_ms / 1000.0f) * sr;
 
        if (attack_samples > 0.0f) {
            float x = 1.0f / attack_samples;
            attack_coeff_ = x / (1.0f + x);
        } else {
            attack_coeff_ = 1.0f;  // Instant attack
        }
 
        if (release_samples > 0.0f) {
            float x = 1.0f / release_samples;
            release_coeff_ = x / (1.0f + x);
        } else {
            release_coeff_ = 1.0f;  // Instant release
        }
    }
 
    /**
     * @brief Set attack and release coefficients directly
     *
     * Coefficient range [0.0, 1.0). Higher = faster response.
     * 0.0 = no change (hold forever), approaching 1.0 = instant.
     *
     * @param attack Attack coefficient
     * @param release Release coefficient
     */
    void set_coefficients(float attack, float release) {
        attack_coeff_ = attack;
        release_coeff_ = release;
    }
 
    /**
     * @brief Process a single sample, return envelope value
     *
     * Full-wave rectifies the input, then applies asymmetric smoothing:
     * if |input| > state: use attack coefficient (rise fast)
     * if |input| < state: use release coefficient (fall slow)
     *
     * @param sample Input audio sample
     * @return Current envelope value (always >= 0)
     */
    float process(float sample) {
        // Full-wave rectification
        float rectified = sample < 0.0f ? -sample : sample;
 
        // Asymmetric one-pole: choose coefficient based on direction
        float coeff = rectified > envelope_ ? attack_coeff_ : release_coeff_;
        envelope_ += coeff * (rectified - envelope_);
 
        return envelope_;
    }
 
    /**
     * @brief Process a block, write envelope to output buffer
     *
     * Input and output can be the same buffer (in-place).
     *
     * @param in Input audio buffer
     * @param out Output envelope buffer (always >= 0)
     * @param frames Number of samples
     */
    void process(const float* in, float* out, uint16_t frames) {
        for (uint16_t i = 0; i < frames; ++i) {
            out[i] = process(in[i]);
        }
    }
 
    /** @brief Current envelope value (can be read without processing) */
    float value() const { return envelope_; }
 
    /** @brief Reset envelope state to zero */
    void reset() { envelope_ = 0.0f; }
 
    /** @brief Reset envelope state to a specific value */
    void reset(float initial) { envelope_ = initial; }
 
private:
    float envelope_ = 0.0f;
    float attack_coeff_ = 0.0f;
    float release_coeff_ = 0.0f;
};
 
} // namespace sbl::dsp