Delay.h

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "../Core/AudioBuffer.h"
#include "../Core/AudioSpec.h"
#include "../Core/DspMath.h"
#include "../Core/Smoothers.h"
#include "../Core/StateBlob.h"
 
#include <algorithm>
#include <array>
#include <atomic>
#include <cmath>
#include <cstdint>
#include <cstring>
#include <vector>
 
namespace dspark {
 
template <typename SampleType>
class Delay final
{
public:
    enum class SmootherType
    {
        None, Linear, Exponential, OnePole, MultiPole2,
        Asymmetric, SlewLimiter, StateVariable, Butterworth, CriticallyDamped
    };
 
    enum class FeedbackMode
    {
        Clean,  
        Analog  
    };
 
    void setFeedbackMode(FeedbackMode mode) noexcept
    {
        feedbackMode_.store(mode, std::memory_order_relaxed);
    }
 
    [[nodiscard]] FeedbackMode getFeedbackMode() const noexcept
    {
        return feedbackMode_.load(std::memory_order_relaxed);
    }
 
    // -- Lifecycle -----------------------------------------------------------
 
    void prepare(const AudioSpec& spec)
    {
        prepare(spec, kDefaultMaxDelaySeconds);
    }
 
    void prepare(const AudioSpec& spec, double maxDelaySeconds)
    {
        if (!spec.isValid() || !(maxDelaySeconds >= 0.0)) return;
        sampleRate_ = static_cast<SampleType>(spec.sampleRate);
        // Clamp to the fixed per-channel state arrays (states_/writeIndices_ are
        // kMaxChannels): maybeUpdateSmoothers()/updateSmootherTargets() iterate
        // [0, numChannels_) and would otherwise read/write out of bounds.
        numChannels_ = std::min(static_cast<int>(spec.numChannels), kMaxChannels);
        blockSize_   = spec.maxBlockSize;
 
        // Cap in double BEFORE the int cast: a huge request would otherwise be
        // undefined behaviour in the cast, and nextPow2 past 2^29 overflows
        // its shift. 2^29 samples is over 3 hours at 48 kHz.
        const double capacityD =
            std::min(std::ceil(maxDelaySeconds * spec.sampleRate) + blockSize_,
                     536870912.0); // 2^29
        maxDelaySamples_ = nextPow2(static_cast<int>(capacityD));
        bufferMask_ = maxDelaySamples_ - 1;
 
        delayBuffer_.resize(numChannels_, maxDelaySamples_);
        wetBuffer_.resize(numChannels_, blockSize_);
        lastWetSamples_ = blockSize_; // full capacity until the first push
 
        float timeMs = smoothingTimeMs_.load(std::memory_order_relaxed);
        for (int ch = 0; ch < std::min(numChannels_, kMaxChannels); ++ch)
        {
            resetChannelSmoothers(states_[ch], timeMs, 0.0f);
            writeIndices_[ch] = 0;
        }
 
        mixSmoother_.reset(spec.sampleRate, timeMs, 1.0f);
        insertMixMaxStep_ = static_cast<SampleType>(1.0 / std::max(1.0, spec.sampleRate * 0.02));
        reset();
        
        prepared_.store(true, std::memory_order_release);
    }
 
    void prepareMs(const AudioSpec& spec, double maxDelayMs)
    {
        prepare(spec, maxDelayMs / 1000.0);
    }
 
    void reset() noexcept
    {
        delayBuffer_.clear();
        wetBuffer_.clear();
        for (int ch = 0; ch < kMaxChannels; ++ch)
        {
            writeIndices_[ch] = 0;
            resetChannelState(states_[ch]);
        }
        mixSmoother_.skip();
        insertMix_ = mix_.load(std::memory_order_relaxed); // no fade-in on start
    }
 
    // -- Configuration -------------------------------------------------------
 
    void setSmoother(SmootherType type) noexcept
    {
        smootherType_.store(type, std::memory_order_relaxed);
        smootherDirty_.store(true, std::memory_order_release);
    }
 
    void setSmoothingTime(float ms) noexcept
    {
        if (!std::isfinite(ms)) return;
        smoothingTimeMs_.store(std::max(0.0f, ms), std::memory_order_relaxed);
        smootherDirty_.store(true, std::memory_order_release);
    }
 
    // -- Parameters ----------------------------------------------------------
 
