feedforward_compressor.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/denormal.hpp>
#include <pulp/signal/dynamics_core.hpp>
#include <pulp/signal/dynamics_contract.hpp>
#include <pulp/signal/units.hpp>
 
#include <algorithm>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <vector>
 
namespace pulp::signal {

enum class CompressorDetector : std::uint8_t {
    peak,  
    rms,   
};

template <typename SampleType = float>
class FeedforwardCompressorT {
public:
    using Detector = CompressorDetector;
 
    // ── Design parameters (the complete roster) ───────────────────────────

    static constexpr double kLevelEpsilon = dynamics::kLevelEpsilon;

    static constexpr double kSlowReleaseRatio = 4.0;

    static constexpr double kSustainTauMs = 200.0;

    static constexpr double kSustainThresholdDb = 3.0;
 
    // Control ranges. These mirror the catalog node's parameter table; the
    // table is the canonical declaration and these are the same numbers at the
    // call site, not a second independent one.
    static constexpr double kThresholdDbMin = -60.0;
    static constexpr double kThresholdDbMax = 0.0;
    static constexpr double kRatioMin = 1.0;
    static constexpr double kRatioMax = 100.0;
    static constexpr double kKneeDbMin = 0.0;
    static constexpr double kKneeDbMax = 24.0;
    static constexpr double kAttackMsMin = 0.05;
    static constexpr double kAttackMsMax = 200.0;
    static constexpr double kReleaseMsMin = 5.0;
    static constexpr double kReleaseMsMax = 4000.0;
    static constexpr double kRmsWindowMsMin = 1.0;
    static constexpr double kRmsWindowMsMax = 50.0;
    static constexpr double kMakeupDbMax = 24.0;

    static constexpr double kMaxLookaheadMsCeiling = 50.0;
 
    // ── Lifecycle ─────────────────────────────────────────────────────────

    void prepare(double sample_rate, double max_lookahead_ms = 10.0) {
        sample_rate_ = sample_rate > 0.0 ? sample_rate : sample_rate_;
        max_lookahead_ms_ = std::clamp(max_lookahead_ms, 0.0, kMaxLookaheadMsCeiling);
 
        const auto capacity = static_cast<std::size_t>(
            std::llround(units::ms_to_samples(max_lookahead_ms_, sample_rate_))) + 1;
        for (auto& ring : lookahead_) ring.assign(capacity, SampleType{0});
 
        update_coefficients();
        update_lookahead();
        update_makeup();
        reset();
    }

    void reset() {
        for (auto& ch : channels_) ch = ChannelState{};
        for (auto& ring : lookahead_) std::fill(ring.begin(), ring.end(), SampleType{0});
        write_index_[0] = 0;
        write_index_[1] = 0;
        lookahead_valid_[0] = 0;
        lookahead_valid_[1] = 0;
    }
 
    // ── Controls (real units throughout) ──────────────────────────────────
 
    void set_threshold_db(double db) {
        threshold_db_ = std::clamp(dynamics::retain_finite(db, threshold_db_),
                                   kThresholdDbMin, kThresholdDbMax);
        update_makeup();
    }
 
    void set_ratio(double r) {
        ratio_ = std::clamp(dynamics::retain_finite(r, ratio_), kRatioMin, kRatioMax);
        update_makeup();
    }
 
    void set_knee_width_db(double w) {
        knee_db_ = std::clamp(dynamics::retain_finite(w, knee_db_),
                              kKneeDbMin, kKneeDbMax);
        update_makeup();
    }
 
    void set_attack_ms(double ms) {
        attack_ms_ = std::clamp(dynamics::retain_finite(ms, attack_ms_),
                                kAttackMsMin, kAttackMsMax);
        update_coefficients();
    }
 
    void set_release_ms(double ms) {
        release_ms_ = std::clamp(dynamics::retain_finite(ms, release_ms_),
                                 kReleaseMsMin, kReleaseMsMax);
        update_coefficients();
    }
 
    void set_detector(Detector d) { detector_ = d; }
    Detector detector() const { return detector_; }
 
    void set_rms_window_ms(double ms) {
        rms_window_ms_ = std::clamp(dynamics::retain_finite(ms, rms_window_ms_),
                                    kRmsWindowMsMin, kRmsWindowMsMax);
        update_coefficients();
    }

    void set_lookahead_ms(double ms) {
        lookahead_ms_ = std::clamp(dynamics::retain_finite(ms, lookahead_ms_),
                                   0.0, max_lookahead_ms_);
        update_lookahead();
    }
 
