tape_delay.hpp

Go to the documentation of this file.

// sbl/dsp/modules/tape_delay.hpp — Stereo tape echo (Audio Stack — Modules)
//
// Opinionated tape delay with Roland Space Echo / Echoplex character.
// Models tape transport phenomena: head gap loss, magnetic saturation,
// wow/flutter, speed drift, and tape hiss — all composed from existing
// SBL atoms (ModulatedDelayLine, OnePole, ParameterSmoother, WarmSaturator,
// SlewLimiter, AnalogDrift, Rng).
//
// Wet-only output — designed for send/return bus architecture.
// Caller handles dry/wet balance via send level.
//
// Float-domain processing — STM32H7 (Cortex-M7) has hardware FPU with
// single-cycle float ops.
//
// Signal Unit API (FDP-052):
//   Widgets expose normalized [0,1] inputs via _su() methods. The widget
//   owns internal mapping and parameter conditioning. TapeDelay already
//   owned most of its smoothing (motor slew, TIME_SMOOTH, per-sample
//   ramps). The _su API adds feedback smoothing (OnePole 50ms) and
//   formalizes the input contract.
//
// Usage (new — signal units):
//   sbl::dsp::modules::TapeDelay delay;
//   delay.init(buf_l, buf_r, 48000);
//   delay.set_time_su(0.3f);            // [0,1] → 0–max samples (motor slew)
//   delay.set_feedback_su(0.5f);        // [0,1] → 0–1.15 (OnePole 50ms)
//   delay.set_tone_su(0.6f);            // [0,1] → 200–20000 Hz (exp)
//   delay.process(left, right, frames); // wet-only output
//   delay.tick();                        // call at ~200 Hz
//
// See: FDP-042, FDP-048, FDP-052
 
#ifndef SBL_DSP_MODULES_TAPE_DELAY_HPP_
#define SBL_DSP_MODULES_TAPE_DELAY_HPP_
 
#include <cmath>
#include <cstdint>
 
#include <sbl/dsp/comp/analog_drift.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/primitives/phase_accumulator.hpp>
#include <sbl/dsp/primitives/rng.hpp>
#include <sbl/dsp/math/fast_math.hpp>
#include <sbl/dsp/comp/warm_saturator.hpp>
#include <sbl/dsp/primitives/dc_blocker.hpp>
#include <sbl/dsp/primitives/slew_limiter.hpp>
#include <sbl/dsp/primitives/soft_limiter.hpp>
#include <sbl/dsp/tables/sin_256.hpp>
#include <sbl/dsp/tables/triangle_256.hpp>
#include <sbl/dsp/primitives/wavetable_reader.hpp>
#include <sbl/dsp/types/fixed.hpp>
 
namespace sbl::dsp::modules {
 
/// Musical note subdivisions for tempo-synced delay
enum class Subdivision : uint8_t {
    Whole,           // 4 beats
    HalfDotted,      // 3 beats
    Half,            // 2 beats
    QuarterDotted,   // 1.5 beats
    QuarterTriplet,  // 1.333 beats
    Quarter,         // 1 beat
    EighthDotted,    // 0.75 beats
    EighthTriplet,   // 0.667 beats
    Eighth,          // 0.5 beats
    SixteenthDotted, // 0.375 beats
    Sixteenth,       // 0.25 beats
};
 
class TapeDelay {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    // === Parameter range constants (for test helpers) ===
    static constexpr float kMinFeedback = 0.0f;
    static constexpr float kMaxFeedback = 1.15f;
    static constexpr uint32_t kModHeadroom = 128;  // ~2.7ms at 48kHz
    static constexpr float kMinToneHz = 200.0f;
    static constexpr float kMaxToneHz = 20000.0f;
    static constexpr float kMinBassLossHz = 0.0f;      // 0 = disabled
    static constexpr float kMaxBassLossHz = 500.0f;
    static constexpr float kMinBassLossFilterHz = 1.0f;  // OnePoleHP range min
    static constexpr float kMinDrive = 1.0f;
    static constexpr float kMaxDrive = 3.0f;
    static constexpr float kMaxWobble = 2.0f;
    static constexpr float kMaxHiss = 1.0f;
    static constexpr float kMaxDrift = 3.0f;
    static constexpr float kMinTransportSpeed = 1.0f;
    static constexpr float kMaxTransportSpeed = 20.0f;
 
