chorus_family.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/character_delay/bbd.hpp>
#include <pulp/signal/delay_line.hpp>
#include <pulp/signal/interpolator.hpp>
#include <pulp/signal/lfo.hpp>
#include <pulp/signal/tpt_filter.hpp>
#include <pulp/signal/units.hpp>
 
#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>
 
namespace pulp::signal {

template <typename SampleType = float>
class ChorusEnsembleT {
public:
    enum class Voicing : std::uint8_t { ce2, juno_ensemble, dimension_d, tri_chorus };

    enum class JunoMode : std::uint8_t { mode_I, mode_II, mode_I_plus_II };
 
    // ── Structural constants ──────────────────────────────────────────────

    static constexpr int kMaxVoices = 3;
    static constexpr std::size_t kVoiceSlots = static_cast<std::size_t>(kMaxVoices);

    static constexpr int kInterpOrder = 3;

    static constexpr int kGuardSamples = kInterpOrder + 1;

    static constexpr double kMaxDelayMs = 40.0;
 
    // ── Dimension D constants ─────────────────────────────────────────────

    static constexpr double kTrapK = 1.8;

    static constexpr double kDimCornerHz = 200.0;

    static constexpr double kDimBoostDb = 1.5;
 
    // ── BBD colour constants ──────────────────────────────────────────────

    static constexpr double kBbdColorCharacter = 1.0;

    static constexpr double kBbdColorGuardMs = 0.5;
 
    // ── Calibration tables ────────────────────────────────────────────────

    struct Calibration {
        double center_ms;
        double depth_ms;
        double rate_hz;
        double mix_default;
        int voices;
        LfoWave wave;
        bool mono_source;
        bool trapezoid;
    };
 
    static constexpr Calibration calibration(Voicing v) {
        switch (v) {
            case Voicing::ce2:
                // d_center 12 ms [dp, range 5–25], d_depth 6 ms [dp, range
                // 2–10], rate 1.2 Hz [dp, range 0.05–10], internal blend 0.5
                // [dp, range 0.3–0.7 — the pedal has no mix knob]. The
                // enclosing 5–40 ms practical zone and the MN3007's
                // 5.12–51.2 ms device range are the cited part (ElectroSmash,
                // "Boss CE-2 Analysis"); the calibration inside it is not
                // published and is an honest gap.
                return {12.0, 6.0, 1.2, 0.5, 1, LfoWave::triangle, true, false};
            case Voicing::juno_ensemble:
                // Placeholder row: the Juno's numbers are per-mode and come
                // from juno_spec(). Only `voices`, `wave` and the routing flags
                // are read for this voicing.
                return {3.505, 1.845, 0.513, 0.5, 2, LfoWave::triangle, false, false};
            case Voicing::dimension_d:
                // All four numbers [dp] — honest gap. d_center 6 ms [range
                // 3–12], d_depth 1.5 ms [range 0.3–3] (deliberately shallow:
                // the unit is engineered not to sound like modulation), rate
                // 0.6 Hz [range 0.2–1.5], mix 0.5 [range 0.3–0.7]. Roland's
                // SDD-320 service notes document the topology, not constants.
                return {6.0, 1.5, 0.6, 0.5, 2, LfoWave::triangle, false, true};
            case Voicing::tri_chorus:
                // All [dp] — honest gap. The 120°-spaced three-voice L/C/R
                // topology is documented across the Dytronics Songbird
                // TSC-1380 lineage (Fractal Audio's Chorus block notes,
                // Eventide's TriceraChorus documentation); no source publishes
                // delay or rate figures, by design — the family spans many
                // implementations. d_center 15 ms [range 8–25], d_depth 4 ms
                // [range 1–8], rate 0.8 Hz [range 0.3–3], mix 0.5 [0.3–0.7].
                return {15.0, 4.0, 0.8, 0.5, 3, LfoWave::sine, true, false};
        }
        return {12.0, 6.0, 1.2, 0.5, 1, LfoWave::triangle, true, false};
    }

    struct JunoModeSpec {
        double center_ms;
        double depth_ms;
        double rate_a_hz;
        double rate_b_hz;  
        bool dual;
    };
 
