envelope.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/ballistics_filter.hpp>
#include <pulp/signal/mod_tools.hpp>
 
#include <algorithm>
#include <cmath>
#include <cstdint>
 
namespace pulp::signal {

enum class EnvelopeStage : std::uint8_t {
    idle,
    delay,
    attack,
    hold,
    decay,
    sustain,
    release,
};
 
namespace detail {

struct EnvelopeStageClock {
    long long pos = 0;
    long long length = 0;
 
    void restart(long long len) {
        pos = 0;
        length = len;
    }
 
    float progress() const {
        if (length <= 0) return 1.0f;
        return static_cast<float>(pos) / static_cast<float>(length);
    }
 
    bool advance() { return ++pos >= length; }
};
 
inline long long envelope_ms_to_samples(double ms, double sample_rate) {
    return static_cast<long long>(std::lround(std::max(0.0, ms) * 0.001 * sample_rate));
}

template <typename SampleType = float>
class EnvelopeEngine {
public:
    using Stage = EnvelopeStage;
 
    static constexpr int kMaxLoops = 128;
 
    void prepare(double sample_rate) {
        sample_rate_ = sample_rate > 0.0 ? sample_rate : 1.0;
        update_lengths_();
        reset();
    }
 
    void set_delay_ms(double ms) { delay_ms_ = std::max(0.0, ms); update_lengths_(); }
    void set_attack_ms(double ms) { attack_ms_ = std::max(0.0, ms); update_lengths_(); }
    void set_hold_ms(double ms) { hold_ms_ = std::max(0.0, ms); update_lengths_(); }
    void set_decay_ms(double ms) { decay_ms_ = std::max(0.0, ms); update_lengths_(); }
    void set_release_ms(double ms) { release_ms_ = std::max(0.0, ms); update_lengths_(); }
 
    void set_attack_curve(float c) { attack_curve_ = std::clamp(c, -1.0f, 1.0f); }
    void set_decay_curve(float c) { decay_curve_ = std::clamp(c, -1.0f, 1.0f); }
    void set_release_curve(float c) { release_curve_ = std::clamp(c, -1.0f, 1.0f); }
 
    void set_sustain(SampleType level) {
        sustain_ = std::clamp(level, SampleType{0}, SampleType{1});
    }
 
    void set_has_sustain(bool on) { has_sustain_ = on; }
    void set_gate_driven(bool on) { gate_driven_ = on; }
 
    void set_loop(bool on, int count) {
        loop_ = on;
        loop_count_ = std::clamp(count, 0, kMaxLoops);
    }
 
    void reset() {
        stage_ = Stage::idle;
        level_ = SampleType{0};
        peak_ = SampleType{1};
        start_ = SampleType{0};
        release_start_ = SampleType{0};
        loops_done_ = 0;
        clock_.restart(0);
    }
 
    void trigger(SampleType velocity) {
        peak_ = std::clamp(velocity, SampleType{0}, SampleType{1});
        loops_done_ = 0;
        begin_shape_();
    }
 
    void release() {
        if (!gate_driven_ || stage_ == Stage::idle || stage_ == Stage::release) return;
        release_start_ = level_;
        stage_ = Stage::release;
        clock_.restart(release_samples_);
        if (release_samples_ <= 0) {
            // Straight to idle, not through finish_(): a release is the end of
            // the note, and finish_() would loop a looping envelope — a
            // note-off would start it over.
            stage_ = Stage::idle;
            level_ = SampleType{0};
            clock_.restart(0);
        }
    }
 
    SampleType next() {
        level_ = level_at_();
        advance_();
        return level_;
    }
 
    SampleType current() const { return level_; }
    Stage stage() const { return stage_; }
    bool active() const { return stage_ != Stage::idle; }
    int loops_completed() const { return loops_done_; }
 
private:
    void update_lengths_() {
        delay_samples_ = envelope_ms_to_samples(delay_ms_, sample_rate_);
        attack_samples_ = envelope_ms_to_samples(attack_ms_, sample_rate_);
        hold_samples_ = envelope_ms_to_samples(hold_ms_, sample_rate_);
        decay_samples_ = envelope_ms_to_samples(decay_ms_, sample_rate_);
        release_samples_ = envelope_ms_to_samples(release_ms_, sample_rate_);
    }
 