    TapeDelay() = default;
 
    /**
     * @brief Initialize with pre-allocated stereo delay buffers
     * @param buf_l Left delay buffer (must outlive the Delay)
     * @param buf_r Right delay buffer (must outlive the Delay)
     * @param max_samples Maximum delay in samples (buffer size)
     */
    void init(float* buf_l, float* buf_r, uint32_t max_samples) {
        dl_l_.init(buf_l, max_samples);
        dl_r_.init(buf_r, max_samples);
        configure_rate_dependent();
    }
 
    // === Signal Unit API (FDP-052) ===
 
    /**
     * @brief Set delay time from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 0–max_samples
     *
     * Feeds into the existing motor slew model. No additional smoothing.
     */
    void set_time_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        uint32_t max = dl_l_.max_delay();
        if (max <= kModHeadroom) max = kModHeadroom + 1;
        uint32_t usable = max - kModHeadroom;
        set_time(static_cast<uint32_t>(su * static_cast<float>(usable)));
    }
 
    /**
     * @brief Tempo-synced delay time (internally slewed)
     * @param bpm Tempo in beats per minute
     * @param div Musical subdivision
     *
     * Public because tempo sync requires structured input (BPM + subdivision),
     * not a normalized signal.
     */
    void set_time_bpm(float bpm, Subdivision div) {
        if (bpm < 1.0f) bpm = 1.0f;
        float seconds = (60.0f / bpm) * subdivision_beats(div);
        set_time(static_cast<uint32_t>(seconds * types::SAMPLE_RATE_F));
    }
 
