Phaser.h

Go to the documentation of this file.

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "../Core/Oscillator.h"
#include "../Core/DryWetMixer.h"
#include "../Core/AudioSpec.h"
#include "../Core/AudioBuffer.h"
#include "../Core/DspMath.h" // fastExp, fastTan, fastTanh
#include "../Core/StateBlob.h"
 
#include <algorithm>
#include <array>
#include <atomic>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <numbers>
#include <vector>
 
namespace dspark {
 
template <FloatType T>
class Phaser
{
public:
    ~Phaser() = default; // non-virtual: leaf class (no virtual dispatch)
 
    static constexpr int kMaxStages = 12;
 
    // -- Lifecycle --------------------------------------------------------------
 
    void prepare(const AudioSpec& spec)
    {
        if (!spec.isValid()) return; // release-safe: keep previous state
 
        spec_ = spec;
        mixer_.prepare(spec);
 
        lfo_.prepare(spec.sampleRate);
        lfo_.setFrequency(rate_.load(std::memory_order_relaxed));
        lfo_.setWaveform(lfoWaveform_.load(std::memory_order_relaxed));
 
        lfoR_.prepare(spec.sampleRate);
        lfoR_.setFrequency(rate_.load(std::memory_order_relaxed));
        lfoR_.setWaveform(lfoWaveform_.load(std::memory_order_relaxed));
 
        // One-pole parameter smoothing at a 20 Hz corner (~8 ms time constant)
        smoothCoef_ = T(1) - std::exp(static_cast<T>(-2.0 * std::numbers::pi * 20.0) / static_cast<T>(spec_.sampleRate));
 
        prepared_ = true;
        reset();
    }
 
    void processBlock(AudioBufferView<T> buffer) noexcept
    {
        if (!prepared_) return; // without prepare(), fsInv below would be 1/0 -> NaN chain
 
        const int nCh = std::min(buffer.getNumChannels(), kMaxChannels);
        const int nS  = buffer.getNumSamples();
 
        // Front-door non-finite guard (M-006 C1): the allpass recursion
        // (yPrev/xPrev) latches a NaN/Inf input permanently -- even with feedback
        // off -- so a single glitch would silence the effect forever. Replace
        // non-finite input with 0 before it reaches the dry snapshot or any
        // allpass/feedback state. No-op on finite input (metrics byte-identical).
        for (int ch = 0; ch < buffer.getNumChannels(); ++ch)
        {
            T* d = buffer.getChannel(ch);
            for (int i = 0; i < nS; ++i)
                if (!std::isfinite(d[i])) d[i] = T(0);
        }
 
        // Target parameters loaded once per block
        const T targetDepth = depth_.load(std::memory_order_relaxed);
        const T targetMix   = mix_.load(std::memory_order_relaxed);
        const T targetFb    = feedback_.load(std::memory_order_relaxed);
        const int stagesVal = numStages_.load(std::memory_order_relaxed);
        const T minF        = minFreq_.load(std::memory_order_relaxed);
        const T maxF        = maxFreq_.load(std::memory_order_relaxed);
        const T spreadVal   = stereoSpread_.load(std::memory_order_relaxed);
 
        // Apply LFO rate/waveform on the AUDIO thread (the setters only publish
        // atomics) so the non-atomic Oscillator state is never written concurrently.
        lfo_.setFrequency(rate_.load(std::memory_order_relaxed));
        lfo_.setWaveform(lfoWaveform_.load(std::memory_order_relaxed));
        lfoR_.setFrequency(rate_.load(std::memory_order_relaxed));
        lfoR_.setWaveform(lfoWaveform_.load(std::memory_order_relaxed));
 
        // Re-phase the right-channel LFO when the spread changes (audio thread
        // only; Oscillator state is not thread-safe).
        if (std::abs(spreadVal - lastSpread_) > T(0.0001))
        {
            lastSpread_ = spreadVal;
            T ph = lfo_.getPhase() + spreadVal * T(0.5);
            ph -= std::floor(ph);
            lfoR_.setPhase(ph);
        }
        const bool useSpread = (spreadVal > T(0.0001)) && (nCh >= 2);
 
        // Stages activated by a live increase start from cleared state: their
        // history is from whenever they were last active (arbitrarily old),
        // and replaying it injects an unrelated step into the chain.
        if (stagesVal > lastStages_)
            for (int s = lastStages_; s < stagesVal; ++s)
            {
                stages_[s].xPrev.fill(T(0));
                stages_[s].yPrev.fill(T(0));
            }
        lastStages_ = stagesVal;
 
        mixer_.pushDry(buffer);
 
        const T logMin = std::log(minF);
        const T logMax = std::log(maxF);
        const T fsInv  = T(1) / static_cast<T>(spec_.sampleRate);
        const T nyquist = static_cast<T>(spec_.sampleRate) * T(0.499);
        constexpr T kPi = static_cast<T>(std::numbers::pi);
 
        auto coeffFromLfo = [&](T lfoVal) noexcept -> T
        {
            T modAmount = (lfoVal + T(1)) * T(0.5) * currentDepth_;
            T logFreq = logMin + modAmount * (logMax - logMin);
            // Convert log-frequency back to linear Hz (fastExp, ~2x std::exp)
            T cutoff = std::min(fastExp(logFreq), nyquist);
            // Bilinear-transform coefficient: tan(pi * f / Fs). fastTan is safe:
            // `cutoff` stays below Nyquist thanks to the clamp above.
            T tanVal = fastTan(kPi * cutoff * fsInv);
            return (tanVal - T(1)) / (tanVal + T(1));
        };
 
        for (int i = 0; i < nS; ++i)
        {
            // Parameter smoothing (1-pole lowpass) to prevent zipper noise
            currentDepth_ += smoothCoef_ * (targetDepth - currentDepth_);
            currentFb_    += smoothCoef_ * (targetFb - currentFb_);
 
            const T cL = coeffFromLfo(lfo_.getNextSample());
            const T lfoRVal = lfoR_.getNextSample(); // keep phase advancing always
            const T cR = useSpread ? coeffFromLfo(lfoRVal) : cL;
 
            // Process active channels (odd channels follow the spread LFO)
            for (int ch = 0; ch < nCh; ++ch)
            {
                const T c = (ch & 1) ? cR : cL;
                T sample = buffer.getChannel(ch)[i];
 
                // Analog-modeled feedback with soft clipping to prevent digital
                // blowups. fastTanh is internally clamped; at typical levels
                // the argument stays below 1, where its error is < 0.05%.
                T fbSignal = fastTanh(fbState_[ch] * currentFb_);
                sample += fbSignal;
 
                // Series first-order allpass chain
                for (int s = 0; s < stagesVal; ++s)
                {
                    auto& st = stages_[s];
                    T y = c * sample + st.xPrev[ch] - c * st.yPrev[ch];
                    st.xPrev[ch] = sample;
                    st.yPrev[ch] = y;
                    sample = y;
                }
 
                fbState_[ch] = sample; // 1-sample delay for next iteration
                buffer.getChannel(ch)[i] = sample;
            }
        }
 
        // DryWetMixer smooths the mix parameter internally.
        mixer_.mixWet(buffer, targetMix);
    }
 