    void setDelaySamples(SampleType samples) noexcept
    {
        if (!std::isfinite(samples)) return;
        samples = std::clamp(samples, SampleType(0),
                             static_cast<SampleType>(std::max(0, maxDelaySamples_ - 1)));
        globalDelay_.store(samples, std::memory_order_relaxed);
        // Publish/apply pattern: the smoothers are NOT touched here (they are
        // non-atomic audio-thread state - mutating them from a control thread
        // raced against advanceSmoother). The audio thread applies the new
        // target in maybeUpdateSmoothers() at the top of its next process call.
        delayTargetDirty_.store(true, std::memory_order_release);
    }
 
    void setDelayMs(SampleType ms) noexcept { setDelaySamples(ms * sampleRate_ / SampleType(1000)); }
 
    void setDelaySeconds(SampleType secs) noexcept { setDelaySamples(secs * sampleRate_); }
 
    [[nodiscard]] SampleType getCurrentDelaySamples() const noexcept { return globalDelay_.load(std::memory_order_relaxed); }
 
    void setFeedback(SampleType gain) noexcept
    {
        if (!std::isfinite(gain)) return;
        feedbackGain_.store(gain, std::memory_order_relaxed);
    }
 
    void setFeedbackLpHz(SampleType freq) noexcept
    {
        if (!std::isfinite(freq)) return;
        fbLpCoef_.store((freq > 0) ? calcLpCoef(freq) : SampleType(0), std::memory_order_relaxed);
        fbLpHzShadow_.store(freq, std::memory_order_relaxed);   // serialization readback
    }
 
    void setFeedbackHpHz(SampleType freq) noexcept
    {
        if (!std::isfinite(freq)) return;
        fbHpCoef_.store((freq > 0) ? calcHpCoef(freq) : SampleType(0), std::memory_order_relaxed);
        fbHpHzShadow_.store(freq, std::memory_order_relaxed);   // serialization readback
    }
 
    // -- Sample processing ---------------------------------------------------
 
    SampleType processSample(int ch, SampleType input) noexcept
    {
        if (ch < 0 || ch >= numChannels_ || !prepared_.load(std::memory_order_acquire)) return input;
        maybeUpdateSmoothers();
        
        auto& s = states_[ch];
        auto st = smootherType_.load(std::memory_order_relaxed);
        SampleType delay = (st == SmootherType::None) 
            ? globalDelay_.load(std::memory_order_relaxed) : advanceSmoother(s, st);
            
        SampleType out = processSampleInternal(ch, input, delay, s, 
                                               feedbackGain_.load(std::memory_order_relaxed), 
                                               fbLpCoef_.load(std::memory_order_relaxed),
                                               fbHpCoef_.load(std::memory_order_relaxed));
        advanceWriteIndexUnchecked(ch);
        return out;
    }
 
    // -- Block processing ----------------------------------------------------
 
