plate_reverb.hpp

Go to the documentation of this file.

// sbl/dsp/modules/plate_reverb.hpp — Scalable Dattorro reverb (Audio Stack — Modules)
//
// Classic Dattorro plate topology, templated on a scale factor:
//   Input → Pre-delay → Bandwidth LP → 4x Input Diffusion (allpass)
//   → Cross-fed Tank (2 halves, each: AP → long delay → damp → AP → long delay)
//   → Multi-tap stereo output
//
// Based on Jon Dattorro, "Effect Design Part 1" (JAES, 1997).
//
// ScalePercent controls the acoustic space size. All delay lengths and output
// tap positions are multiplied by ScalePercent/100, preserving the Dattorro
// geometry (echo density pattern) while changing the perceived room size:
//   - PlateReverb  = AlgoReverb<100>  (~161 KB, tight plate character)
//
// Base delay values are scaled from Dattorro's 29.76 kHz reference rate to
// 48 kHz (factor 50/31), then further scaled by ScalePercent.
//
// Tank modulation uses a 4-phase quadrature oscillator (zero-cost, no LUT)
// to modulate all 4 tank delay lines with 90° offsets. Modulation depth
// scales with tank size to keep comb teeth dispersed at all scales.
//
// Parameter smoothing: All parameters are smoothed per-sample via
// ParameterSmoother IIR with category-appropriate settling times (structural
// 50ms, timbral 20ms, gain 15ms) to prevent pops/clicks from abrupt
// parameter changes. Predelay uses ModulatedDelayLine for interpolated
// read-position gliding.
//
// Float-domain processing — STM32H7 (Cortex-M7) has hardware FPU.
//
// Usage:
//   // Plate (original 1x size)
//   float pool[PlateReverb::BUFFER_SIZE] = {};
//   PlateReverb reverb;
//   reverb.init(pool, PlateReverb::BUFFER_SIZE);
//
//   // Hall (3x larger tank — place in SDRAM)
 
#ifndef SBL_DSP_MODULES_PLATE_REVERB_HPP_
#define SBL_DSP_MODULES_PLATE_REVERB_HPP_
 
#include <cmath>
#include <cstdint>
#include <cstring>
 
#include <sbl/dsp/primitives/allpass_filter.hpp>
#include <sbl/dsp/math/fast_math.hpp>
#include <sbl/dsp/primitives/delay_line.hpp>
#include <sbl/dsp/primitives/one_pole.hpp>
#include <sbl/dsp/primitives/parameter_smoother.hpp>
#include <sbl/dsp/types/fixed.hpp>
#include <sbl/dsp/math/constants.hpp>
 