    void reset() noexcept
    {
        for (auto& stage : stages_)
        {
            stage.xPrev.fill(T(0));
            stage.yPrev.fill(T(0));
        }
        for (auto& fb : fbState_) fb = T(0);
 
        currentDepth_ = depth_.load(std::memory_order_relaxed);
        currentFb_    = feedback_.load(std::memory_order_relaxed);
 
        lfo_.reset();
        lfoR_.reset();
        lastSpread_ = T(-1); // force re-phase of the spread LFO on next block
        mixer_.reset();
    }
 
    // -- Level 1: Simple API ----------------------------------------------------
 
    void setRate(T hz) noexcept
    {
        if (!std::isfinite(hz)) return;
        rate_.store(std::clamp(hz, T(0.01), T(20)), std::memory_order_relaxed); // applied on the audio thread
    }
 
    void setDepth(T amount) noexcept
    {
        if (!std::isfinite(amount)) return;
        depth_.store(std::clamp(amount, T(0), T(1)), std::memory_order_relaxed);
    }
 
    void setMix(T dryWet) noexcept
    {
        if (!std::isfinite(dryWet)) return;
        mix_.store(std::clamp(dryWet, T(0), T(1)), std::memory_order_relaxed);
    }
 
    // -- Level 2: Intermediate API ----------------------------------------------
 
    void setStages(int count) noexcept
    {
        numStages_.store(std::clamp(count, 1, kMaxStages), std::memory_order_relaxed);
    }
 
    void setFeedback(T amount) noexcept
    {
        if (!std::isfinite(amount)) return;
        feedback_.store(std::clamp(amount, T(-0.99), T(0.99)), std::memory_order_relaxed);
    }
 
    void setStereoSpread(T amount) noexcept
    {
        if (!std::isfinite(amount)) return;
        stereoSpread_.store(std::clamp(amount, T(0), T(1)), std::memory_order_relaxed);
    }
 