    void processBlock(AudioBufferView<SampleType> buffer) noexcept
    {
        if (!prepared_.load(std::memory_order_acquire)) return;
        maybeUpdateSmoothers();
 
        const int nS  = buffer.getNumSamples();
        const int nCh = std::min(buffer.getNumChannels(), numChannels_);
        const auto smoothType = smootherType_.load(std::memory_order_relaxed);
        const SampleType targetDelay = globalDelay_.load(std::memory_order_relaxed);
        const SampleType fb  = feedbackGain_.load(std::memory_order_relaxed);
        const SampleType lpC = fbLpCoef_.load(std::memory_order_relaxed);
        const SampleType hpC = fbHpCoef_.load(std::memory_order_relaxed);
        const SampleType mixTarget = mix_.load(std::memory_order_relaxed);
        const SampleType mixStart  = insertMix_;
        const bool pingPong = pingPong_.load(std::memory_order_relaxed) && nCh >= 2;
 
        if (pingPong)
        {
            // The first two channels cross their feedback (the same wiring as
            // processPingPong()); the blend is the insert's.
            const bool analogFb = feedbackMode_.load(std::memory_order_relaxed) == FeedbackMode::Analog;
            SampleType* L = buffer.getChannel(0);
            SampleType* R = buffer.getChannel(1);
            auto& sL = states_[0];
            auto& sR = states_[1];
            for (int i = 0; i < nS; ++i)
            {
                const SampleType currentDelay = (smoothType == SmootherType::None)
                                              ? targetDelay : advanceSmoother(sL, smoothType);
                advanceSmoother(sR, smoothType);   // kept in step, as in processPingPong()
                const SampleType dryL = L[i], dryR = R[i];
                const SampleType outL = processSampleInternal(0, dryL + sL.pingPongFb, currentDelay, sL, SampleType(0), lpC, hpC);
                const SampleType outR = processSampleInternal(1, dryR + sR.pingPongFb, currentDelay, sR, SampleType(0), lpC, hpC);
                sR.pingPongFb = saturateFeedback(processFbFilters(1, outL * fb, lpC, hpC), analogFb);
                sL.pingPongFb = saturateFeedback(processFbFilters(0, outR * fb, lpC, hpC), analogFb);
                advanceWriteIndexUnchecked(0);
                advanceWriteIndexUnchecked(1);
                const SampleType m = moveTowards(mixStart, mixTarget,
                                                 insertMixMaxStep_ * static_cast<SampleType>(i + 1));
                L[i] = dryL + (outL - dryL) * m;
                R[i] = dryR + (outR - dryR) * m;
            }
        }
 
        for (int ch = pingPong ? 2 : 0; ch < nCh; ++ch)
        {
            SampleType* data = buffer.getChannel(ch);
            auto& s = states_[ch];
            for (int i = 0; i < nS; ++i)
            {
                const SampleType currentDelay = (smoothType == SmootherType::None)
                                              ? targetDelay : advanceSmoother(s, smoothType);
                const SampleType dry = data[i];
                const SampleType wet = processSampleInternal(ch, dry, currentDelay, s, fb, lpC, hpC);
                advanceWriteIndexUnchecked(ch);
                const SampleType m = moveTowards(mixStart, mixTarget,
                                                 insertMixMaxStep_ * static_cast<SampleType>(i + 1));
                data[i] = dry + (wet - dry) * m;
            }
        }
        insertMix_ = moveTowards(mixStart, mixTarget, insertMixMaxStep_ * static_cast<SampleType>(nS));
    }
 
    void setMix(SampleType mix) noexcept
    {
        if (!std::isfinite(mix)) return;
        mix_.store(std::clamp(mix, SampleType(0), SampleType(1)), std::memory_order_relaxed);
    }
 
    [[nodiscard]] SampleType getMix() const noexcept { return mix_.load(std::memory_order_relaxed); }
 
    void setPingPong(bool on) noexcept { pingPong_.store(on, std::memory_order_relaxed); }
 
    [[nodiscard]] bool getPingPong() const noexcept { return pingPong_.load(std::memory_order_relaxed); }
 
    [[nodiscard]] int getLatency() const noexcept { return 0; }
 
    void processBlock(AudioBufferView<SampleType> buffer, SampleType delayMs,
                      SampleType feedback = 0, SampleType lpHz = 0, SampleType hpHz = 0) noexcept
    {
        if (!prepared_.load(std::memory_order_acquire)) return;
 
        setDelayMs(delayMs);
        setFeedback(feedback);
        setFeedbackLpHz(lpHz);
        setFeedbackHpHz(hpHz);
        maybeUpdateSmoothers();
 
        const int nS = buffer.getNumSamples();
        const int nCh = std::min(buffer.getNumChannels(), numChannels_);
        
        // Cache atomic parameters to local stack for auto-vectorization & performance
        const auto smoothType = smootherType_.load(std::memory_order_relaxed);
        const SampleType targetDelay = globalDelay_.load(std::memory_order_relaxed);
        const SampleType fb = feedbackGain_.load(std::memory_order_relaxed);
        const SampleType lpC = fbLpCoef_.load(std::memory_order_relaxed);
        const SampleType hpC = fbHpCoef_.load(std::memory_order_relaxed);
 
        for (int ch = 0; ch < nCh; ++ch)
        {
            SampleType* data = buffer.getChannel(ch);
            auto& s = states_[ch];
            
            for (int i = 0; i < nS; ++i)
            {
                SampleType currentDelay = (smoothType == SmootherType::None) ? targetDelay : advanceSmoother(s, smoothType);
                data[i] = processSampleInternal(ch, data[i], currentDelay, s, fb, lpC, hpC);
                advanceWriteIndexUnchecked(ch);
            }
        }
    }
 