namespace sbl::dsp::modules {
 
// ============================================================================
// Base Dattorro delay values at 48 kHz (scaled from 29.76 kHz reference)
// Scale factor: 48000 / 29760 = 50/31 ≈ 1.6129
// ============================================================================
 
namespace reverb {
 
// Input diffusion allpass delays (scaled from 142, 107, 379, 277)
constexpr uint32_t BASE_INPUT_AP1 = 229;
constexpr uint32_t BASE_INPUT_AP2 = 173;
constexpr uint32_t BASE_INPUT_AP3 = 611;
constexpr uint32_t BASE_INPUT_AP4 = 447;
 
// Tank left: AP1 → Delay1 → (damp) → AP2 → Delay2
// Scaled from 672, 4453, 1800, 3720.
constexpr uint32_t BASE_TANK_L_AP1    = 1084;
constexpr uint32_t BASE_TANK_L_DELAY1 = 7182;
constexpr uint32_t BASE_TANK_L_AP2    = 2903;
constexpr uint32_t BASE_TANK_L_DELAY2 = 6000;
 
// Tank right: AP1 → Delay1 → (damp) → AP2 → Delay2
// Scaled from 908, 4217, 2656, 3163.
constexpr uint32_t BASE_TANK_R_AP1    = 1465;
constexpr uint32_t BASE_TANK_R_DELAY1 = 6802;
constexpr uint32_t BASE_TANK_R_AP2    = 4284;
constexpr uint32_t BASE_TANK_R_DELAY2 = 5102;
 
// Pre-delay (max 100ms @ 48kHz at 1x scale)
constexpr uint32_t BASE_PREDELAY_MAX = 4800;
 
// LFO modulation parameters (base values at 1x scale)
constexpr float BASE_MOD_RATE_HZ = 1.5f;
constexpr float BASE_MOD_DEPTH   = 16.0f;
 
// Output tap positions (scaled from 29.76 kHz to 48 kHz)
constexpr uint32_t BASE_TAP_L_AP1_A = 429;
constexpr uint32_t BASE_TAP_L_DL1_A = 569;
constexpr uint32_t BASE_TAP_L_DL1_B = 5850;
constexpr uint32_t BASE_TAP_L_AP2_A = 2161;
constexpr uint32_t BASE_TAP_L_DL2_A = 2258;
constexpr uint32_t BASE_TAP_L_DL2_B = 4302;
 
constexpr uint32_t BASE_TAP_R_AP1_A = 429;
constexpr uint32_t BASE_TAP_R_DL1_A = 569;
constexpr uint32_t BASE_TAP_R_DL1_B = 5592;
constexpr uint32_t BASE_TAP_R_AP2_A = 1129;
constexpr uint32_t BASE_TAP_R_DL2_A = 1981;
constexpr uint32_t BASE_TAP_R_DL2_B = 4105;
 
// Input diffusion feedback coefficients (Dattorro standard)
constexpr float INPUT_DIFFUSION1 = 0.75f;   // AP1, AP2
constexpr float INPUT_DIFFUSION2 = 0.625f;  // AP3, AP4
 
// Tank diffusion — first AP is fixed, second AP tracks decay
constexpr float DECAY_DIFFUSION1 = 0.7f;
 
// Decay diffusion 2: dd2 = BASE * (1 - SCALE * decay)
// Range: 0.5 (zero decay) → ~0.2 (full decay). From Dattorro (1997).
constexpr float DECAY_DIFFUSION2_BASE  = 0.5f;
constexpr float DECAY_DIFFUSION2_SCALE = 0.6f;
 
// Input bandwidth LP frequency (Dattorro "bandwidth" parameter)
// Lower = warmer/darker reverb, higher = brighter/more transparent
constexpr float DEFAULT_BANDWIDTH_HZ = 10000.0f;
 
// Multi-tap output scaling: 7 taps sum to ~10x amplitude at unity decay.
// Normalizes the mix bus to approximately [-1, 1].
constexpr float TAP_SUM_SCALE = 0.10f;
 
} // namespace reverb
 
// Forward declaration for friend access
struct AlgoReverbTestAccess;
 
// ============================================================================
// AlgoReverb<ScalePercent> — Dattorro reverb with configurable space size
// ============================================================================
 
template<uint32_t ScalePercent = 100>
class AlgoReverb {
    // Scale a base delay value by the configured percentage
    static constexpr uint32_t S(uint32_t base) {
        return base * ScalePercent / 100;
    }
 
    // Modulation depth scales with tank size
    static constexpr float MOD_DEPTH =
        reverb::BASE_MOD_DEPTH * static_cast<float>(ScalePercent) / 100.0f;
    static constexpr uint32_t MOD_MARGIN =
        static_cast<uint32_t>(MOD_DEPTH) + 2;
 
    // Scaled delay values (compile-time constants)
    static constexpr uint32_t INPUT_AP1 = S(reverb::BASE_INPUT_AP1);
    static constexpr uint32_t INPUT_AP2 = S(reverb::BASE_INPUT_AP2);
    static constexpr uint32_t INPUT_AP3 = S(reverb::BASE_INPUT_AP3);
    static constexpr uint32_t INPUT_AP4 = S(reverb::BASE_INPUT_AP4);
 
    static constexpr uint32_t TANK_L_AP1    = S(reverb::BASE_TANK_L_AP1);
    static constexpr uint32_t TANK_L_DELAY1 = S(reverb::BASE_TANK_L_DELAY1);
    static constexpr uint32_t TANK_L_AP2    = S(reverb::BASE_TANK_L_AP2);
    static constexpr uint32_t TANK_L_DELAY2 = S(reverb::BASE_TANK_L_DELAY2);
 
    static constexpr uint32_t TANK_R_AP1    = S(reverb::BASE_TANK_R_AP1);
    static constexpr uint32_t TANK_R_DELAY1 = S(reverb::BASE_TANK_R_DELAY1);
    static constexpr uint32_t TANK_R_AP2    = S(reverb::BASE_TANK_R_AP2);
    static constexpr uint32_t TANK_R_DELAY2 = S(reverb::BASE_TANK_R_DELAY2);
 
    static constexpr uint32_t PREDELAY_MAX = S(reverb::BASE_PREDELAY_MAX);
 