    long long shape_length_() const {
        return delay_samples_ + attack_samples_ + hold_samples_ + decay_samples_;
    }
 
    SampleType sustain_level_() const {
        return has_sustain_ ? sustain_ * peak_ : SampleType{0};
    }
 
    void begin_shape_() {
        start_ = level_;
        enter_delay_();
    }
 
    void enter_delay_() {
        if (delay_samples_ <= 0) {
            enter_attack_();
            return;
        }
        stage_ = Stage::delay;
        clock_.restart(delay_samples_);
    }
 
    void enter_attack_() {
        if (attack_samples_ <= 0) {
            level_ = peak_;
            enter_hold_();
            return;
        }
        stage_ = Stage::attack;
        clock_.restart(attack_samples_);
    }
 
    void enter_hold_() {
        if (hold_samples_ <= 0) {
            enter_decay_();
            return;
        }
        stage_ = Stage::hold;
        clock_.restart(hold_samples_);
    }
 
    void enter_decay_() {
        if (decay_samples_ <= 0) {
            level_ = sustain_level_();
            enter_after_decay_();
            return;
        }
        stage_ = Stage::decay;
        clock_.restart(decay_samples_);
    }
 
    void enter_after_decay_() {
        // Looping skips the sustain hold: an envelope that stops to wait for a
        // note-off cannot also be a cycling modulation source.
        if (has_sustain_ && !loop_) {
            stage_ = Stage::sustain;
            clock_.restart(0);
            return;
        }
        finish_();
    }
 
    void finish_() {
        // A shape with no length at all cannot be looped — that is an infinite
        // loop, not a modulation source.
        if (loop_ && shape_length_() > 0) {
            ++loops_done_;
            if (loop_count_ == 0 || loops_done_ < loop_count_) {
                start_ = level_;
                enter_delay_();
                return;
            }
        }
        stage_ = Stage::idle;
        level_ = SampleType{0};
        clock_.restart(0);
    }
 
    SampleType level_at_() const {
        const float p = clock_.progress();
        switch (stage_) {
            case Stage::delay:
                // A fresh trigger enters the delay at zero because `start_` is
                // zero. A retrigger holds the level it captured instead:
                // snapping to zero for the delay and then resuming the attack
                // from `start_` would be two full-scale steps, which is the
                // opposite of retrigger-from-current-level.
                return start_;
            case Stage::attack:
                return start_ + (peak_ - start_)
                                    * static_cast<SampleType>(curve_rise(p, attack_curve_));
            case Stage::hold:
                return peak_;
            case Stage::decay: {
                const SampleType floor_level = sustain_level_();
                return floor_level + (peak_ - floor_level)
                                         * static_cast<SampleType>(curve_fall(p, decay_curve_));
            }
            case Stage::sustain:
                return sustain_level_();
            case Stage::release:
                return release_start_ * static_cast<SampleType>(curve_fall(p, release_curve_));
            case Stage::idle:
            default:
                return SampleType{0};
        }
    }
 
    void advance_() {
        switch (stage_) {
            case Stage::delay:
                if (clock_.advance()) enter_attack_();
                return;
            case Stage::attack:
                if (clock_.advance()) enter_hold_();
                return;
            case Stage::hold:
                if (clock_.advance()) enter_decay_();
                return;
            case Stage::decay:
                if (clock_.advance()) enter_after_decay_();
                return;
            case Stage::release:
                if (clock_.advance()) {
                    stage_ = Stage::idle;
                    level_ = SampleType{0};
                    clock_.restart(0);
                }
                return;
            case Stage::sustain:
            case Stage::idle:
            default:
                return;
        }
    }
 