    void processChannel(AudioBufferView<SampleType> buffer, int ch, SampleType delayMs,
                        SampleType feedback = 0, SampleType lpHz = 0, SampleType hpHz = 0) noexcept
    {
        if (ch < 0 || ch >= numChannels_ || !prepared_.load(std::memory_order_acquire)) return;
 
        setDelayMs(delayMs);
        setFeedback(feedback);
        setFeedbackLpHz(lpHz);
        setFeedbackHpHz(hpHz);
        maybeUpdateSmoothers();
 
        SampleType* data = buffer.getChannel(ch);
        const int nS = buffer.getNumSamples();
        
        const auto smoothType = smootherType_.load(std::memory_order_relaxed);
        const SampleType targetDelay = globalDelay_.load(std::memory_order_relaxed);
        const SampleType fb = feedbackGain_.load(std::memory_order_relaxed);
        const SampleType lpC = fbLpCoef_.load(std::memory_order_relaxed);
        const SampleType hpC = fbHpCoef_.load(std::memory_order_relaxed);
        
        auto& s = states_[ch];
 
        for (int i = 0; i < nS; ++i)
        {
            SampleType currentDelay = (smoothType == SmootherType::None) ? targetDelay : advanceSmoother(s, smoothType);
            data[i] = processSampleInternal(ch, data[i], currentDelay, s, fb, lpC, hpC);
            advanceWriteIndexUnchecked(ch);
        }
    }
 
    // -- Wet buffer processing -----------------------------------------------
 
    void pushDryToWet(AudioBufferView<const SampleType> dry) noexcept
    {
        pushDryToWetImpl([&](int ch) { return dry.getChannel(ch); }, dry.getNumChannels(), dry.getNumSamples());
    }
 
    void pushDryToWet(AudioBufferView<SampleType> dry) noexcept
    {
        pushDryToWetImpl([&](int ch) { return dry.getChannel(ch); }, dry.getNumChannels(), dry.getNumSamples());
    }
 
    void processWet(SampleType delayMs, SampleType feedback = 0, SampleType lpHz = 0, SampleType hpHz = 0) noexcept
    {
        processBlock(wetBuffer_.toView().getSubView(0, lastWetSamples_), delayMs, feedback, lpHz, hpHz);
    }
 
    void processPingPong(SampleType delayMs, SampleType feedback = 0, SampleType lpHz = 0, SampleType hpHz = 0) noexcept
    {
        if (wetBuffer_.getNumChannels() < 2 || !prepared_.load(std::memory_order_acquire)) return;
 
        setDelayMs(delayMs);
        setFeedback(feedback);
        setFeedbackLpHz(lpHz);
        setFeedbackHpHz(hpHz);
        maybeUpdateSmoothers();
 
        SampleType* L = wetBuffer_.getChannel(0);
        SampleType* R = wetBuffer_.getChannel(1);
        const int nS = std::min(lastWetSamples_, wetBuffer_.getNumSamples());
 
        const auto smoothType = smootherType_.load(std::memory_order_relaxed);
        const SampleType targetDelay = globalDelay_.load(std::memory_order_relaxed);
        const SampleType fb  = feedbackGain_.load(std::memory_order_relaxed);
        const SampleType lpC = fbLpCoef_.load(std::memory_order_relaxed);
        const SampleType hpC = fbHpCoef_.load(std::memory_order_relaxed);
        const bool analogFb  = feedbackMode_.load(std::memory_order_relaxed) == FeedbackMode::Analog;
 
        for (int i = 0; i < nS; ++i)
        {
            auto& sL = states_[0];
            auto& sR = states_[1];
 
            SampleType currentDelay = (smoothType == SmootherType::None) ? targetDelay : advanceSmoother(sL, smoothType);
            advanceSmoother(sR, smoothType); // Keep smoothers in sync
 
            // s.pingPongFb holds what THIS channel receives next sample, i.e.
            // the OTHER channel's previous output. (The original wiring
            // consumed each channel's own stored value while storing f(other)
            // into it: every echo regenerated into its own channel and the
            // signal never crossed the stereo field at all.)
            SampleType inL = L[i] + sL.pingPongFb;
            SampleType inR = R[i] + sR.pingPongFb;
 
            SampleType outL = processSampleInternal(0, inL, currentDelay, sL, SampleType(0), lpC, hpC);
            SampleType outR = processSampleInternal(1, inR, currentDelay, sR, SampleType(0), lpC, hpC);
 
            sR.pingPongFb = saturateFeedback(processFbFilters(1, outL * fb, lpC, hpC), analogFb); // L crosses to R
            sL.pingPongFb = saturateFeedback(processFbFilters(0, outR * fb, lpC, hpC), analogFb); // R crosses to L
 
            L[i] = outL;
            R[i] = outR;
            advanceWriteIndexUnchecked(0);
            advanceWriteIndexUnchecked(1);
        }
    }
 