    static constexpr JunoModeSpec juno_spec(JunoMode m) {
        constexpr double kLoMs = 1.66;   // published
        constexpr double kHiMs = 5.35;   // published
        constexpr double kRateI = 0.513;  // published, Hz
        constexpr double kRateII = 0.863; // published, Hz
        constexpr double kBothLoMs = 3.3; // published
        constexpr double kBothHiMs = 3.7; // published
        switch (m) {
            case JunoMode::mode_I:
                return {0.5 * (kLoMs + kHiMs), 0.5 * (kHiMs - kLoMs), kRateI, 0.0, false};
            case JunoMode::mode_II:
                return {0.5 * (kLoMs + kHiMs), 0.5 * (kHiMs - kLoMs), kRateII, 0.0, false};
            case JunoMode::mode_I_plus_II:
                return {0.5 * (kBothLoMs + kBothHiMs), 0.5 * (kBothHiMs - kBothLoMs),
                        kRateI, kRateII, true};
        }
        return {0.5 * (kLoMs + kHiMs), 0.5 * (kHiMs - kLoMs), kRateI, 0.0, false};
    }
 
    // ── Lifecycle ─────────────────────────────────────────────────────────
 
    ChorusEnsembleT() { configure_voicing(); }

    void prepare(double sample_rate) {
        sample_rate_ = (std::isfinite(sample_rate) && sample_rate > 0.0) ? sample_rate : 48000.0;
 
        const int capacity = static_cast<int>(
            std::ceil(kMaxDelayMs * 0.001 * sample_rate_)) + kGuardSamples + kInterpOrder + 2;
        for (auto& line : lines_) line.prepare(capacity);
        max_read_samples_ = static_cast<double>(capacity - kInterpOrder - 1);
 
        for (std::size_t k = 0; k < kVoiceSlots; ++k) {
            lfo_a_[k].prepare(sample_rate_);
            lfo_b_[k].prepare(sample_rate_);
            bbd_[k].prepare(sample_rate_);
            // Distinct clock-jitter streams per voice. Sharing one seed would
            // make three "independent" BBDs wander in lockstep, which is
            // exactly the correlation the third voice exists to avoid.
            bbd_[k].set_seed(chardelay::kPrngSeed ^ (0x9E3779B9u * static_cast<std::uint32_t>(k + 1)));
        }
        for (std::size_t c = 0; c < 2; ++c) {
            shelf_lowpass_[c].prepare(sample_rate_);
            shelf_lowpass_[c].set_cutoff(kDimCornerHz);
            cross_highpass_[c].prepare(sample_rate_);
            cross_highpass_[c].set_cutoff(kDimCornerHz);
        }
 
        prepared_ = true;
        configure_voicing();
        reset();
    }
 
    // ── Configuration ─────────────────────────────────────────────────────

    void set_voicing(Voicing v) {
        voicing_ = v;
        configure_voicing();
    }
 
    Voicing voicing() const { return voicing_; }

    void set_juno_mode(JunoMode m) {
        juno_mode_ = m;
        if (voicing_ == Voicing::juno_ensemble) configure_voicing();
    }
 
    JunoMode juno_mode() const { return juno_mode_; }

    void set_rate_hz(SampleType hz) {
        if (!std::isfinite(static_cast<double>(hz))) return;
        rate_hz_ = std::clamp(static_cast<double>(hz), kRateMinHz, kRateMaxHz);
        apply_rates();
    }
 
    double rate_hz() const { return rate_hz_; }

    void set_depth(SampleType depth01) {
        if (!std::isfinite(static_cast<double>(depth01))) return;
        depth_ = std::clamp(static_cast<double>(depth01), 0.0, 1.0);
    }

    void set_mix(SampleType mix01) {
        if (!std::isfinite(static_cast<double>(mix01))) return;
        mix_ = std::clamp(static_cast<double>(mix01), 0.0, 1.0);
    }

    void set_stereo_width(SampleType width01) {
        if (!std::isfinite(static_cast<double>(width01))) return;
        width_ = std::clamp(static_cast<double>(width01), 0.0, 1.0);
    }