    /**
     * @brief Set feedback from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 0–1.15 (FDP-060)
     *
     * Linear mapping. For musical response curves (more resolution at the
     * top of the range), apply a cam profile in the control stack before
     * this port. Smoothed via OnePole (50ms structural settling), then
     * per-sample linear ramp across the block.
     */
    void set_feedback_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        // Linear mapping — response curve shaping belongs in the control
        // stack (cam profile), not inside the widget (FDP-060).
        float fb = su * kMaxFeedback;
        feedback_ = fb;
        ensure_fb_smoother();
        if (!fb_init_) {
            op_feedback_.reset(fb);
            fb_init_ = true;
        }
    }
 
    /**
     * @brief Set tone (head gap loss LP) from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — exponentially mapped to 200–20000 Hz
     *
     * 0 = dark (200 Hz LP), 1 = bright (20000 Hz, near-passthrough).
     * Exponential mapping is handled by OnePole::set_cutoff_su() using
     * the configured range.
     */
    void set_tone_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        tone_su_ = su;
    }
 
    /**
     * @brief Set bass loss (feedback HP) from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 0–500 Hz
     *
     * 0 = disabled (no HP), 1 = maximum bass removal (500 Hz).
     * OnePoleHP maps [0,1] exponentially across its configured range.
     */
    void set_bass_loss_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        hp_su_ = su;
    }
 
    /**
     * @brief Set drive (magnetic saturation) from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 1.0–3.0
     */
    void set_drive_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        drive_ = kMinDrive + su * (kMaxDrive - kMinDrive);
    }
 
    /**
     * @brief Set wow+flutter from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 0–2.0
     */
    void set_wobble_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        set_wobble(su * kMaxWobble);
    }
 
    /**
     * @brief Set tape hiss from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 0–1.0
     */
    void set_hiss_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        set_hiss(su * kMaxHiss);
    }
 
    /**
     * @brief Set speed drift from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 0–3.0
     */
    void set_drift_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        set_drift(su * kMaxDrift);
    }
 
    /**
     * @brief Set transport speed (motor inertia) from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 1.0–20.0
     */
    void set_transport_speed_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        set_transport_speed(kMinTransportSpeed + su * (kMaxTransportSpeed - kMinTransportSpeed));
    }
 
    /** @brief Enable stereo ping-pong (alternating L/R repeats). Default: false. */
    void set_ping_pong(bool enable) { ping_pong_ = enable; }
 
    // ─── Accessors ───────────────────────────────────────────────
 
    uint32_t time() const { return static_cast<uint32_t>(target_time_); }
    float feedback() const { return feedback_; }
    bool ping_pong() const { return ping_pong_; }
 
    // ─── Processing ──────────────────────────────────────────────
 
    /**
     * @brief Process a stereo block in-place (wet-only output)
     *
     * Input: dry signal from send bus.
     * Output: wet delay signal (replaces input in-place).
     * Caller mixes into return bus.
     */
    void process(float* left, float* right, uint16_t frames) {
        if (!smoothing_initialized_) {
            smooth_feedback_ = feedback_;
            smooth_drive_ = drive_;
            block_drive_ = drive_;
            smooth_tone_su_ = tone_su_;
            smooth_hp_su_ = hp_su_;
            smooth_time_ = target_time_;
            smooth_wow_depth_ = wow_depth_;
            smooth_flutter_depth_ = flutter_depth_;
            smooth_hiss_level_ = hiss_level_;
            smooth_drift_amount_ = drift_amount_;
            op_feedback_.reset(feedback_);
            smoothing_initialized_ = true;
        }
        if (!time_initialized_) {
            time_slew_.reset(target_time_);
            time_initialized_ = true;
        }
 
        // Block-rate smoothing: eliminates CC zipper on all parameters.
        // Filter coefficients recalculated once per block (too expensive per-sample).
        // Time pre-filtered before motor slew — the staircase from TIME_SMOOTH
        // is gentler than raw target jumps, which produce harsher digital artifacts.
        // Character params use TIME_SMOOTH to settle at the same rate as time,
        // keeping all transport parameters synchronized during macro sweeps (FDP-048).
        smooth_time_ += TIME_SMOOTH * (target_time_ - smooth_time_);
 
        // Tape character — match time settling so macro sweeps are cohesive
        block_drive_ += TIME_SMOOTH * (drive_ - block_drive_);
        smooth_wow_depth_ += TIME_SMOOTH * (wow_depth_ - smooth_wow_depth_);
        smooth_flutter_depth_ += TIME_SMOOTH * (flutter_depth_ - smooth_flutter_depth_);
        smooth_hiss_level_ += TIME_SMOOTH * (hiss_level_ - smooth_hiss_level_);
        smooth_drift_amount_ += TIME_SMOOTH * (drift_amount_ - smooth_drift_amount_);
 
        smooth_tone_su_ += BLOCK_SMOOTH * (tone_su_ - smooth_tone_su_);
        tone_lp_l_.set_cutoff_su(smooth_tone_su_);
        tone_lp_r_.set_cutoff_su(smooth_tone_su_);
 
        if (hp_su_ > 0.0f) {
            smooth_hp_su_ += BLOCK_SMOOTH * (hp_su_ - smooth_hp_su_);
            feedback_hp_l_.set_cutoff_su(smooth_hp_su_);
            feedback_hp_r_.set_cutoff_su(smooth_hp_su_);
        }
 
        const bool hp = hp_su_ > 0.0f;
        const float hiss = smooth_hiss_level_;
 
        // Feedback: OnePole smoothing (50ms structural settling) absorbs
        // external smoother from Davis Jr. Per-sample linear ramp on top
        // eliminates block-edge steps entirely (FDP-048 Phase 4).
        float smoothed_fb = op_feedback_.process(feedback_);
 
        float prev_fb = smooth_feedback_;
        float prev_drv = smooth_drive_;
        smooth_feedback_ = smoothed_fb;
        smooth_drive_ = block_drive_;       // block-rate TIME_SMOOTH handles settling
 
        float fb_inc = (smooth_feedback_ - prev_fb) / static_cast<float>(frames);
        float drv_inc = (smooth_drive_ - prev_drv) / static_cast<float>(frames);
        float fb_val = prev_fb;
        float drv_val = prev_drv;
 
        for (uint16_t i = 0; i < frames; ++i) {
            // Capture dry input before overwriting
            float in_l = left[i];
            float in_r = right[i];
 
            // Per-sample linear ramp (replaces exponential PARAM_SMOOTH)
            fb_val += fb_inc;
            drv_val += drv_inc;
 
            // Distance-proportional motor acceleration: big jumps spool fast,
            // small adjustments arrive gently. Models motor torque proportional
            // to error signal — real servo behavior. Decelerates naturally as
            // distance shrinks. (FDP-048, FDP-060: reduced from 4.0 to 1.5
            // for heavier reel-to-reel feel)
            float motor_distance = smooth_time_ - time_slew_.value();
            if (motor_distance < 0.0f) motor_distance = -motor_distance;
            float accel = motor_distance * (1.0f / 4800.0f);  // normalize ~100ms
            float effective_rate = motor_slew_rate_ * (1.0f + accel * 1.0f);
            time_slew_.set_rate(effective_rate);
 
            // Time modulation: motor slew + wow + flutter + drift
            float slewed = time_slew_.process(smooth_time_);
 
            // Scale down wow/flutter during active motor slew to prevent muddy warble.
            // Drift is unscaled — it IS part of the motor behavior.
            float slew_delta = time_slew_.delta();
            float slew_scale = (slew_delta < 1.0f) ? 1.0f :
                               (slew_delta > 4800.0f) ? 0.5f :
                               1.0f - 0.5f * (slew_delta / 4800.0f);
 
            wow_phase_.advance();
            flutter_phase_.advance();
 
            float time_mod = wow_reader_.read(wow_phase_.phase()) * smooth_wow_depth_ * slew_scale
                           + flutter_reader_.read(flutter_phase_.phase()) * smooth_flutter_depth_ * slew_scale
                           + time_drift_.value() * smooth_drift_amount_;
 
            float read_pos = slewed + time_mod;
 
            // Read from delay lines (cubic Hermite interpolation)
            float wet_l = dl_l_.read_cubic(read_pos);
            float wet_r = dl_r_.read_cubic(read_pos);
 
            // Head gap loss (LP) — applied to everything read from "tape",
            // including the first repeat. Cumulative darkening per pass.
            wet_l = tone_lp_l_.process(wet_l);
            wet_r = tone_lp_r_.process(wet_r);
 
            // Output tap: this is what the listener hears
            left[i] = wet_l;
            right[i] = wet_r;
 
            // === Everything below is feedback-only (2nd repeat onward) ===
 
            // Bass loss (HP) — thin out the low end per repeat
            float fb_l = hp ? feedback_hp_l_.process(wet_l) : wet_l;
            float fb_r = hp ? feedback_hp_r_.process(wet_r) : wet_r;
 
            // Ping-pong: cross-feed channels (one transport, two heads)
            if (ping_pong_) {
                float tmp = fb_l;
                fb_l = fb_r;
                fb_r = tmp;
            }
 
            // Safety limiter — always-on (FDP-060). SoftLimiter provides
            // natural compression that enables safe self-oscillation at
            // feedback > 1.0. WarmSaturator (asymmetric harmonics) only
            // engages when drive > 1.0 — at drive=1.0 the harmonics
            // accumulate through feedback and produce noise artifacts.
            if (drv_val > 1.01f) {
                fb_l = saturator_.process(fb_l, drv_val);
                fb_r = saturator_.process(fb_r, drv_val);
            } else {
                fb_l = limiter_.process(fb_l);
                fb_r = limiter_.process(fb_r);
            }
 
            // DC blocker — catch offset from asymmetric saturation (FDP-060)
            fb_l = dc_l_.process(fb_l);
            fb_r = dc_r_.process(fb_r);
 
            // Tape hiss — pink noise injection (accumulates per pass)
            if (hiss > 0.0f) {
                float noise = hiss_pink_.process(hiss_rng_.bipolar()) * hiss;
                fb_l += noise;
                fb_r += noise;
            }
 
            // Feedback gain
            fb_l *= fb_val;
            fb_r *= fb_val;
 
            // Write input + feedback to delay line
            dl_l_.write(in_l + fb_l);
            dl_r_.write(in_r + fb_r);
        }
    }
 
    /**
     * @brief Tick control-rate modulation (~200 Hz)
     *
     * Advances AnalogDrift. Call from control loop, not audio callback.
     */
    void tick() {
        time_drift_.process(1.0f);
    }
 
    /** @brief Clear delay buffers and reset all internal state */
    void reset() {
        dl_l_.reset();
        dl_r_.reset();
        tone_lp_l_.reset();
        tone_lp_r_.reset();
        feedback_hp_l_.reset();
        feedback_hp_r_.reset();
        time_drift_.reset();
        wow_phase_.reset();
        flutter_phase_.reset();
        hiss_pink_.reset();
        dc_l_.reset();
        dc_r_.reset();
        block_drive_ = 0.0f;
        smooth_wow_depth_ = 0.0f;
        smooth_flutter_depth_ = 0.0f;
        smooth_hiss_level_ = 0.0f;
        smooth_drift_amount_ = 0.0f;
        time_initialized_ = false;
        smoothing_initialized_ = false;
        fb_init_ = false;
    }
 