    void setCenterFrequency(T hz) noexcept
    {
        if (!std::isfinite(hz) || !(hz > T(0))) return;
        T curMin = minFreq_.load(std::memory_order_relaxed);
        T curMax = maxFreq_.load(std::memory_order_relaxed);
        T halfRange = std::sqrt(curMax / (curMin > T(0) ? curMin : T(1)));
 
        const T ceiling = (spec_.sampleRate > 0)
            ? static_cast<T>(spec_.sampleRate) * T(0.499) : T(20000);
        const T mn = std::clamp(hz / halfRange, T(20), ceiling - T(1));
        minFreq_.store(mn, std::memory_order_relaxed);
        maxFreq_.store(std::clamp(hz * halfRange, mn + T(1), ceiling),
                       std::memory_order_relaxed);
    }
 
    void setFrequencyRange(T minHz, T maxHz) noexcept
    {
        if (!std::isfinite(minHz) || !std::isfinite(maxHz)) return;
        T mn = std::max(minHz, T(20));
        minFreq_.store(mn, std::memory_order_relaxed);
        maxFreq_.store(std::max(maxHz, mn + T(1)), std::memory_order_relaxed);
    }
 
    // -- Level 3: Expert API ----------------------------------------------------
 
    void setLfoWaveform(typename Oscillator<T>::Waveform wf) noexcept
    {
        const int w = std::clamp(static_cast<int>(wf), 0,
                                 static_cast<int>(Oscillator<T>::Waveform::Triangle));
        lfoWaveform_.store(static_cast<typename Oscillator<T>::Waveform>(w),
                           std::memory_order_relaxed); // applied on the audio thread
    }
 
    [[nodiscard]] int getStages() const noexcept { return numStages_.load(std::memory_order_relaxed); }
 
    [[nodiscard]] T getRate() const noexcept { return rate_.load(std::memory_order_relaxed); }
 
 
    [[nodiscard]] std::vector<uint8_t> getState() const
    {
        StateWriter w(stateId("PHSR"), 1);
        w.write("rate", rate_.load(std::memory_order_relaxed));
        w.write("depth", depth_.load(std::memory_order_relaxed));
        w.write("mix", mix_.load(std::memory_order_relaxed));
        w.write("feedback", feedback_.load(std::memory_order_relaxed));
        w.write("minFreq", minFreq_.load(std::memory_order_relaxed));
        w.write("maxFreq", maxFreq_.load(std::memory_order_relaxed));
        w.write("stages", numStages_.load(std::memory_order_relaxed));
        w.write("spread", stereoSpread_.load(std::memory_order_relaxed));
        w.write("waveform",
                static_cast<int32_t>(lfoWaveform_.load(std::memory_order_relaxed)));
        return w.blob();
    }
 
    bool setState(const uint8_t* data, size_t size)
    {
        StateReader r(data, size);
        if (!r.isValid() || r.processorId() != stateId("PHSR")) return false;
        setRate(static_cast<T>(r.read("rate", 0.5f)));
        setDepth(static_cast<T>(r.read("depth", 0.8f)));
        setMix(static_cast<T>(r.read("mix", 0.5f)));
        setFeedback(static_cast<T>(r.read("feedback", 0.0f)));
        setFrequencyRange(static_cast<T>(r.read("minFreq", 200.0f)),
                          static_cast<T>(r.read("maxFreq", 6000.0f)));
        setStages(r.read("stages", 4));
        setStereoSpread(static_cast<T>(r.read("spread", 0.0f)));
        setLfoWaveform(static_cast<typename Oscillator<T>::Waveform>(
            r.read("waveform", 0)));
        return true;
    }
 
protected:
    static constexpr int kMaxChannels = 16;
 
    AudioSpec spec_ {};
 
    // Parameters
    std::atomic<T> rate_     { T(0.5) };
    std::atomic<T> depth_    { T(0.8) };
    std::atomic<T> mix_      { T(0.5) };
    std::atomic<T> feedback_ { T(0) };
    std::atomic<T> minFreq_  { T(200) };
    std::atomic<T> maxFreq_  { T(6000) };
    std::atomic<int> numStages_ { 4 };
    std::atomic<typename Oscillator<T>::Waveform> lfoWaveform_ { Oscillator<T>::Waveform::Sine };
    std::atomic<T> stereoSpread_ { T(0) };
 
    // Smoothed state parameters
    bool prepared_  { false };
    T currentDepth_ { T(0.8) };
    T currentFb_    { T(0) };
    T smoothCoef_   { T(0.01) };
    T lastSpread_   { T(-1) };
    int lastStages_ { kMaxStages }; // audio-thread: clears newly activated stages
 
    struct FirstOrderAllpass
    {
        std::array<T, kMaxChannels> xPrev {};
        std::array<T, kMaxChannels> yPrev {};
    };
 
    // Processing state
    std::array<FirstOrderAllpass, kMaxStages> stages_ {};
    std::array<T, kMaxChannels> fbState_ {};
    Oscillator<T> lfo_;
    Oscillator<T> lfoR_;   // right-channel LFO for stereo spread
    DryWetMixer<T> mixer_;
};
 
} // namespace dspark