    void mixWetToDry(AudioBufferView<SampleType> dry, SampleType mix) noexcept
    {
        // min/max with this argument order also resolves NaN to the dry bound.
        mix = std::min(SampleType(1), std::max(SampleType(0), mix));
        auto st = smootherType_.load(std::memory_order_relaxed);
        if (st != SmootherType::None)
            mixSmoother_.setTargetValue(static_cast<float>(mix));
 
        const int nS = std::min(dry.getNumSamples(), wetBuffer_.getNumSamples());
        const int nCh = std::min(dry.getNumChannels(), wetBuffer_.getNumChannels());
 
        // Sample-outer loop: ONE smoother value per sample, shared by every
        // channel. Advancing the smoother inside a channel-outer loop ran the
        // ramp numChannels times too fast and, worse, gave each channel a
        // different segment of it (channel 1 got the ramp a whole block ahead
        // of channel 0), audibly tilting the stereo image on every mix change.
        std::array<SampleType*, kMaxChannels> d {};
        std::array<const SampleType*, kMaxChannels> w {};
        for (int ch = 0; ch < nCh; ++ch)
        {
            d[ch] = dry.getChannel(ch);
            w[ch] = wetBuffer_.getChannel(ch);
        }
        for (int i = 0; i < nS; ++i)
        {
            const SampleType m = (st != SmootherType::None)
                ? static_cast<SampleType>(mixSmoother_.getNextValue()) : mix;
            for (int ch = 0; ch < nCh; ++ch)
                d[ch][i] = d[ch][i] * (SampleType(1) - m) + w[ch][i] * m;
        }
    }
 
    AudioBufferView<SampleType> getWetView() noexcept { return wetBuffer_.toView(); }
    
    [[nodiscard]] int getMaxDelaySamples() const noexcept { return maxDelaySamples_; }
 
 
    [[nodiscard]] std::vector<uint8_t> getState() const
    {
        StateWriter w(stateId("DLAY"), 1);
        w.write("delaySamples", globalDelay_.load(std::memory_order_relaxed));
        w.write("feedback", feedbackGain_.load(std::memory_order_relaxed));
        w.write("fbLpHz", fbLpHzShadow_.load(std::memory_order_relaxed));
        w.write("fbHpHz", fbHpHzShadow_.load(std::memory_order_relaxed));
        w.write("smoother", static_cast<int32_t>(smootherType_.load(std::memory_order_relaxed)));
        w.write("smoothingMs", smoothingTimeMs_.load(std::memory_order_relaxed));
        w.write("fbMode", static_cast<int32_t>(feedbackMode_.load(std::memory_order_relaxed)));
        w.write("mix", static_cast<float>(mix_.load(std::memory_order_relaxed)));
        w.write("pingPong", static_cast<int32_t>(pingPong_.load(std::memory_order_relaxed) ? 1 : 0));
        return w.blob();
    }
 
    bool setState(const uint8_t* data, size_t size)
    {
        StateReader r(data, size);
        if (!r.isValid() || r.processorId() != stateId("DLAY")) return false;
        setDelaySamples(static_cast<SampleType>(r.read("delaySamples", 0.0f)));
        setFeedback(static_cast<SampleType>(r.read("feedback", 0.0f)));
        setFeedbackLpHz(static_cast<SampleType>(r.read("fbLpHz", 0.0f)));
        setFeedbackHpHz(static_cast<SampleType>(r.read("fbHpHz", 0.0f)));
        // Enum fields clamped so a corrupt/foreign blob cannot install ids
        // outside the ranges the switches expect.
        setSmoother(static_cast<SmootherType>(std::clamp(r.read("smoother", 0), 0,
                    static_cast<int>(SmootherType::CriticallyDamped))));
        setSmoothingTime(r.read("smoothingMs", 20.0f));
        setFeedbackMode(static_cast<FeedbackMode>(std::clamp(r.read("fbMode", 1), 0,
                        static_cast<int>(FeedbackMode::Analog))));
        setMix(static_cast<SampleType>(r.read("mix", 0.3f)));
        setPingPong(r.read("pingPong", 0) != 0);
        return true;
    }
 
protected:
    static constexpr int kMaxChannels = 16;
    static constexpr double kDefaultMaxDelaySeconds = 4.0;
 