    // Scaled output tap positions
    static constexpr uint32_t TAP_L_AP1_A = S(reverb::BASE_TAP_L_AP1_A);
    static constexpr uint32_t TAP_L_DL1_A = S(reverb::BASE_TAP_L_DL1_A);
    static constexpr uint32_t TAP_L_DL1_B = S(reverb::BASE_TAP_L_DL1_B);
    static constexpr uint32_t TAP_L_AP2_A = S(reverb::BASE_TAP_L_AP2_A);
    static constexpr uint32_t TAP_L_DL2_A = S(reverb::BASE_TAP_L_DL2_A);
    static constexpr uint32_t TAP_L_DL2_B = S(reverb::BASE_TAP_L_DL2_B);
 
    static constexpr uint32_t TAP_R_AP1_A = S(reverb::BASE_TAP_R_AP1_A);
    static constexpr uint32_t TAP_R_DL1_A = S(reverb::BASE_TAP_R_DL1_A);
    static constexpr uint32_t TAP_R_DL1_B = S(reverb::BASE_TAP_R_DL1_B);
    static constexpr uint32_t TAP_R_AP2_A = S(reverb::BASE_TAP_R_AP2_A);
    static constexpr uint32_t TAP_R_DL2_A = S(reverb::BASE_TAP_R_DL2_A);
    static constexpr uint32_t TAP_R_DL2_B = S(reverb::BASE_TAP_R_DL2_B);
 
    // Signal-unit parameter ranges
    static constexpr float kMaxDecay = 0.99f;
    static constexpr float kMinBandwidthHz = 100.0f;
    static constexpr float kMaxBandwidthHz = 20000.0f;
    static constexpr float kBandwidthOctaves = 7.644f;  // log2(20000/100)
    static constexpr float kMaxTankHpHz = 500.0f;
    static constexpr float kMinTankHpFilterHz = 1.0f;  // OnePoleHP range min
    static constexpr float kMaxDiffusion1 = 0.95f;
    static constexpr float kMaxDiffusion2 = 0.95f * reverb::INPUT_DIFFUSION2
                                          / reverb::INPUT_DIFFUSION1;  // ≈ 0.7917
    static constexpr float kMinOutputScale = 0.001f;
 
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /// Total float buffer size required for init()
    static constexpr uint32_t BUFFER_SIZE =
        INPUT_AP1 + INPUT_AP2 + INPUT_AP3 + INPUT_AP4 +
        TANK_L_AP1 + (TANK_L_DELAY1 + MOD_MARGIN) +
        TANK_L_AP2 + (TANK_L_DELAY2 + MOD_MARGIN) +
        TANK_R_AP1 + (TANK_R_DELAY1 + MOD_MARGIN) +
        TANK_R_AP2 + (TANK_R_DELAY2 + MOD_MARGIN) +
        PREDELAY_MAX;
 
    AlgoReverb() = default;
 
    /**
     * @brief Initialize with a pre-allocated float buffer pool
     * @param pool Float buffer pool (must outlive the reverb)
     * @param pool_size Pool size in floats (must be >= BUFFER_SIZE)
     */
    void init(float* pool, uint32_t pool_size) {
        if (pool_size < BUFFER_SIZE) return;
 
        // Zero the pool — NOLOAD sections may contain garbage from previous firmware
        memset(pool, 0, pool_size * sizeof(float));
 
        float* p = pool;
 
        predelay_.init(p, PREDELAY_MAX);  p += PREDELAY_MAX;
 
        input_ap_[0].init(p, INPUT_AP1);  p += INPUT_AP1;
        input_ap_[1].init(p, INPUT_AP2);  p += INPUT_AP2;
        input_ap_[2].init(p, INPUT_AP3);  p += INPUT_AP3;
        input_ap_[3].init(p, INPUT_AP4);  p += INPUT_AP4;
 
        input_ap_[0].set_feedback(reverb::INPUT_DIFFUSION1);
        input_ap_[1].set_feedback(reverb::INPUT_DIFFUSION1);
        input_ap_[2].set_feedback(reverb::INPUT_DIFFUSION2);
        input_ap_[3].set_feedback(reverb::INPUT_DIFFUSION2);
 
        tank_l_ap1_buf_ = p;
        tank_l_ap1_.init(p, TANK_L_AP1);   p += TANK_L_AP1;
        tank_l_dl1_buf_ = p;
        tank_l_dl1_.init(p, TANK_L_DELAY1 + MOD_MARGIN);
        p += TANK_L_DELAY1 + MOD_MARGIN;
        tank_l_ap2_buf_ = p;
        tank_l_ap2_.init(p, TANK_L_AP2);   p += TANK_L_AP2;
        tank_l_dl2_buf_ = p;
        tank_l_dl2_.init(p, TANK_L_DELAY2 + MOD_MARGIN);
        p += TANK_L_DELAY2 + MOD_MARGIN;
 
        tank_l_ap1_.set_feedback(reverb::DECAY_DIFFUSION1);
 
        tank_r_ap1_buf_ = p;
        tank_r_ap1_.init(p, TANK_R_AP1);   p += TANK_R_AP1;
        tank_r_dl1_buf_ = p;
        tank_r_dl1_.init(p, TANK_R_DELAY1 + MOD_MARGIN);
        p += TANK_R_DELAY1 + MOD_MARGIN;
        tank_r_ap2_buf_ = p;
        tank_r_ap2_.init(p, TANK_R_AP2);   p += TANK_R_AP2;
        tank_r_dl2_buf_ = p;
        tank_r_dl2_.init(p, TANK_R_DELAY2 + MOD_MARGIN);
        p += TANK_R_DELAY2 + MOD_MARGIN;
 
        tank_r_ap1_.set_feedback(reverb::DECAY_DIFFUSION1);
 
        pool_ = pool;
        pool_size_ = pool_size;
 
        reset();
    }
 
