vca_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 <vector>
 
namespace pulp::signal {

template <typename SampleType = float>
class VcaCompressorT {
public:
    // ── Design parameters (the complete roster) ───────────────────────────

    static constexpr double kFloorLinear = 1e-12;

    static constexpr double kRatioKDefault = 4.0;
    static constexpr double kRatioKMin = 2.0;
    static constexpr double kRatioKMax = 8.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 = 20.0;
    static constexpr double kNegRatioMin = -20.0;
    static constexpr double kNegRatioMax = -1.0;
    static constexpr double kKneeDbMin = 0.0;
    static constexpr double kKneeDbMax = 24.0;
    static constexpr double kTimeMsMin = 1.0;
    static constexpr double kTimeMsMax = 500.0;
    static constexpr double kMakeupDbMax = 24.0;
    static constexpr double kLookaheadMsMax = 10.0;

    static constexpr double kCeilingDbDefault = 96.0;
    static constexpr double kCeilingDbMin = 60.0;
    static constexpr double kCeilingDbMax = 144.0;
 
    // ── Lifecycle ─────────────────────────────────────────────────────────

    void prepare(double sample_rate) {
        sample_rate_ = sample_rate > 0.0 ? sample_rate : sample_rate_;
 
        const auto capacity = static_cast<std::size_t>(std::llround(
                                  units::ms_to_samples(kLookaheadMsMax, sample_rate_))) +
                              1;
        lookahead_.assign(capacity, SampleType{0});
 
        update_coefficients();
        update_lookahead();
        reset();
    }

    void reset() {
        mean_square_ = 0.0;
        level_db_ = 10.0 * std::log10(kFloorLinear);
        gain_reduction_db_ = 0.0;
        gain_linear_ = units::db_to_linear(makeup_db_);
        std::fill(lookahead_.begin(), lookahead_.end(), SampleType{0});
        write_index_ = 0;
        lookahead_valid_ = 0;
    }
 
    // ── Controls (real units throughout) ──────────────────────────────────
 
    void set_threshold_db(double db) {
        threshold_db_ = std::clamp(dynamics::retain_finite(db, threshold_db_),
                                   kThresholdDbMin, kThresholdDbMax);
    }

    void set_ratio(double r) {
        ratio_ = std::clamp(dynamics::retain_finite(r, ratio_), kRatioMin, kRatioMax);
    }

    void set_negative_ratio_mode(bool enabled) { negative_ratio_ = enabled; }

    void set_neg_ratio_amount(double r) {
        neg_ratio_ = std::clamp(dynamics::retain_finite(r, neg_ratio_),
                                kNegRatioMin, kNegRatioMax);
    }

    void set_knee_db(double db) {
        knee_db_ = std::clamp(dynamics::retain_finite(db, knee_db_),
                              kKneeDbMin, kKneeDbMax);
    }

    void set_time_ms(double ms) {
        time_ms_ = std::clamp(dynamics::retain_finite(ms, time_ms_),
                              kTimeMsMin, kTimeMsMax);
        update_coefficients();
    }

    void set_attack_release_ratio_k(double k) {
        ratio_k_ = std::clamp(dynamics::retain_finite(k, ratio_k_),
                              kRatioKMin, kRatioKMax);
        update_coefficients();
    }
 
    void set_makeup_db(double db) {
        makeup_db_ = std::clamp(dynamics::retain_finite(db, makeup_db_),
                                -kMakeupDbMax, kMakeupDbMax);
    }

    void set_lookahead_ms(double ms) {
        lookahead_ms_ = std::clamp(dynamics::retain_finite(ms, lookahead_ms_),
                                   0.0, kLookaheadMsMax);
        update_lookahead();
    }

    void set_mix(double mix01) {
        mix_ = std::clamp(dynamics::retain_finite(mix01, mix_), 0.0, 1.0);
    }
 
    void set_ceiling_db(double db) {
        ceiling_db_ = std::clamp(dynamics::retain_finite(db, ceiling_db_),
                                 kCeilingDbMin, kCeilingDbMax);
    }
 