    struct ChannelState
    {
        SampleType fbLpZ1 = 0, fbHpZ1 = 0;
        SampleType lastFeedback = 0;
        SampleType pingPongFb = 0;
        SampleType currentDelay = 0, targetDelay = 0;
 
        Smoothers::LinearSmoother lin;
        Smoothers::ExponentialSmoother exp;
        Smoothers::OnePoleSmoother onePole;
        Smoothers::MultiPoleSmoother<2> multi2;
        Smoothers::AsymmetricSmoother asym;
        Smoothers::SlewLimiter slew;
        Smoothers::StateVariableSmoother svf;
        Smoothers::ButterworthSmoother butter;
        Smoothers::CriticallyDampedSmoother crit;
    };
 
public:
    void advanceWriteIndex(int ch) noexcept
    {
        if (ch < 0 || ch >= kMaxChannels) return;
        advanceWriteIndexUnchecked(ch);
    }
 
private:
    void advanceWriteIndexUnchecked(int ch) noexcept { writeIndices_[ch] = (writeIndices_[ch] + 1) & bufferMask_; }
 
    [[nodiscard]] SampleType saturateFeedback(SampleType x, bool analog) const noexcept
    {
        return analog ? std::tanh(x) : std::clamp(x, SampleType(-2), SampleType(2));
    }
 
    template <typename ChannelFn>
    void pushDryToWetImpl(ChannelFn&& getCh, int dryCh, int drySamples) noexcept
    {
        const int nCh = std::min(dryCh, wetBuffer_.getNumChannels());
        const int nS  = std::min(drySamples, wetBuffer_.getNumSamples());
        for (int ch = 0; ch < nCh; ++ch)
            std::memcpy(wetBuffer_.getChannel(ch), getCh(ch), static_cast<std::size_t>(nS) * sizeof(SampleType));
        lastWetSamples_ = nS; // processWet()/processPingPong() run exactly this many
    }
 
    void resetChannelState(ChannelState& s) noexcept
    {
        s.fbLpZ1 = s.fbHpZ1 = s.lastFeedback = s.pingPongFb = 0;
        s.currentDelay = s.targetDelay = 0;
    }
 
    void resetChannelSmoothers(ChannelState& s, float timeMs, float init) noexcept
    {
        double sr = static_cast<double>(sampleRate_);
        s.lin.reset(sr, timeMs, init);
        s.exp.reset(sr, timeMs, std::max(init, 1e-6f));
        s.onePole.reset(sr, timeMs, init);
        s.multi2.reset(sr, timeMs, init);
        s.asym.reset(sr, timeMs / 5.0f, timeMs, init);
        float timeSec = timeMs / 1000.0f;
        float maxRate = static_cast<float>(maxDelaySamples_) / std::max(timeSec, 1e-6f);
        s.slew.reset(sr, maxRate, init);
        s.svf.reset(sr, timeMs, 0.707f, init);
        s.butter.reset(sr, timeMs, init);
        s.crit.reset(sr, timeMs, init);
    }
 
    void maybeUpdateSmoothers() noexcept
    {
        // Audio-thread application point for control-thread publications.
        if (delayTargetDirty_.exchange(false, std::memory_order_acquire))
            updateSmootherTargets(globalDelay_.load(std::memory_order_relaxed));
 
        // exchange (not load+store: a publication between the two would be
        // lost) with acquire, pairing with the setters' release stores so the
        // freshly written type/time values are visible here.
        if (!smootherDirty_.exchange(false, std::memory_order_acquire)) return;
        float timeMs = smoothingTimeMs_.load(std::memory_order_relaxed);
        for (int ch = 0; ch < numChannels_; ++ch)
        {
            auto& s = states_[ch];
            float cur = static_cast<float>(s.currentDelay);
            float tgt = static_cast<float>(s.targetDelay);
            resetChannelSmoothers(s, timeMs, cur);
            setSmootherTarget(s, static_cast<SampleType>(tgt));
        }
        mixSmoother_.reset(static_cast<double>(sampleRate_), timeMs, mixSmoother_.getCurrentValue());
    }
 
    void updateSmootherTargets(SampleType target) noexcept
    {
        if (smootherType_.load(std::memory_order_relaxed) == SmootherType::None) return;
        for (int ch = 0; ch < numChannels_; ++ch)
            setSmootherTarget(states_[ch], target);
    }
 