    // =====================================================================
    // Signal-unit inputs (_su API)
    // =====================================================================
 
    /// Set decay [0,1] → [0, 0.99] linear (structural, 50ms settling)
    void set_decay_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        decay_ = su * kMaxDecay;
    }
 
    /// Set damping [0,1] → [0, 1.0] linear (structural, 50ms settling)
    void set_damping_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        damping_ = su;
    }
 
    /// Set pre-delay [0,1] → [0, max] samples linear (structural, 50ms settling)
    void set_predelay_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        target_predelay_ = su * static_cast<float>(PREDELAY_MAX - 1);
    }
 
    /// Set stereo width [0,1] → [0, 1.0] linear (timbral, 20ms settling)
    void set_width_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        width_ = su;
    }
 
    /// Set wet/dry mix [0,1] → [0, 1.0] linear (gain, 15ms settling)
    void set_mix_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        mix_ = su;
    }
 
    /// Set input bandwidth LP [0,1] → [100, 20000] Hz exponential (structural, 50ms)
    /// Exponential mapping is handled by OnePole::set_cutoff_su() using the
    /// configured range.
    void set_bandwidth_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        bandwidth_su_ = su;
    }
 
    /// Set tank HP cutoff [0,1] → [0, 500] Hz (structural, 50ms)
    /// su = 0 disables the HP filter. OnePoleHP maps [0,1] exponentially
    /// across the configured range.
    void set_tank_hp_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        tank_hp_su_ = su;
    }
 
    /// Set input diffusion [0,1] → d1=[0, 0.95], d2=[0, 0.79] (structural, 50ms)
    /// Preserves the Dattorro d2/d1 ratio (0.625/0.75) across the range.
    void set_input_diffusion_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        diffusion_d1_ = su * kMaxDiffusion1;
        diffusion_d2_ = su * kMaxDiffusion2;
    }
 
    /// Set output tap scale [0,1] → [0.001, 1.0] linear (gain, 15ms)
    void set_output_scale_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        output_scale_ = kMinOutputScale + su * (1.0f - kMinOutputScale);
    }
 
    // =====================================================================
    // Accessors
    // =====================================================================
 
    float decay() const { return decay_; }
    float damping() const { return damping_; }
    float mix() const { return mix_; }
    float width() const { return width_; }
 
    /// Maximum pre-delay in milliseconds for this scale
    float max_predelay_ms() const {
        return static_cast<float>(PREDELAY_MAX) * 1000.0f
             / types::SAMPLE_RATE_F;
    }
 
    /**
     * @brief Process a stereo block in-place (float)
     */
    void process(float* left, float* right, uint16_t frames) {
        // Auto-configure smoothers on first process() call
        if (!smoothers_configured_) configure_smoothers();
 
        for (uint16_t i = 0; i < frames; ++i) {
            // Per-sample parameter smoothing via OnePole
            float sd = op_decay_.process(decay_);
            float sdamp = op_damping_.process(damping_);
            float smix = op_mix_.process(mix_);
            float swidth = op_width_.process(width_);
            float spd = op_predelay_.process(target_predelay_);
            float soscale = op_output_scale_.process(output_scale_);
 
            // Smooth bandwidth _su and update input LP filter cutoff
            float sbw_su = op_bandwidth_su_.process(bandwidth_su_);
            bandwidth_.set_cutoff_su(sbw_su);
 
            // Smooth tank HP _su
            float sthp_su = op_tank_hp_su_.process(tank_hp_su_);
 
            // Smooth input diffusion and update allpass feedback
            float sd1 = op_diffusion_d1_.process(diffusion_d1_);
            float sd2 = op_diffusion_d2_.process(diffusion_d2_);
            input_ap_[0].set_feedback(sd1);
            input_ap_[1].set_feedback(sd1);
            input_ap_[2].set_feedback(sd2);
            input_ap_[3].set_feedback(sd2);
 
            // Decay diffusion: derive from smoothed decay (avoids discrete
            // allpass coefficient steps inside the recirculating tank)
            float dd2 = reverb::DECAY_DIFFUSION2_BASE
                       * (1.0f - reverb::DECAY_DIFFUSION2_SCALE * sd);
            tank_l_ap2_.set_feedback(dd2);
            tank_r_ap2_.set_feedback(dd2);
 
            // Damping: smooth coefficient update
            float damp_coeff = 1.0f - sdamp;
            tank_l_damp_.set_coefficient(damp_coeff);
            tank_r_damp_.set_coefficient(damp_coeff);
 
            const float wet = smix;
            const float dry = 1.0f - wet;
 
            float in_l = left[i];
            float in_r = right[i];
 
            float input = (in_l + in_r) * 0.5f;
 
            // === Pre-delay (via ModulatedDelayLine for smooth gliding) ===
            float predelayed;
            if (spd < 1.0f) {
                predelayed = input;
            } else {
                predelayed = predelay_.read(spd);
            }
            predelay_.write(input);
 
            // === Bandwidth limiter (Dattorro input LP) ===
            float limited = bandwidth_.process(predelayed);
 
            // === Input diffusion ===
            float diffused = limited;
            for (int ap = 0; ap < 4; ++ap) {
                diffused = input_ap_[ap].process(diffused);
            }
 
            // === Quadrature LFO tick (4-phase for all tank delays) ===
            mod_sin_ += mod_inc_ * mod_cos_;
            mod_cos_ -= mod_inc_ * mod_sin_;
            float mod_dl1_l =  mod_sin_ * MOD_DEPTH;  // 0°
            float mod_dl2_l =  mod_cos_ * MOD_DEPTH;  // 90°
            float mod_dl1_r = -mod_sin_ * MOD_DEPTH;  // 180°
            float mod_dl2_r = -mod_cos_ * MOD_DEPTH;  // 270°
 
            // === Tank processing (uses smoothed decay for gain) ===
            float fb_l = tank_r_out_;
            float fb_r = tank_l_out_;
            if (sthp_su > 0.0f) {
                tank_hp_l_.set_cutoff_su(sthp_su);
                tank_hp_r_.set_cutoff_su(sthp_su);
                fb_l = tank_hp_l_.process(fb_l);
                fb_r = tank_hp_r_.process(fb_r);
            }
            float tank_l_in = diffused + sd * fb_l;
            float tank_r_in = diffused + sd * fb_r;
 
            // --- Tank Left ---
            float tl = tank_l_ap1_.process(tank_l_in);
            float tl_dl1 = tank_l_dl1_.read_cubic(
                static_cast<float>(TANK_L_DELAY1) + mod_dl1_l);
            tank_l_dl1_.write(tl);
            tl = tank_l_ap2_.process(tank_l_damp_.process(tl_dl1) * sd);
            float tl_dl2 = tank_l_dl2_.read_cubic(
                static_cast<float>(TANK_L_DELAY2) + mod_dl2_l);
            tank_l_dl2_.write(tl);
            tank_l_out_ = tl_dl2;
 
            // --- Tank Right ---
            float tr = tank_r_ap1_.process(tank_r_in);
            float tr_dl1 = tank_r_dl1_.read_cubic(
                static_cast<float>(TANK_R_DELAY1) + mod_dl1_r);
            tank_r_dl1_.write(tr);
            tr = tank_r_ap2_.process(tank_r_damp_.process(tr_dl1) * sd);
            float tr_dl2 = tank_r_dl2_.read_cubic(
                static_cast<float>(TANK_R_DELAY2) + mod_dl2_r);
            tank_r_dl2_.write(tr);
            tank_r_out_ = tr_dl2;
 
            // === Multi-tap stereo output ===
            float out_l = tap_from(tank_r_ap1_buf_, TANK_R_AP1,
                                   tank_r_ap1_.write_pos(), TAP_R_AP1_A)
                        + tap_from(tank_r_dl1_buf_,
                                   TANK_R_DELAY1 + MOD_MARGIN,
                                   tank_r_dl1_.write_pos(), TAP_R_DL1_A)
                        - tap_from(tank_r_ap2_buf_, TANK_R_AP2,
                                   tank_r_ap2_.write_pos(), TAP_R_AP2_A)
                        + tap_from(tank_r_dl2_buf_,
                                   TANK_R_DELAY2 + MOD_MARGIN,
                                   tank_r_dl2_.write_pos(), TAP_R_DL2_A)
                        - tap_from(tank_l_dl1_buf_,
                                   TANK_L_DELAY1 + MOD_MARGIN,
                                   tank_l_dl1_.write_pos(), TAP_L_DL1_B)
                        - tap_from(tank_l_ap2_buf_, TANK_L_AP2,
                                   tank_l_ap2_.write_pos(), TAP_L_AP2_A)
                        - tap_from(tank_l_dl2_buf_,
                                   TANK_L_DELAY2 + MOD_MARGIN,
                                   tank_l_dl2_.write_pos(), TAP_L_DL2_B);
 
            float out_r = tap_from(tank_l_ap1_buf_, TANK_L_AP1,
                                   tank_l_ap1_.write_pos(), TAP_L_AP1_A)
                        + tap_from(tank_l_dl1_buf_,
                                   TANK_L_DELAY1 + MOD_MARGIN,
                                   tank_l_dl1_.write_pos(), TAP_L_DL1_B)
                        - tap_from(tank_l_ap2_buf_, TANK_L_AP2,
                                   tank_l_ap2_.write_pos(), TAP_L_AP2_A)
                        + tap_from(tank_l_dl2_buf_,
                                   TANK_L_DELAY2 + MOD_MARGIN,
                                   tank_l_dl2_.write_pos(), TAP_L_DL2_A)
                        - tap_from(tank_r_dl1_buf_,
                                   TANK_R_DELAY1 + MOD_MARGIN,
                                   tank_r_dl1_.write_pos(), TAP_R_DL1_B)
                        - tap_from(tank_r_ap2_buf_, TANK_R_AP2,
                                   tank_r_ap2_.write_pos(), TAP_R_AP2_A)
                        - tap_from(tank_r_dl2_buf_,
                                   TANK_R_DELAY2 + MOD_MARGIN,
                                   tank_r_dl2_.write_pos(), TAP_R_DL2_B);
 
            out_l *= soscale;
            out_r *= soscale;
 
            float mono = (out_l + out_r) * 0.5f;
            out_l = mono + swidth * (out_l - mono);
            out_r = mono + swidth * (out_r - mono);
 
            left[i]  = dry * in_l + wet * out_l;
            right[i] = dry * in_r + wet * out_r;
        }
    }
 
    void reset() {
        if (pool_) {
            for (uint32_t i = 0; i < pool_size_; ++i) pool_[i] = 0.0f;
        }
 
        for (int i = 0; i < 4; ++i) input_ap_[i].reset();
        tank_l_ap1_.reset();
        tank_l_ap2_.reset();
        tank_r_ap1_.reset();
        tank_r_ap2_.reset();
 
        tank_l_dl1_.reset();
        tank_l_dl2_.reset();
        tank_r_dl1_.reset();
        tank_r_dl2_.reset();
 
        predelay_.reset();
 
        tank_l_out_ = 0.0f;
        tank_r_out_ = 0.0f;
        tank_l_damp_.reset();
        tank_r_damp_.reset();
        bandwidth_.reset();
        tank_hp_l_.reset();
        tank_hp_r_.reset();
 
        mod_sin_ = 0.0f;
        mod_cos_ = 1.0f;
 
        // Reset parameter smoothers to current targets
        op_decay_.reset(decay_);
        op_damping_.reset(damping_);
        op_mix_.reset(mix_);
        op_width_.reset(width_);
        op_predelay_.reset(target_predelay_);
        op_bandwidth_su_.reset(bandwidth_su_);
        op_tank_hp_su_.reset(tank_hp_su_);
        op_diffusion_d1_.reset(diffusion_d1_);
        op_diffusion_d2_.reset(diffusion_d2_);
        op_output_scale_.reset(output_scale_);
    }
 