    void set_program_dependent_release(bool on) { program_dependent_ = on; }
 
    void set_makeup_gain_db(double db) {
        makeup_db_ = std::clamp(dynamics::retain_finite(db, makeup_db_),
                                -kMakeupDbMax, kMakeupDbMax);
        update_makeup();
    }
 
    void set_auto_makeup(bool on) {
        auto_makeup_ = on;
        update_makeup();
    }

    void set_stereo_link(double amount) {
        stereo_link_ = std::clamp(dynamics::retain_finite(amount, stereo_link_), 0.0, 1.0);
    }

    int latency_samples() const noexcept { return lookahead_samples_; }

    double static_curve_db(double input_db) const {
        return dynamics::soft_knee_output_db(input_db, threshold_db_, knee_db_, ratio_);
    }

    double gain_computer_db(double input_db) const {
        return static_curve_db(input_db) - input_db;
    }

    double effective_makeup_db() const { return auto_makeup_ ? auto_makeup_db_ : makeup_db_; }

    double gain_reduction_db(int channel = 0) const {
        return channels_[static_cast<std::size_t>(channel & 1)].smoothed_reduction;
    }

    GainReduction gain_reduction(int channel = 0) const noexcept {
        return GainReduction::from_magnitude_db(gain_reduction_db(channel));
    }
 
    // ── Processing ────────────────────────────────────────────────────────

    SampleType process(SampleType input) {
        // A non-finite sample is not audio and must not become detector or
        // lookahead history. Clear the owned recursive state so the very next
        // finite sample is processed from a valid, deterministic state.
        if (!std::isfinite(static_cast<double>(input))) {
            recover_audio_fault();
            return SampleType{0};
        }
        const double level_db = detect_level_db(0, static_cast<double>(input));
        const double gain = channel_gain(0, level_db);
        return static_cast<SampleType>(delayed(0, input) * gain * makeup_linear_);
    }

    void process_stereo(SampleType& left, SampleType& right) {
        if (!std::isfinite(static_cast<double>(left)) ||
            !std::isfinite(static_cast<double>(right))) {
            recover_audio_fault();
            left = SampleType{0};
            right = SampleType{0};
            return;
        }
        const double left_db = detect_level_db(0, static_cast<double>(left));
        const double right_db = detect_level_db(1, static_cast<double>(right));
 
        // The blend crosses the two DETECTOR INPUTS, before the detector, not
        // two finished gain-reduction values after it.
        const double shared_db = std::max(left_db, right_db);
        const double left_used = left_db + stereo_link_ * (shared_db - left_db);
        const double right_used = right_db + stereo_link_ * (shared_db - right_db);
 
        const double left_gain = channel_gain(0, left_used);
        const double right_gain = channel_gain(1, right_used);
 
        const SampleType dry_left = delayed(0, left);
        const SampleType dry_right = delayed(1, right);
        left = static_cast<SampleType>(dry_left * left_gain * makeup_linear_);
        right = static_cast<SampleType>(dry_right * right_gain * makeup_linear_);
    }
 
    void process_block(SampleType* io, int n) {
        for (int i = 0; i < n; ++i) io[i] = process(io[i]);
    }
 
    void process_block_stereo(SampleType* left, SampleType* right, int n) {
        for (int i = 0; i < n; ++i) process_stereo(left[i], right[i]);
    }
 
private:
    void recover_audio_fault() noexcept {
        for (auto& ch : channels_) ch = ChannelState{};
        write_index_[0] = write_index_[1] = 0;
        lookahead_valid_[0] = lookahead_valid_[1] = 0;
    }
 
    struct ChannelState {
        double mean_square = 0.0;      
        double release_stage = 0.0;    
        double smoothed_reduction = 0.0;  
        double sustain = 0.0;          
    };

    double detect_level_db(int channel, double x) {
        auto& ch = channels_[static_cast<std::size_t>(channel)];
        if (detector_ == Detector::peak) return dynamics::amplitude_db(x, kLevelEpsilon);
 
        // `power_db` is `10·log10`, not 20, because the integrator already holds
        // a squared quantity — see its note in `dynamics_core.hpp`.
        ch.mean_square = snap_to_zero(rms_coef_ * ch.mean_square + (1.0 - rms_coef_) * x * x);
        return dynamics::power_db(ch.mean_square, kLevelEpsilon);
    }