private:
    // Test-only access to engineering-unit setters
    friend struct TapeDelayTestAccess;
 
    // ─── Engineering-unit setters (private — tests via TapeDelayTestAccess) ──
 
    /**
     * @brief Set delay time in samples (internally slewed — tape motor)
     * @param samples Delay length (clamped to max_samples - 1)
     */
    void set_time(uint32_t samples) {
        uint32_t max = dl_l_.max_delay();
        target_time_ = static_cast<float>((samples < max) ? samples : max - 1);
        if (!time_initialized_) {
            time_slew_.reset(target_time_);
            time_initialized_ = true;
        }
    }
 
    /** @brief Set delay time in milliseconds (internally slewed) */
    void set_time_ms(float ms) {
        set_time(static_cast<uint32_t>(ms * types::SAMPLE_RATE_F / 1000.0f));
    }
 
    /**
     * @brief Set feedback gain (0.0–1.15, clamped to kMaxFeedback)
     *
     * Immediate — no smoothing. For internal use and backward-compatible tests.
     */
    void set_feedback(float fb) {
        feedback_ = (fb > kMaxFeedback) ? kMaxFeedback : (fb < 0.0f ? 0.0f : fb);
        op_feedback_.reset(feedback_);
    }
 
    /**
     * @brief Head gap loss — LP cutoff in Hz
     */
    void set_tone(float freq_hz) {
        // Convert Hz to _su via inverse exponential mapping
        // su = log2(hz / min) / log2(max / min)
        float su = log2f(freq_hz / kMinToneHz) / log2f(kMaxToneHz / kMinToneHz);
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        tone_su_ = su;
    }
 
    /**
     * @brief Bass loss — HP cutoff in the feedback path
     */
    void set_bass_loss(float freq_hz) {
        // Convert Hz to _su via inverse exponential mapping
        float su = log2f(freq_hz / kMinBassLossFilterHz) / log2f(kMaxBassLossHz / kMinBassLossFilterHz);
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        hp_su_ = su;
    }
 
    /**
     * @brief Magnetic saturation drive in the feedback path
     */
    void set_drive(float drive) {
        drive_ = (drive < 1.0f) ? 1.0f : drive;
    }
 
    /**
     * @brief Wow + flutter — mechanical tape speed variation
     */
    void set_wobble(float amount) {
        wow_depth_ = amount * 3.0f;
        flutter_depth_ = amount * 2.0f;
    }
 
    /**
     * @brief Tape hiss — pink noise injection into feedback path
     */
    void set_hiss(float amount) {
        hiss_level_ = amount * 0.003f;
    }
 
    /**
     * @brief Speed drift — slow non-periodic delay time wander
     */
    void set_drift(float amount) {
        drift_amount_ = amount * 10.0f;
    }
 
    /**
     * @brief Transport inertia — how quickly the motor changes speed
     */
    void set_transport_speed(float samples_per_sample) {
        motor_slew_rate_ = (samples_per_sample < 0.5f) ? 0.5f : samples_per_sample;
        time_slew_.set_rate(motor_slew_rate_);
    }
 
    void ensure_fb_smoother() {
        if (!fb_smoother_configured_) {
            op_feedback_.set_time_ms(50.0f, 1000.0f);  // 50ms at ~1kHz block rate
            fb_smoother_configured_ = true;
        }
    }
 
    static constexpr float BLOCK_SMOOTH = 0.2f;   // per-block (~5 blocks settle)
    // Time needs a much slower smoother than other params because
    // any rate-of-change in read position = Doppler pitch shift.
    // At 0.02, a 200-sample CC step produces ~0.08 samples/audio-sample
    // of read position change — imperceptible pitch wobble.
    // Big jumps still trigger the motor slew naturally.
    static constexpr float TIME_SMOOTH = 0.02f;   // per-block (~50 blocks settle)
 
    // Motor slew rate: 5 samples/audio-sample.
    // A 1-second time change (48000 samples) slews over ~200ms.
    // Small CC steps (~200 samples) complete in <1ms (nearly instant).
    static constexpr float MOTOR_SLEW_RATE = 5.0f;
 
    void configure_rate_dependent() {
        float sr = types::SAMPLE_RATE_F;
        wow_reader_.set_table(lut::sin_256);
        flutter_reader_.set_table(lut::triangle_256);
        wow_phase_.set_increment(primitives::PhaseAccumulator::freq_to_inc(1.0f, sr));
        flutter_phase_.set_increment(primitives::PhaseAccumulator::freq_to_inc(6.0f, sr));
        time_slew_.set_rate(motor_slew_rate_);
        time_drift_.set_rate(200.0f);
        // Hiss pink noise coloring — fixed 3000 Hz LP, not signal-driven
        primitives::OnePoleTestAccess::set_frequency(hiss_pink_, 3000.0f);
        // Tape saturation character — mild asymmetric warmth
        saturator_.set_asymmetry(0.1f);
        // Tone LP: configure range, then drive via _su
        tone_lp_l_.set_range(kMinToneHz, kMaxToneHz);
        tone_lp_r_.set_range(kMinToneHz, kMaxToneHz);
        tone_lp_l_.set_cutoff_su(tone_su_);
        tone_lp_r_.set_cutoff_su(tone_su_);
        // Bass loss HP: configure range, then drive via _su
        feedback_hp_l_.set_range(kMinBassLossFilterHz, kMaxBassLossHz);
        feedback_hp_r_.set_range(kMinBassLossFilterHz, kMaxBassLossHz);
        if (hp_su_ > 0.0f) {
            feedback_hp_l_.set_cutoff_su(hp_su_);
            feedback_hp_r_.set_cutoff_su(hp_su_);
        }
        // Configure feedback smoother at ~1kHz block rate (50ms structural settling)
        op_feedback_.set_time_ms(50.0f, 1000.0f);
        op_feedback_.reset(feedback_);
        fb_smoother_configured_ = true;
    }
 
    static float subdivision_beats(Subdivision div) {
        switch (div) {
        case Subdivision::Whole:           return 4.0f;
        case Subdivision::HalfDotted:      return 3.0f;
        case Subdivision::Half:            return 2.0f;
        case Subdivision::QuarterDotted:   return 1.5f;
        case Subdivision::QuarterTriplet:  return 2.0f / 3.0f;
        case Subdivision::Quarter:         return 1.0f;
        case Subdivision::EighthDotted:    return 0.75f;
        case Subdivision::EighthTriplet:   return 1.0f / 3.0f;
        case Subdivision::Eighth:          return 0.5f;
        case Subdivision::SixteenthDotted: return 0.375f;
        case Subdivision::Sixteenth:       return 0.25f;
        default:                           return 1.0f;
        }
    }
 
    // ─── Per-channel state ───────────────────────────────────────
    primitives::DelayLine dl_l_;
    primitives::DelayLine dl_r_;
    primitives::OnePole tone_lp_l_;           // head gap loss (pre-output tap)
    primitives::OnePole tone_lp_r_;
    primitives::OnePoleHP feedback_hp_l_;     // bass loss (feedback-only)
    primitives::OnePoleHP feedback_hp_r_;
 
    // ─── Shared modulation (mono — one transport) ────────────────
    primitives::PhaseAccumulator wow_phase_;
    primitives::PhaseAccumulator flutter_phase_;
    primitives::WavetableReader<256> wow_reader_;
    primitives::WavetableReader<256> flutter_reader_;
    comp::AnalogDrift time_drift_{0xDEADCAFE};
    primitives::SlewLimiter time_slew_;
    primitives::Rng hiss_rng_{0xBEEFF00D};
    primitives::OnePole hiss_pink_;
    comp::WarmSaturator saturator_;
    primitives::SoftLimiter limiter_;       // safety-only (no asymmetric harmonics)
    primitives::DcBlocker dc_l_;
    primitives::DcBlocker dc_r_;
 
    // ─── Parameters ──────────────────────────────────────────────
    float feedback_ = 0.4f;
    float drive_ = 1.2f;
    float tone_su_ = 0.5f;           // [0,1] signal unit for tone LP
    float hp_su_ = 0.0f;             // [0,1] signal unit for bass loss HP (0 = disabled)
    float wow_depth_ = 0.0f;          // samples excursion (set by set_wobble)
    float flutter_depth_ = 0.0f;      // samples excursion (set by set_wobble)
    float hiss_level_ = 0.0f;         // linear amplitude (set by set_hiss)
    float drift_amount_ = 0.0f;       // samples excursion (set by set_drift)
    bool ping_pong_ = false;
    float motor_slew_rate_ = MOTOR_SLEW_RATE;
    float target_time_ = 12000.0f;    // samples (250 ms default)
 
    // ─── Feedback ParameterSmoother (FDP-052) ─────────────────────
    primitives::ParameterSmoother op_feedback_;
    bool fb_init_ = false;
    bool fb_smoother_configured_ = false;
 
    // ─── Smoothing state ─────────────────────────────────────────
    float smooth_feedback_ = 0.0f;
    float smooth_drive_ = 0.0f;
    float block_drive_ = 0.0f;         // block-rate pre-smoother for drive
    float smooth_tone_su_ = 0.0f;
    float smooth_hp_su_ = 0.0f;
    float smooth_time_ = 0.0f;
    float smooth_wow_depth_ = 0.0f;    // block-rate character smoothing (FDP-048)
    float smooth_flutter_depth_ = 0.0f;
    float smooth_hiss_level_ = 0.0f;
    float smooth_drift_amount_ = 0.0f;
    bool smoothing_initialized_ = false;
    bool time_initialized_ = false;
};
 
} // namespace sbl::dsp::modules
 
#endif // SBL_DSP_MODULES_TAPE_DELAY_HPP_