    void setSmootherTarget(ChannelState& s, SampleType target) noexcept
    {
        s.targetDelay = target;
        float t = static_cast<float>(target);
        switch (smootherType_.load(std::memory_order_relaxed))
        {
            case SmootherType::Linear:          s.lin.setTargetValue(t); break;
            case SmootherType::Exponential:     s.exp.setTargetValue(t); break;
            case SmootherType::OnePole:         s.onePole.setTargetValue(t); break;
            case SmootherType::MultiPole2:      s.multi2.setTargetValue(t); break;
            case SmootherType::Asymmetric:      s.asym.setTargetValue(t); break;
            case SmootherType::SlewLimiter:     s.slew.setTargetValue(t); break;
            case SmootherType::StateVariable:   s.svf.setTargetValue(t); break;
            case SmootherType::Butterworth:     s.butter.setTargetValue(t); break;
            case SmootherType::CriticallyDamped:s.crit.setTargetValue(t); break;
            default: break;
        }
    }
 
    inline SampleType advanceSmoother(ChannelState& s, SmootherType st) noexcept
    {
        float val;
        switch (st)
        {
            case SmootherType::Linear:          val = s.lin.getNextValue(); break;
            case SmootherType::Exponential:     val = s.exp.getNextValue(); break;
            case SmootherType::OnePole:         val = s.onePole.getNextValue(); break;
            case SmootherType::MultiPole2:      val = s.multi2.getNextValue(); break;
            case SmootherType::Asymmetric:      val = s.asym.getNextValue(); break;
            case SmootherType::SlewLimiter:     val = s.slew.getNextValue(); break;
            case SmootherType::StateVariable:   val = s.svf.getNextValue(); break;
            case SmootherType::Butterworth:     val = s.butter.getNextValue(); break;
            case SmootherType::CriticallyDamped:val = s.crit.getNextValue(); break;
            default: val = static_cast<float>(s.targetDelay);
        }
        s.currentDelay = static_cast<SampleType>(val);
        return s.currentDelay;
    }
 
    inline SampleType processSampleInternal(int ch, SampleType input, SampleType delaySamples,
                                            ChannelState& s, SampleType fbMult,
                                            SampleType lpC, SampleType hpC) noexcept
    {
        // Front-door non-finite guard: a NaN/Inf input, once written to the
        // ring and recirculated through the recursive feedback filters
        // (fbLpZ1/fbHpZ1) and the tanh saturator, poisons the delay line
        // permanently. Replace it with 0 before it enters any state. No-op on
        // finite input, so conformance metrics stay byte-identical. Shared by
        // every entry point (processBlock/Channel/Wet/PingPong/processSample).
        if (!std::isfinite(input)) input = SampleType(0);
 
        // 4-point Hermite needs read positions at idx0-1, idx0, idx0+1, idx0+2.
        // The write index points to the slot we are about to write THIS sample.
        // Slots writeIdx, writeIdx+1, writeIdx+2 still hold stale data from
        // the previous ring-buffer wrap. To keep all 4 interpolation taps
        // inside the already-written history we need delaySamples >= 3.
        // Below that, samples idx1 / idx2 leak data ~bufferSize samples old
        // which manifests as audible clicks (notably when a binaural / Haas
        // panner crosses the centre). 3 samples ~ 62 us at 48 kHz -
        // imperceptible and the same on both channels, so spatial cues
        // (centre image, ITD ratios) are preserved.
        constexpr SampleType kMinHermiteDelay = SampleType(3);
        delaySamples = std::clamp(delaySamples, kMinHermiteDelay,
                                  static_cast<SampleType>(maxDelaySamples_ - 1));
 
        SampleType* data = delayBuffer_.getChannel(ch);
        int writeIdx = writeIndices_[ch];
 
        // Read position writeIdx - delaySamples, split into an integer index
        // and a fraction in [0, 1] without ever forming the wrapped float
        // position: writeIdx - delay + size rounded up to exactly `size` when
        // the position fell a hair below 0, which masked the index to 0 while
        // the "fraction" became `size` (a Hermite blow-up, heard as random
        // zips on moving Haas/binaural delays).
        const int dInt = static_cast<int>(delaySamples);            // >= 3
        const SampleType dFrac = delaySamples - static_cast<SampleType>(dInt);
        int idx0;
        SampleType frac;
        if (dFrac > SampleType(0))
        {
            idx0 = (writeIdx - dInt - 1) & bufferMask_;
            frac = SampleType(1) - dFrac;
        }
        else
        {
            idx0 = (writeIdx - dInt) & bufferMask_;
            frac = SampleType(0);
        }
 
        // 3rd-order Hermite Interpolation (4-point)
 
        int idxM1 = (idx0 - 1 + maxDelaySamples_) & bufferMask_;
        int idx1  = (idx0 + 1) & bufferMask_;
        int idx2  = (idx0 + 2) & bufferMask_;
 
        SampleType ym1 = data[idxM1];
        SampleType y0  = data[idx0];
        SampleType y1  = data[idx1];
        SampleType y2  = data[idx2];
 
        // Hermite polynomial logic
        SampleType c = (y1 - ym1) * SampleType(0.5);
        SampleType v = y0 - y1;
        SampleType w = c + v;
        SampleType a = w + v + (y2 - y0) * SampleType(0.5);
        SampleType b = w + a;
        SampleType delayed = ((((a * frac) - b) * frac + c) * frac + y0);
 
        // Feedback processing
        SampleType fbInput = delayed * fbMult;
        if (fbInput != SampleType(0))
        {
            fbInput = processFbFilters(ch, fbInput, lpC, hpC);
            fbInput = saturateFeedback(fbInput,
                feedbackMode_.load(std::memory_order_relaxed) == FeedbackMode::Analog);
        }
        s.lastFeedback = fbInput;
 
        data[writeIdx] = input + s.lastFeedback;
        return delayed;
    }
 