    EnvelopeStageClock clock_{};
    double sample_rate_ = 48000.0;
    double delay_ms_ = 0.0;
    double attack_ms_ = 10.0;
    double hold_ms_ = 0.0;
    double decay_ms_ = 100.0;
    double release_ms_ = 200.0;
    long long delay_samples_ = 0;
    long long attack_samples_ = 480;
    long long hold_samples_ = 0;
    long long decay_samples_ = 4800;
    long long release_samples_ = 9600;
    SampleType level_ = SampleType{0};
    SampleType peak_ = SampleType{1};
    SampleType start_ = SampleType{0};
    SampleType release_start_ = SampleType{0};
    SampleType sustain_ = SampleType{0.7};
    float attack_curve_ = 0.0f;
    float decay_curve_ = 0.0f;
    float release_curve_ = 0.0f;
    int loop_count_ = 0;
    int loops_done_ = 0;
    Stage stage_ = Stage::idle;
    bool has_sustain_ = true;
    bool gate_driven_ = true;
    bool loop_ = false;
};
 
} // namespace detail

template <typename SampleType = float>
class ArT {
public:
    void prepare(double sample_rate) {
        engine_.set_has_sustain(true);
        engine_.set_sustain(SampleType{1});
        engine_.set_gate_driven(true);
        engine_.set_hold_ms(0.0);
        engine_.set_decay_ms(0.0);
        engine_.prepare(sample_rate);
    }
 
    void set_attack_ms(double ms) { engine_.set_attack_ms(ms); }
    void set_release_ms(double ms) { engine_.set_release_ms(ms); }
    void set_attack_curve(float c) { engine_.set_attack_curve(c); }
    void set_release_curve(float c) { engine_.set_release_curve(c); }

    void set_curve(double c) {
        const float curve = static_cast<float>(std::clamp(c, 0.0, 1.0));
        engine_.set_attack_curve(-curve);
        engine_.set_release_curve(curve);
    }

    void gate(bool on) {
        if (on == gate_) return;
        gate_ = on;
        if (on) engine_.trigger(SampleType{1});
        else engine_.release();
    }

    void gate_on() { gate(true); }
    void gate_off() { gate(false); }
 
    void reset() {
        engine_.reset();
        gate_ = false;
    }
 
    SampleType next() { return engine_.next(); }
    SampleType current() const { return engine_.current(); }
    SampleType value() const { return current(); }
    bool active() const { return engine_.active(); }
    EnvelopeStage stage() const { return engine_.stage(); }
 
private:
    detail::EnvelopeEngine<SampleType> engine_{};
    bool gate_ = false;
};
 
using Ar = ArT<float>;
using Ar64 = ArT<double>;

template <typename SampleType = float>
class AdT {
public:
    void prepare(double sample_rate) {
        engine_.set_has_sustain(false);
        engine_.set_gate_driven(false);
        engine_.set_hold_ms(0.0);
        engine_.prepare(sample_rate);
    }
 
    void set_attack_ms(double ms) { engine_.set_attack_ms(ms); }
    void set_decay_ms(double ms) { engine_.set_decay_ms(ms); }
    void set_attack_curve(float c) { engine_.set_attack_curve(c); }
    void set_decay_curve(float c) { engine_.set_decay_curve(c); }
 
    void set_curve(double c) {
        const float curve = static_cast<float>(std::clamp(c, 0.0, 1.0));
        engine_.set_attack_curve(-curve);
        engine_.set_decay_curve(curve);
    }

    void set_loop(bool on, int count = 0) { engine_.set_loop(on, count); }
 
    void trigger(SampleType velocity = SampleType{1}) { engine_.trigger(velocity); }
    void gate_on() { trigger(); }
    void gate_off() {}
    void reset() { engine_.reset(); }
 
    SampleType next() { return engine_.next(); }
    SampleType current() const { return engine_.current(); }
    SampleType value() const { return current(); }
    bool active() const { return engine_.active(); }
    int loops_completed() const { return engine_.loops_completed(); }
    EnvelopeStage stage() const { return engine_.stage(); }
 
private:
    detail::EnvelopeEngine<SampleType> engine_{};
};
 
using Ad = AdT<float>;
using Ad64 = AdT<double>;

template <typename SampleType = float>
class AhdT {
public:
    void prepare(double sample_rate) {
        engine_.set_has_sustain(false);
        engine_.set_gate_driven(false);
        engine_.prepare(sample_rate);
    }
 