    // ── Read-only taps ────────────────────────────────────────────────────

    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_, active_ratio());
    }

    double gain_computer_db(double input_db) const {
        return std::max(static_curve_db(input_db) - input_db, -ceiling_db_);
    }

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

    double active_ratio() const noexcept { return negative_ratio_ ? neg_ratio_ : ratio_; }

    double gain_reduction_db() const noexcept { return gain_reduction_db_; }
    GainReduction gain_reduction() const noexcept {
        return GainReduction::from_signed_db(gain_reduction_db_);
    }
    double level_db() const noexcept { return level_db_; }
    double mean_square() const noexcept { return mean_square_; }
    double current_gain_linear() const noexcept { return gain_linear_; }

    double attack_coef() const noexcept { return attack_coef_; }
    double release_coef() const noexcept { return release_coef_; }
 
    // ── Processing ────────────────────────────────────────────────────────
 
    SampleType process(SampleType input) {
        // Do not admit a non-finite sample into either the direction-switched
        // detector or the lookahead ring: both are recursive state and would
        // otherwise remain poisoned after the bad sample has passed.
        if (!std::isfinite(static_cast<double>(input))) {
            recover_audio_fault();
            return SampleType{0};
        }
        level_db_ = detect_level_db(static_cast<double>(input));
        gain_reduction_db_ = gain_computer_db(level_db_);
        gain_linear_ = units::db_to_linear(gain_reduction_db_ + makeup_db_);
 
        // The detector read `x[n]` un-delayed above; the AUDIO is what the
        // lookahead delays, which is the whole point — it gives the detector a
        // head start on the sample it is about to gate.
        const double dry = static_cast<double>(delayed(input));
        return static_cast<SampleType>(dry * (mix_ * gain_linear_ + (1.0 - mix_)));
    }
 
    void process_block(SampleType* io, int n) {
        for (int i = 0; i < n; ++i) io[i] = process(io[i]);
    }
 
private:
    void recover_audio_fault() noexcept {
        mean_square_ = 0.0;
        level_db_ = 10.0 * std::log10(kFloorLinear);
        gain_reduction_db_ = 0.0;
        gain_linear_ = units::db_to_linear(makeup_db_);
        write_index_ = 0;
        lookahead_valid_ = 0;
    }

    double detect_level_db(double x) {
        const double p = x * x;
        const double a = p > mean_square_ ? attack_coef_ : release_coef_;
        mean_square_ = snap_to_zero(mean_square_ + a * (p - mean_square_));
        return 10.0 * std::log10(std::max(mean_square_, kFloorLinear));
    }

    SampleType delayed(SampleType input) {
        if (lookahead_samples_ <= 0 || lookahead_.empty()) return input;
        const std::size_t size = lookahead_.size();
        const std::size_t read =
            (write_index_ + size - static_cast<std::size_t>(lookahead_samples_)) % size;
        const SampleType out = lookahead_valid_ >= static_cast<std::size_t>(lookahead_samples_)
                                   ? lookahead_[read]
                                   : SampleType{0};
        lookahead_[write_index_] = input;
        write_index_ = (write_index_ + 1) % size;
        if (lookahead_valid_ < size) ++lookahead_valid_;
        return out;
    }

    void update_coefficients() {
        release_coef_ = units::ms_to_onepole_coef(time_ms_, sample_rate_);
        attack_coef_ = units::ms_to_onepole_coef(time_ms_ / ratio_k_, sample_rate_);
    }
 
    void update_lookahead() {
        lookahead_samples_ =
            static_cast<int>(std::llround(units::ms_to_samples(lookahead_ms_, sample_rate_)));
        const auto capacity = lookahead_.size();
        if (capacity > 0 && lookahead_samples_ >= static_cast<int>(capacity))
            lookahead_samples_ = static_cast<int>(capacity) - 1;
        if (lookahead_samples_ < 0) lookahead_samples_ = 0;
    }
 
    double sample_rate_ = 44100.0;
 
    double threshold_db_ = -20.0;
    double ratio_ = 4.0;
    double neg_ratio_ = -4.0;
    double knee_db_ = 10.0;
    double time_ms_ = 30.0;
    double ratio_k_ = kRatioKDefault;
    double makeup_db_ = 0.0;
    double lookahead_ms_ = 0.0;
    double mix_ = 1.0;
    double ceiling_db_ = kCeilingDbDefault;
    bool negative_ratio_ = false;
 
    double attack_coef_ = 0.0;
    double release_coef_ = 0.0;
    int lookahead_samples_ = 0;
 
    double mean_square_ = 0.0;
    double level_db_ = 10.0 * -12.0;  // 10·log10(kFloorLinear), as a constant expression.
    double gain_reduction_db_ = 0.0;
    double gain_linear_ = 1.0;
 
    std::vector<SampleType> lookahead_{};
    std::size_t write_index_ = 0;
    std::size_t lookahead_valid_ = 0;
};
 
using VcaCompressor = VcaCompressorT<float>;
using VcaCompressor64 = VcaCompressorT<double>;
 
}  // namespace pulp::signal