    inline SampleType processFbFilters(int ch, SampleType sample, SampleType lpC, SampleType hpC) noexcept
    {
        auto& s = states_[ch];
        SampleType out = sample;
 
        // Apply denormal prevention (1e-18f bias)
        out += SampleType(1e-18); 
 
        if (hpC > SampleType(0))
        {
            s.fbHpZ1 = out * (SampleType(1) - hpC) + s.fbHpZ1 * hpC;
            out -= s.fbHpZ1;
        }
        if (lpC > SampleType(0))
        {
            s.fbLpZ1 = out * (SampleType(1) - lpC) + s.fbLpZ1 * lpC;
            out = s.fbLpZ1;
        }
        
        out -= SampleType(1e-18);
        return out;
    }
 
    SampleType calcOnePoleCoef(SampleType freq) const noexcept { return std::exp(-twoPi<SampleType> * freq / sampleRate_); }
    SampleType calcLpCoef(SampleType freq) const noexcept { return calcOnePoleCoef(freq); }
    SampleType calcHpCoef(SampleType freq) const noexcept { return calcOnePoleCoef(freq); }
 
    static int nextPow2(int v) noexcept
    {
        int r = 1;
        while (r < v) r <<= 1;
        return r;
    }
 
    // -- Members -------------------------------------------------------------
    std::atomic<bool> prepared_{ false };
    AudioBuffer<SampleType> delayBuffer_, wetBuffer_;
    std::array<ChannelState, kMaxChannels> states_ {};
    std::array<int, kMaxChannels> writeIndices_ {}; 
 
    int maxDelaySamples_ = 0, bufferMask_ = 0;
    int numChannels_ = 0, blockSize_ = 0;
    int lastWetSamples_ = 0;   
    SampleType sampleRate_ = SampleType(48000);
    
    std::atomic<SampleType> globalDelay_ { SampleType(0) };
    std::atomic<SampleType> feedbackGain_ { SampleType(0) };
    std::atomic<SampleType> fbLpCoef_ { SampleType(0) };
    std::atomic<SampleType> fbLpHzShadow_ { SampleType(0) };  
    std::atomic<SampleType> fbHpHzShadow_ { SampleType(0) };  
    std::atomic<SampleType> fbHpCoef_ { SampleType(0) };
 
    std::atomic<SmootherType> smootherType_ { SmootherType::Exponential };
    std::atomic<float> smoothingTimeMs_ { 20.0f };
    std::atomic<bool> smootherDirty_ { false };
    std::atomic<bool> delayTargetDirty_ { false };
    std::atomic<FeedbackMode> feedbackMode_ { FeedbackMode::Analog };
 
    Smoothers::LinearSmoother mixSmoother_;
    std::atomic<SampleType> mix_ { SampleType(0.3) };            
    std::atomic<bool> pingPong_ { false };                          
    SampleType insertMix_ = SampleType(0.3);                     
    SampleType insertMixMaxStep_ = SampleType(1.0 / 960.0);      
};
 
} // namespace dspark