    void set_attack_ms(double ms) { engine_.set_attack_ms(ms); }
    void set_hold_ms(double ms) { engine_.set_hold_ms(ms); }
    void set_decay_ms(double ms) { engine_.set_decay_ms(ms); }
    void set_attack_curve(float c) { engine_.set_attack_curve(c); }
    void set_decay_curve(float c) { engine_.set_decay_curve(c); }
    void set_curve(double c) {
        const float curve = static_cast<float>(std::clamp(c, 0.0, 1.0));
        engine_.set_attack_curve(-curve);
        engine_.set_decay_curve(curve);
    }
    void set_loop(bool on, int count = 0) { engine_.set_loop(on, count); }
 
    void trigger(SampleType velocity = SampleType{1}) { engine_.trigger(velocity); }
    void gate_on() { trigger(); }
    void gate_off() {}
    void reset() { engine_.reset(); }
 
    SampleType next() { return engine_.next(); }
    SampleType current() const { return engine_.current(); }
    SampleType value() const { return current(); }
    bool active() const { return engine_.active(); }
    int loops_completed() const { return engine_.loops_completed(); }
    EnvelopeStage stage() const { return engine_.stage(); }
 
private:
    detail::EnvelopeEngine<SampleType> engine_{};
};
 
using Ahd = AhdT<float>;
using Ahd64 = AhdT<double>;

template <typename SampleType = float>
class DahdsrT {
public:
    void prepare(double sample_rate) {
        engine_.set_has_sustain(true);
        engine_.set_gate_driven(true);
        engine_.prepare(sample_rate);
    }
 
    void set_delay_ms(double ms) { engine_.set_delay_ms(ms); }
    void set_attack_ms(double ms) { engine_.set_attack_ms(ms); }
    void set_hold_ms(double ms) { engine_.set_hold_ms(ms); }
    void set_decay_ms(double ms) { engine_.set_decay_ms(ms); }
    void set_sustain(SampleType level) { engine_.set_sustain(level); }
    void set_release_ms(double ms) { engine_.set_release_ms(ms); }
 
    void set_attack_curve(float c) { engine_.set_attack_curve(c); }
    void set_decay_curve(float c) { engine_.set_decay_curve(c); }
    void set_release_curve(float c) { engine_.set_release_curve(c); }
 
    void set_curve(double c) {
        const float curve = static_cast<float>(std::clamp(c, 0.0, 1.0));
        engine_.set_attack_curve(-curve);
        engine_.set_decay_curve(curve);
        engine_.set_release_curve(curve);
    }
 
    void set_loop(bool on, int count = 0) { engine_.set_loop(on, count); }
 
    void note_on(SampleType velocity = SampleType{1}) { engine_.trigger(velocity); }
    void note_off() { engine_.release(); }
    void gate_on() { note_on(); }
    void gate_off() { note_off(); }
    void reset() { engine_.reset(); }
 
    SampleType next() { return engine_.next(); }
    SampleType current() const { return engine_.current(); }
    SampleType value() const { return current(); }
    bool active() const { return engine_.active(); }
    int loops_completed() const { return engine_.loops_completed(); }
    EnvelopeStage stage() const { return engine_.stage(); }
 
private:
    detail::EnvelopeEngine<SampleType> engine_{};
};
 
using Dahdsr = DahdsrT<float>;
using Dahdsr64 = DahdsrT<double>;

template <typename SampleType = float>
class ModEnvT {
public:
    void prepare(double sample_rate) {
        engine_.set_has_sustain(false);
        engine_.set_gate_driven(false);
        engine_.prepare(sample_rate);
    }
 
    void set_delay_ms(double ms) { engine_.set_delay_ms(ms); }
    void set_attack_ms(double ms) { engine_.set_attack_ms(ms); }
    void set_hold_ms(double ms) { engine_.set_hold_ms(ms); }
    void set_decay_ms(double ms) { engine_.set_decay_ms(ms); }
    void set_release_ms(double ms) { engine_.set_release_ms(ms); }
    void set_sustain(SampleType level) { engine_.set_sustain(level); }
    void set_attack_curve(float c) { engine_.set_attack_curve(c); }
    void set_decay_curve(float c) { engine_.set_decay_curve(c); }
    void set_curve(double c) {
        const float curve = static_cast<float>(std::clamp(c, 0.0, 1.0));
        engine_.set_attack_curve(-curve);
        engine_.set_decay_curve(curve);
        engine_.set_release_curve(curve);
    }
    void set_loop(bool on, int count = 0) { engine_.set_loop(on, count); }