private:
    friend struct AlgoReverbTestAccess;
 
    // =====================================================================
    // Engineering-unit setters (private — use _su API or TestAccess)
    // =====================================================================
 
    void set_decay(float decay) {
        if (decay > 0.99f) decay = 0.99f;
        if (decay < 0.0f) decay = 0.0f;
        decay_ = decay;
        op_decay_.reset(decay_);
    }
 
    void set_damping(float damp) {
        if (damp > 1.0f) damp = 1.0f;
        if (damp < 0.0f) damp = 0.0f;
        damping_ = damp;
        op_damping_.reset(damping_);
    }
 
    void set_predelay(float ms) {
        float samples = ms * types::SAMPLE_RATE_F / 1000.0f;
        if (samples < 0.0f) samples = 0.0f;
        if (samples >= static_cast<float>(PREDELAY_MAX)) {
            samples = static_cast<float>(PREDELAY_MAX - 1);
        }
        target_predelay_ = samples;
        op_predelay_.reset(target_predelay_);
    }
 
    void set_width(float width) {
        if (width > 1.0f) width = 1.0f;
        if (width < 0.0f) width = 0.0f;
        width_ = width;
        op_width_.reset(width_);
    }
 
    void set_mix(float mix) {
        if (mix > 1.0f) mix = 1.0f;
        if (mix < 0.0f) mix = 0.0f;
        mix_ = mix;
        op_mix_.reset(mix_);
    }
 
    /**
     * @brief Set tank high-pass frequency to prevent bass buildup
     * @param freq_hz HP cutoff in Hz (0 = disabled, typical 60–80 Hz)
     */
    void set_tank_hp(float freq_hz) {
        // Convert Hz to _su via inverse exponential mapping
        float su = 0.0f;
        if (freq_hz > 0.0f) {
            su = log2f(freq_hz / kMinTankHpFilterHz)
               / log2f(kMaxTankHpHz / kMinTankHpFilterHz);
            if (su < 0.0f) su = 0.0f;
            if (su > 1.0f) su = 1.0f;
        }
        tank_hp_su_ = su;
        op_tank_hp_su_.reset(su);
        if (su > 0.0f) {
            tank_hp_l_.set_cutoff_su(su);
            tank_hp_r_.set_cutoff_su(su);
        }
    }
 
    /**
     * @brief Set input bandwidth LP frequency
     * @param freq_hz LP cutoff in Hz (default 10000). Lower = darker/warmer input.
     */
    void set_bandwidth(float freq_hz) {
        if (freq_hz < kMinBandwidthHz) freq_hz = kMinBandwidthHz;
        // Convert Hz to _su via inverse exponential mapping
        float su = log2f(freq_hz / kMinBandwidthHz) / kBandwidthOctaves;
        if (su > 1.0f) su = 1.0f;
        bandwidth_su_ = su;
        bandwidth_.set_cutoff_su(su);
        op_bandwidth_su_.reset(su);
    }
 
    /**
     * @brief Set input diffusion coefficients (allpass feedback gains)
     * @param d1 First pair (AP1, AP2) feedback [0, 1]. Default 0.75.
     * @param d2 Second pair (AP3, AP4) feedback [0, 1]. Default 0.625.
     */
    void set_input_diffusion(float d1, float d2) {
        if (d1 < 0.0f) d1 = 0.0f;
        if (d1 > 0.95f) d1 = 0.95f;
        if (d2 < 0.0f) d2 = 0.0f;
        if (d2 > 0.95f) d2 = 0.95f;
        diffusion_d1_ = d1;
        diffusion_d2_ = d2;
        input_ap_[0].set_feedback(d1);
        input_ap_[1].set_feedback(d1);
        input_ap_[2].set_feedback(d2);
        input_ap_[3].set_feedback(d2);
        op_diffusion_d1_.reset(d1);
        op_diffusion_d2_.reset(d2);
    }
 
    /**
     * @brief Set output tap scaling factor
     * @param scale Output multiplier (default 0.10). Higher = louder wet output.
     */
    void set_output_scale(float scale) {
        if (scale < 0.001f) scale = 0.001f;
        if (scale > 1.0f) scale = 1.0f;
        output_scale_ = scale;
        op_output_scale_.reset(scale);
    }
 
    // =====================================================================
    // Smoother configuration
    // =====================================================================
 
    void configure_smoothers() {
        float sr = types::SAMPLE_RATE_F;
        // LFO modulation increment
        mod_inc_ = math::TWO_PI * reverb::BASE_MOD_RATE_HZ / sr;
        // Configure bandwidth LP filter range
        bandwidth_.set_range(kMinBandwidthHz, kMaxBandwidthHz);
        bandwidth_.set_cutoff_su(bandwidth_su_);
        // Configure tank HP filter range
        tank_hp_l_.set_range(kMinTankHpFilterHz, kMaxTankHpHz);
        tank_hp_r_.set_range(kMinTankHpFilterHz, kMaxTankHpHz);
        // Structural params (50ms settling)
        op_decay_.set_time_ms(50.0f, sr);
        op_damping_.set_time_ms(50.0f, sr);
        op_predelay_.set_time_ms(50.0f, sr);
        op_bandwidth_su_.set_time_ms(50.0f, sr);
        op_tank_hp_su_.set_time_ms(50.0f, sr);
        op_diffusion_d1_.set_time_ms(50.0f, sr);
        op_diffusion_d2_.set_time_ms(50.0f, sr);
        // Timbral params (20ms settling)
        op_width_.set_time_ms(20.0f, sr);
        // Gain params (15ms settling)
        op_mix_.set_time_ms(15.0f, sr);
        op_output_scale_.set_time_ms(15.0f, sr);
        // Reset all to current targets
        op_decay_.reset(decay_);
        op_damping_.reset(damping_);
        op_mix_.reset(mix_);
        op_width_.reset(width_);
        op_predelay_.reset(target_predelay_);
        op_bandwidth_su_.reset(bandwidth_su_);
        op_tank_hp_su_.reset(tank_hp_su_);
        op_diffusion_d1_.reset(diffusion_d1_);
        op_diffusion_d2_.reset(diffusion_d2_);
        op_output_scale_.reset(output_scale_);
        smoothers_configured_ = true;
    }
 
    // =====================================================================
    // Private helpers
    // =====================================================================
 
    static float tap_from(const float* buf, uint32_t buf_size,
                          uint32_t write_pos, uint32_t tap_offset) {
        if (tap_offset >= buf_size) tap_offset = buf_size - 1;
        uint32_t pos = (write_pos >= tap_offset)
            ? write_pos - tap_offset
            : write_pos + buf_size - tap_offset;
        return buf[pos];
    }
 
    // =====================================================================
    // Member state
    // =====================================================================
 
    float* pool_ = nullptr;
    uint32_t pool_size_ = 0;
 
    float* tank_l_ap1_buf_ = nullptr;
    float* tank_l_dl1_buf_ = nullptr;
    float* tank_l_ap2_buf_ = nullptr;
    float* tank_l_dl2_buf_ = nullptr;
 
    float* tank_r_ap1_buf_ = nullptr;
    float* tank_r_dl1_buf_ = nullptr;
    float* tank_r_ap2_buf_ = nullptr;
    float* tank_r_dl2_buf_ = nullptr;
 
    primitives::AllpassFilter input_ap_[4];
    primitives::AllpassFilter tank_l_ap1_;
    primitives::AllpassFilter tank_l_ap2_;
    primitives::AllpassFilter tank_r_ap1_;
    primitives::AllpassFilter tank_r_ap2_;
 
    primitives::DelayLine tank_l_dl1_;
    primitives::DelayLine tank_l_dl2_;
    primitives::DelayLine tank_r_dl1_;
    primitives::DelayLine tank_r_dl2_;
 
    primitives::DelayLine predelay_;
 
    float tank_l_out_ = 0.0f;
    float tank_r_out_ = 0.0f;
 
    primitives::OnePole tank_l_damp_;
    primitives::OnePole tank_r_damp_;
    primitives::OnePole bandwidth_;
 
    primitives::OnePoleHP tank_hp_l_;
    primitives::OnePoleHP tank_hp_r_;
 
    float mod_sin_ = 0.0f;
    float mod_cos_ = 1.0f;
    float mod_inc_ = 0.0f;
 
    // Parameter targets
    float decay_ = 0.7f;
    float damping_ = 0.3f;
    float width_ = 1.0f;
    float mix_ = 0.3f;
    float output_scale_ = reverb::TAP_SUM_SCALE;
    float target_predelay_ = 0.0f;
    float bandwidth_su_ = 0.869f;     // [0,1] — default 10 kHz (Dattorro bandwidth)
    float tank_hp_su_ = 0.0f;         // [0,1] — 0 = disabled
    float diffusion_d1_ = reverb::INPUT_DIFFUSION1;
    float diffusion_d2_ = reverb::INPUT_DIFFUSION2;
 
    // Per-sample parameter smoothers (ParameterSmoother)
    primitives::ParameterSmoother op_decay_;
    primitives::ParameterSmoother op_damping_;
    primitives::ParameterSmoother op_mix_;
    primitives::ParameterSmoother op_width_;
    primitives::ParameterSmoother op_predelay_;
    primitives::ParameterSmoother op_bandwidth_su_;
    primitives::ParameterSmoother op_tank_hp_su_;
    primitives::ParameterSmoother op_diffusion_d1_;
    primitives::ParameterSmoother op_diffusion_d2_;
    primitives::ParameterSmoother op_output_scale_;
    bool smoothers_configured_ = false;
};
 
// Convenient type aliases
using PlateReverb = AlgoReverb<100>;   // ~161 KB — original plate
 
} // namespace sbl::dsp::modules
 
#endif // SBL_DSP_MODULES_PLATE_REVERB_HPP_