    void set_bbd_color(bool on) {
        bbd_color_ = on;
        update_bbd_stage();
    }
 
    bool bbd_color() const { return bbd_color_; }
 
    // ── Audio ─────────────────────────────────────────────────────────────
 
    void process(SampleType* left, SampleType* right, int n) {
        if (!prepared_ || left == nullptr || right == nullptr) return;
 
        const Calibration cal = calibration(voicing_);
        const bool juno = voicing_ == Voicing::juno_ensemble;
        const JunoModeSpec juno_cal = juno_spec(juno_mode_);
        const double center_ms = juno ? juno_cal.center_ms : cal.center_ms;
        const double depth_ms = depth_ * (juno ? juno_cal.depth_ms : cal.depth_ms);
        const double ms_to_samples = sample_rate_ * 0.001;
        const double boost_extra = units::db_to_linear(kDimBoostDb) - 1.0;
 
        for (int i = 0; i < n; ++i) {
            const double in_l = static_cast<double>(left[i]);
            const double in_r = static_cast<double>(right[i]);
            if (!std::isfinite(in_l) || !std::isfinite(in_r)) {
                discard_history();
                left[i] = right[i] = SampleType{0};
                continue;
            }
            const double src_l = cal.mono_source ? 0.5 * (in_l + in_r) : in_l;
            const double src_r = cal.mono_source ? src_l : in_r;
 
            lines_[0].push(static_cast<SampleType>(src_l));
            lines_[1].push(static_cast<SampleType>(src_r));
 
            std::array<double, kVoiceSlots> wet{};
            const auto active = static_cast<std::size_t>(voices_);
            for (std::size_t k = 0; k < active; ++k) {
                const double m = modulation(k);
                const double delay_ms = center_ms + depth_ms * m;
                delay_ms_[k] = delay_ms;
 
                double read_samples = delay_ms * ms_to_samples;
                if (bbd_color_) read_samples -= bbd_delay_samples_;
                read_samples = std::clamp(read_samples,
                                          static_cast<double>(kGuardSamples),
                                          max_read_samples_);
 
                double tap = read_lagrange(lines_[voice_line_[k]], read_samples);
                if (bbd_color_) tap = bbd_[k].process(tap);
                wet[k] = tap;
            }
 
            double matrix_l = 0.0;
            double matrix_r = 0.0;
            switch (voicing_) {
                case Voicing::ce2:
                    matrix_l = src_l + wet[0];
                    matrix_r = matrix_l;
                    break;
                case Voicing::juno_ensemble:
                    matrix_l = in_l + wet[0];
                    matrix_r = in_r + wet[1];
                    break;
                case Voicing::dimension_d: {
                    // Cross-feed is high-passed so only mid and high content
                    // participates in the cancellation; the dry is shelved by
                    // the complementary low-pass so the low end that the
                    // cross-mix would thin out stays solid and centred.
                    const double boost_l = in_l + boost_extra * shelf_lowpass_[0].process_lowpass(in_l);
                    const double boost_r = in_r + boost_extra * shelf_lowpass_[1].process_lowpass(in_r);
                    const double cross_l = cross_highpass_[0].process_highpass(wet[1]);
                    const double cross_r = cross_highpass_[1].process_highpass(wet[0]);
                    matrix_l = boost_l + wet[0] - width_ * cross_l;
                    matrix_r = boost_r + wet[1] - width_ * cross_r;
                    break;
                }
                case Voicing::tri_chorus:
                    matrix_l = in_l + wet[0] + width_ * 0.5 * wet[1];
                    matrix_r = in_r + wet[2] + width_ * 0.5 * wet[1];
                    break;
            }
 
            left[i] = static_cast<SampleType>((1.0 - mix_) * in_l + mix_ * matrix_l);
            right[i] = static_cast<SampleType>((1.0 - mix_) * in_r + mix_ * matrix_r);
        }
    }
 