    double channel_gain(int channel, double level_db) {
        auto& ch = channels_[static_cast<std::size_t>(channel)];
 
        // Positive magnitude from here on; see the sign-convention note in the
        // file doc block.
        const double reduction = -gain_computer_db(level_db);
 
        double release_coef = release_coef_;
        if (program_dependent_) {
            // The sustain detector is a one-pole over the indicator "is the
            // CURRENT reduction deep enough to count", so it rises while
            // compression is held and falls once it lets go.
            const double sustained =
                ch.smoothed_reduction > kSustainThresholdDb ? 1.0 : 0.0;
            ch.sustain = sustain_coef_ * ch.sustain + (1.0 - sustain_coef_) * sustained;
            release_coef = release_coef_ + ch.sustain * (slow_release_coef_ - release_coef_);
        }
 
        ch.release_stage = std::max(
            reduction, release_coef * ch.release_stage + (1.0 - release_coef) * reduction);
        ch.smoothed_reduction = snap_to_zero(
            attack_coef_ * ch.smoothed_reduction + (1.0 - attack_coef_) * ch.release_stage);
 
        return std::pow(10.0, -ch.smoothed_reduction / 20.0);
    }

    SampleType delayed(int channel, SampleType input) {
        if (lookahead_samples_ <= 0) return input;
        const auto index = static_cast<std::size_t>(channel);
        auto& ring = lookahead_[index];
        if (ring.empty()) return input;
 
        const std::size_t size = ring.size();
        std::size_t& write = write_index_[index];
        const std::size_t read =
            (write + size - static_cast<std::size_t>(lookahead_samples_)) % size;
        const SampleType out = lookahead_valid_[index] >= static_cast<std::size_t>(lookahead_samples_)
                                   ? ring[read]
                                   : SampleType{0};
        ring[write] = input;
        write = (write + 1) % size;
        if (lookahead_valid_[index] < size) ++lookahead_valid_[index];
        return out;
    }
 
    void update_coefficients() {
        attack_coef_ = one_pole(attack_ms_);
        release_coef_ = one_pole(release_ms_);
        slow_release_coef_ = one_pole(release_ms_ * kSlowReleaseRatio);
        sustain_coef_ = one_pole(kSustainTauMs);
        rms_coef_ = one_pole(rms_window_ms_);
    }

    double one_pole(double tau_ms) const {
        return dynamics::one_pole_retain(tau_ms * 0.001, sample_rate_);
    }
 
    void update_lookahead() {
        lookahead_samples_ = static_cast<int>(
            std::llround(units::ms_to_samples(lookahead_ms_, sample_rate_)));
        const auto capacity = lookahead_[0].size();
        if (capacity > 0 && lookahead_samples_ >= static_cast<int>(capacity))
            lookahead_samples_ = static_cast<int>(capacity) - 1;
        if (lookahead_samples_ < 0) lookahead_samples_ = 0;
    }
 
    void update_makeup() {
        // Exactly cancels the gain computer's own reduction at a 0 dBFS input —
        // the "unity at the reference point" convention. Closed form, evaluated
        // on a control change rather than per sample.
        auto_makeup_db_ = -gain_computer_db(0.0);
        makeup_linear_ = units::db_to_linear(effective_makeup_db());
    }
 
    double sample_rate_ = 44100.0;
    double max_lookahead_ms_ = 10.0;
 
    double threshold_db_ = -18.0;
    double ratio_ = 4.0;
    double knee_db_ = 6.0;
    double attack_ms_ = 10.0;
    double release_ms_ = 120.0;
    double rms_window_ms_ = 10.0;
    double lookahead_ms_ = 0.0;
    double makeup_db_ = 0.0;
    double stereo_link_ = 1.0;
    Detector detector_ = Detector::peak;
    bool program_dependent_ = true;
    bool auto_makeup_ = true;
 
    double attack_coef_ = 0.0;
    double release_coef_ = 0.0;
    double slow_release_coef_ = 0.0;
    double sustain_coef_ = 0.0;
    double rms_coef_ = 0.0;
    double auto_makeup_db_ = 0.0;
    double makeup_linear_ = 1.0;
    int lookahead_samples_ = 0;
 
    ChannelState channels_[2]{};
    std::vector<SampleType> lookahead_[2]{};
    std::size_t write_index_[2]{0, 0};
    std::size_t lookahead_valid_[2]{0, 0};
};
 
using FeedforwardCompressor = FeedforwardCompressorT<float>;
using FeedforwardCompressor64 = FeedforwardCompressorT<double>;
 
}  // namespace pulp::signal