    void set_depth(SampleType d) { depth_ = std::clamp(d, SampleType{-1}, SampleType{1}); }
 
    void trigger(SampleType velocity = SampleType{1}) {
        legacy_scaled_next_ = false;
        engine_.set_has_sustain(false);
        engine_.set_gate_driven(false);
        engine_.trigger(velocity);
    }
    void gate_on() {
        legacy_scaled_next_ = true;
        engine_.set_has_sustain(true);
        engine_.set_gate_driven(true);
        engine_.trigger(SampleType{1});
    }
    void gate_off() { engine_.release(); }
    void reset() { engine_.reset(); }

    SampleType next() {
        const SampleType level = engine_.next();
        return legacy_scaled_next_ ? level * depth_ : level;
    }

    SampleType modulation() const { return engine_.current() * depth_; }
 
    SampleType current() const { return engine_.current(); }
    SampleType value() const {
        return legacy_scaled_next_ ? engine_.current() * depth_ : engine_.current();
    }
    bool active() const { return engine_.active(); }
    EnvelopeStage stage() const { return engine_.stage(); }
 
private:
    detail::EnvelopeEngine<SampleType> engine_{};
    SampleType depth_ = SampleType{1};
    bool legacy_scaled_next_ = false;
};
 
using ModEnv = ModEnvT<float>;
using ModEnv64 = ModEnvT<double>;

template <typename SampleType = float>
class TransientDetectorT {
public:
    static constexpr SampleType kDefaultFastMs = SampleType{2};
    static constexpr SampleType kDefaultSlowMs = SampleType{40};
 
    void prepare(SampleType sample_rate) {
        // RMS rather than peak on both followers: a peak follower fast enough
        // to sit on an attack also tracks the waveform ripple of any low tone,
        // which reads as a permanent 20% transient on a held bass note. RMS
        // averages the ripple out without slowing the attack response.
        fast_.set_mode(BallisticsFilterT<SampleType>::Mode::rms);
        slow_.set_mode(BallisticsFilterT<SampleType>::Mode::rms);
        fast_.prepare(sample_rate);
        slow_.prepare(sample_rate);
        apply_times_();
    }
 
    void set_fast_ms(SampleType ms) {
        fast_ms_ = std::max(SampleType{0.01}, ms);
        apply_times_();
    }
 
    void set_slow_ms(SampleType ms) {
        slow_ms_ = std::max(SampleType{0.01}, ms);
        apply_times_();
    }
 
    void reset() {
        fast_.reset();
        slow_.reset();
    }
 
    SampleType process(SampleType input) {
        const SampleType magnitude = std::abs(input);
        const SampleType f = fast_.process(magnitude);
        const SampleType s = slow_.process(magnitude);
        // The floor only engages in near-silence, well below any level where a
        // transient means anything, so it does not break scale invariance in
        // the range the detector is actually used in.
        const SampleType denominator = std::max(s, SampleType{1e-9});
        return std::max(SampleType{0}, (f - s) / denominator);
    }
 
private:
    void apply_times_() {
        // Symmetric ballistics on both followers: the detector compares two
        // time scales, and an asymmetric follower would make the comparison
        // depend on whether the signal happens to be rising.
        fast_.set_attack_ms(fast_ms_);
        fast_.set_release_ms(fast_ms_);
        slow_.set_attack_ms(slow_ms_);
        slow_.set_release_ms(slow_ms_);
    }
 
    BallisticsFilterT<SampleType> fast_{};
    BallisticsFilterT<SampleType> slow_{};
    SampleType fast_ms_ = kDefaultFastMs;
    SampleType slow_ms_ = kDefaultSlowMs;
};
 
using TransientDetector = TransientDetectorT<float>;
using TransientDetector64 = TransientDetectorT<double>;
 
} // namespace pulp::signal