    void reset() {
        for (auto& line : lines_) line.reset();
        for (std::size_t k = 0; k < kVoiceSlots; ++k) {
            lfo_a_[k].reset();
            lfo_b_[k].reset();
            bbd_[k].reset();
            delay_ms_[k] = 0.0;
        }
        for (std::size_t c = 0; c < 2; ++c) {
            shelf_lowpass_[c].reset();
            cross_highpass_[c].reset();
        }
    }

    void discard_history() noexcept {
        for (auto& line : lines_) line.discard_history();
        for (std::size_t k = 0; k < kVoiceSlots; ++k) {
            lfo_a_[k].reset();
            lfo_b_[k].reset();
            bbd_[k].reset();
            delay_ms_[k] = 0.0;
        }
        for (std::size_t c = 0; c < 2; ++c) {
            shelf_lowpass_[c].reset();
            cross_highpass_[c].reset();
        }
    }

    int latency_samples() const { return 0; }
 
    // ── Observability ─────────────────────────────────────────────────────
    //
    // These exist so the acceptance suite can measure the modulation directly
    // rather than only inferring it from audio. The suite still proves them
    // against the audio path (the delay-range test cross-checks
    // `current_delay_ms` against a click train tracked through `process`) —
    // an accessor that agreed with itself would test nothing.

    double current_delay_ms(int voice) const {
        return (voice >= 0 && voice < kMaxVoices) ? delay_ms_[static_cast<std::size_t>(voice)] : 0.0;
    }
 
    int voice_count() const { return voices_; }

    double bbd_bandwidth_hz() const { return bbd_color_ ? bbd_[0].bandwidth_hz() : 0.0; }

    double bbd_stage_delay_ms() const {
        return bbd_color_ ? bbd_delay_samples_ * 1000.0 / sample_rate_ : 0.0;
    }

    static constexpr double kTapL1 = 1.25;

    double worst_case_gain() const {
        switch (voicing_) {
            case Voicing::ce2:
            case Voicing::juno_ensemble:
                return 1.0 + kTapL1;
            case Voicing::dimension_d:
                return shelf_l1() + kTapL1 + width_ * kTapL1 * highpass_l1();
            case Voicing::tri_chorus:
                return 1.0 + kTapL1 + width_ * 0.5 * kTapL1;
        }
        return 1.0 + kTapL1;
    }

    double shelf_l1() const { return units::db_to_linear(kDimBoostDb); }

    double highpass_l1() const {
        const double t = std::tan(kPi * kDimCornerHz / sample_rate_);
        return 2.0 / (1.0 + t);
    }
 
private:
    static constexpr double kPi = 3.14159265358979323846;

    static constexpr double kRateMinHz = 0.05;
    static constexpr double kRateMaxHz = 10.0;

    static double read_lagrange(const DelayLineT<SampleType>& line, double delay_samples) {
        const int i = static_cast<int>(std::floor(delay_samples));
        const double frac = delay_samples - static_cast<double>(i);
        const double ym1 = static_cast<double>(line.read(i - 1));
        const double y0 = static_cast<double>(line.read(i));
        const double y1 = static_cast<double>(line.read(i + 1));
        const double y2 = static_cast<double>(line.read(i + 2));
        return Interpolator::lagrange(frac, ym1, y0, y1, y2);
    }

    double modulation(std::size_t index) {
        if (juno_dual_) {
            // Both LFOs engage simultaneously — the real unit's two mode
            // switches are not exclusive. The averaging-and-clamp law is a
            // [design parameter]: the analog mixer's summing headroom is not
            // published. The clamp is provably inactive for two bipolar
            // triangles (|0.5(a + b)| ≤ 1) and is kept as the belt-and-braces
            // the spec states, not as an active shaper.
            const double a = lfo_a_[index].next();
            const double b = lfo_b_[index].next();
            return std::clamp(0.5 * (a + b), -1.0, 1.0);
        }
        const double a = lfo_a_[index].next();
        if (!trapezoid_) return a;
        // Dwells at the modulation extremes instead of reversing sharply,
        // which is what lets the Dimension D's excursion be shallow enough to
        // read as width rather than as pitch modulation.
        return std::clamp(kTrapK * a, -1.0, 1.0);
    }
 
    void configure_voicing() {
        const Calibration cal = calibration(voicing_);
        const bool juno = voicing_ == Voicing::juno_ensemble;
        const JunoModeSpec juno_cal = juno_spec(juno_mode_);
 
        voices_ = cal.voices;
        trapezoid_ = cal.trapezoid;
        juno_dual_ = juno && juno_cal.dual;
        rate_hz_ = juno ? juno_cal.rate_a_hz : cal.rate_hz;
 
        // Voice → delay line. Mono-source voicings read one line; the
        // inverted-phase pairs read their own channel.
        for (std::size_t k = 0; k < kVoiceSlots; ++k)
            voice_line_[k] = (cal.mono_source || k == 0) ? 0 : 1;
 
        for (std::size_t k = 0; k < kVoiceSlots; ++k) {
            // Voice k of N sits at k/N cycles — the toolkit's N-voice spacing,
            // which for N = 2 is the exact inversion the Juno and Dimension D
            // are built on and for N = 3 is the TriChorus's 120°.
            const double offset = static_cast<double>(k) / static_cast<double>(voices_);
            lfo_a_[k].set_wave(cal.wave);
            lfo_a_[k].set_phase_offset(offset);
            lfo_b_[k].set_wave(cal.wave);
            lfo_b_[k].set_phase_offset(offset);
            lfo_a_[k].reset();
            lfo_b_[k].reset();
        }
        apply_rates();
        update_bbd_stage();
    }
 
    void apply_rates() {
        const bool juno = voicing_ == Voicing::juno_ensemble;
        const JunoModeSpec juno_cal = juno_spec(juno_mode_);
        const double rate_a = juno ? juno_cal.rate_a_hz : rate_hz_;
        const double rate_b = juno ? juno_cal.rate_b_hz : rate_hz_;
        for (std::size_t k = 0; k < kVoiceSlots; ++k) {
            lfo_a_[k].set_rate_hz(rate_a);
            lfo_b_[k].set_rate_hz(rate_b);
        }
    }
 
    void update_bbd_stage() {
        if (!prepared_) return;
        const Calibration cal = calibration(voicing_);
        const bool juno = voicing_ == Voicing::juno_ensemble;
        const JunoModeSpec juno_cal = juno_spec(juno_mode_);
        const double center_ms = juno ? juno_cal.center_ms : cal.center_ms;
        const double depth_ms = juno ? juno_cal.depth_ms : cal.depth_ms;
 
        const double stage_ms = std::max(center_ms - depth_ms - kBbdColorGuardMs, 0.05);
        bbd_delay_samples_ = stage_ms * sample_rate_ * 0.001;
        for (std::size_t k = 0; k < kVoiceSlots; ++k)
            bbd_[k].update(kBbdColorCharacter, stage_ms * 0.001);
    }
 
    std::array<DelayLineT<SampleType>, 2> lines_{};
    std::array<EffectLfoT<double>, kVoiceSlots> lfo_a_{};
    std::array<EffectLfoT<double>, kVoiceSlots> lfo_b_{};
    std::array<chardelay::BbdChannel, kVoiceSlots> bbd_{};
    std::array<TptFilterT<double>, 2> shelf_lowpass_{};
    std::array<TptFilterT<double>, 2> cross_highpass_{};
 
    std::array<double, kVoiceSlots> delay_ms_{};
    std::array<std::size_t, kVoiceSlots> voice_line_{};
 
    double sample_rate_ = 48000.0;
    double max_read_samples_ = 0.0;
    double bbd_delay_samples_ = 0.0;
    double rate_hz_ = 1.2;
    double depth_ = 0.5;
    double mix_ = 0.5;
    double width_ = 1.0;
 
    Voicing voicing_ = Voicing::ce2;
    JunoMode juno_mode_ = JunoMode::mode_I;
    int voices_ = 1;
    bool trapezoid_ = false;
    bool juno_dual_ = false;
    bool bbd_color_ = false;
    bool prepared_ = false;
};
 
using ChorusEnsemble = ChorusEnsembleT<float>;
using ChorusEnsemble64 = ChorusEnsembleT<double>;
 
}  // namespace pulp::signal