flanger.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/character_delay/bbd.hpp>
#include <pulp/signal/character_delay/primitives.hpp>
#include <pulp/signal/crossfade.hpp>
#include <pulp/signal/dc_blocker.hpp>
#include <pulp/signal/denormal.hpp>
#include <pulp/signal/frequency_shifter_ssb.hpp>
#include <pulp/signal/lfo.hpp>
#include <pulp/signal/smoothed_value.hpp>
#include <pulp/signal/units.hpp>
 
#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <vector>
 
namespace pulp::signal {

enum class FlangerMode : std::uint8_t {
    classic,       
    through_zero,  
    barberpole,    
};

enum class FlangerPolarity : std::uint8_t {
    positive,  
    negative,  
};

enum class FlangerDelayEngine : std::uint8_t {
    clean,  
    bbd,    
};

template <typename SampleType = float>
class FlangerT {
public:
    using Mode = FlangerMode;
    using Polarity = FlangerPolarity;
    using Engine = FlangerDelayEngine;
    using Wave = LfoWave;
 
    // ── Design parameters (the complete roster) ───────────────────────────

    static constexpr double kFbClamp = 0.97;

    static constexpr double kLoopElementGainBound = 1.012;

    static constexpr double kDcBlockHz = 5.0;

    static constexpr double kDepthMinMs = 0.02;
    static constexpr double kDepthMaxMs = 4.0;

    static constexpr double kCenterMinMs = 0.1;
    static constexpr double kCenterMaxMs = 10.0;

    static constexpr double kOffsetMinMs = 0.5;
    static constexpr double kOffsetMaxMs = 10.0;

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

    static constexpr double kMinClassicDelayMs = 0.05;

    static constexpr int kInterpGuardSamples = 2;

    static constexpr double kControlSmoothMs = 3.0;

    static constexpr double kModeSwitchMs = 5.0;

    static constexpr double kBarberpoleShiftMaxHz = 20.0;

    static constexpr double kBbdCharacter = 0.5;
 
    // ── Lifecycle ─────────────────────────────────────────────────────────

    void prepare(double sample_rate) {
        sample_rate_ = sample_rate > 0.0 ? sample_rate : sample_rate_;
 
        // The modulated line has to hold the widest delay any mode can reach:
        // through-zero's `2 · kOffsetMaxMs` beats classic's centre + depth.
        const double widest_ms = std::max(2.0 * kOffsetMaxMs, kCenterMaxMs + kDepthMaxMs);
        modulated_capacity_ =
            static_cast<std::size_t>(std::ceil(units::ms_to_samples(widest_ms, sample_rate_))) +
            static_cast<std::size_t>(kInterpGuardSamples) + 4u;
        fixed_capacity_ =
            static_cast<std::size_t>(std::ceil(units::ms_to_samples(kOffsetMaxMs, sample_rate_))) +
            2u;
 
        const auto pole = static_cast<double>(std::exp(-kTwoPi * kDcBlockHz / sample_rate_));
        for (auto& ch : channels_) {
            ch.line.prepare(modulated_capacity_);
            ch.fixed.assign(fixed_capacity_, 0.0);
            ch.fixed_valid = 0;
            ch.blocker.set_pole(pole);
            ch.bbd.prepare(sample_rate_);
            // The shifter runs as a pure translator inside this loop: the
            // flanger owns the feedback and the mix, so the shifter must own
            // neither, or the spiral would be shaped twice.
            ch.shifter.prepare(sample_rate_);
            ch.shifter.set_feedback(0.0);
            ch.shifter.set_mix(1.0);
            ch.shifter.set_shift_hz(barberpole_hz_);
            // One smoother per channel: the two rails read the modulated line
            // at different delays, so a shared smoother would hand each
            // channel the other's ramp.
            ch.delay_smoother.set_ramp_time(kControlSmoothMs * 0.001, sample_rate_);
        }
 
        for (auto& lfo : lfos_) lfo.prepare(sample_rate_);
        mode_switch_samples_ =
            std::max(2, static_cast<int>(std::lround(units::ms_to_samples(kModeSwitchMs,
                                                                         sample_rate_))));
        apply_lfo_settings();
        reset();
    }

    void reset() {
        for (auto& ch : channels_) {
            ch.line.reset();
            std::fill(ch.fixed.begin(), ch.fixed.end(), 0.0);
            ch.fixed_write = 0;
            ch.fixed_valid = 0;
            ch.blocker.reset();
            ch.bbd.reset();
            ch.shifter.reset();
            ch.feedback = 0.0;
            ch.delay_ms = 0.0;
            ch.delay_smoother.set_immediate(delay_samples_for(mode_, 0.0));
        }
        for (auto& lfo : lfos_) lfo.reset();
        mode_switch_remaining_ = 0;
        previous_mode_ = mode_;
    }

    void discard_history() noexcept {
        for (auto& ch : channels_) {
            ch.line.discard_history();
            ch.fixed_write = 0;
            ch.fixed_valid = 0;
            ch.blocker.reset();
            ch.bbd.reset();
            ch.shifter.discard_history();
            ch.feedback = 0.0;
            ch.delay_ms = 0.0;
            ch.delay_smoother.set_immediate(delay_samples_for(mode_, 0.0));
        }
        for (auto& lfo : lfos_) lfo.reset();
        mode_switch_remaining_ = 0;
        previous_mode_ = mode_;
    }
 
    // ── Parameters (real units throughout) ────────────────────────────────

    void set_mode(Mode mode) {
        if (mode == mode_) return;
        previous_mode_ = mode_;
        mode_ = mode;
        mode_switch_remaining_ = mode_switch_samples_;
    }
 
    Mode mode() const { return mode_; }
 
    void set_polarity(Polarity polarity) { polarity_ = polarity; }
    Polarity polarity() const { return polarity_; }
 
    void set_delay_engine(Engine engine) { engine_ = engine; }
    Engine delay_engine() const { return engine_; }
 
    void set_rate_hz(double hz) {
        if (!std::isfinite(hz)) return;
        rate_hz_ = std::clamp(hz, kRateMinHz, kRateMaxHz);
        apply_lfo_settings();
    }
 
    void set_waveform(Wave wave) {
        wave_ = wave;
        apply_lfo_settings();
    }

    void set_stereo_spread(double cycles01) {
        if (!std::isfinite(cycles01)) return;
        stereo_spread_ = std::clamp(cycles01, 0.0, 0.5);
        apply_lfo_settings();
    }

    void set_depth_ms(double ms) {
        if (!std::isfinite(ms)) return;
        depth_ms_ = std::clamp(ms, 0.0, kDepthMaxMs);
    }
    double depth_ms() const { return depth_ms_; }
 
    void set_center_delay_ms(double ms) {
        if (!std::isfinite(ms)) return;
        center_ms_ = std::clamp(ms, kCenterMinMs, kCenterMaxMs);
    }
    double center_delay_ms() const { return center_ms_; }
 
    void set_offset_ms(double ms) {
        if (!std::isfinite(ms)) return;
        offset_ms_ = std::clamp(ms, kOffsetMinMs, kOffsetMaxMs);
    }
    double offset_ms() const { return offset_ms_; }

    void set_feedback(double fb) {
        if (!std::isfinite(fb)) return;
        feedback_ = std::clamp(fb, -kFbClamp, kFbClamp);
    }
    double feedback() const { return feedback_; }

    void set_mix(double wet01) {
        if (!std::isfinite(wet01)) return;
        mix_ = std::clamp(wet01, 0.0, 1.0);
    }
    double mix() const { return mix_; }

    void set_barberpole_shift_hz(double hz) {
        if (!std::isfinite(hz)) return;
        barberpole_hz_ = std::clamp(hz, -kBarberpoleShiftMaxHz, kBarberpoleShiftMaxHz);
        for (auto& ch : channels_) ch.shifter.set_shift_hz(barberpole_hz_);
    }
    double barberpole_shift_hz() const { return barberpole_hz_; }
 
    // ── Processing ────────────────────────────────────────────────────────
 
    void process(const SampleType* in, SampleType* out, int n) {
        for (int i = 0; i < n; ++i) {
            if (!std::isfinite(static_cast<double>(in[i]))) {
                discard_history();
                out[i] = SampleType{0};
                continue;
            }
            const Sweep sweep = advance_sweep();
            out[i] = static_cast<SampleType>(
                run_channel(channels_[0], static_cast<double>(in[i]), sweep));
        }
    }
 
    void process_stereo(const SampleType* in_left, const SampleType* in_right,
                        SampleType* out_left, SampleType* out_right, int n) {
        for (int i = 0; i < n; ++i) {
            if (!std::isfinite(static_cast<double>(in_left[i])) ||
                !std::isfinite(static_cast<double>(in_right[i]))) {
                discard_history();
                out_left[i] = out_right[i] = SampleType{0};
                continue;
            }
            const Sweep sweep = advance_sweep();
            out_left[i] = static_cast<SampleType>(
                run_channel(channels_[0], static_cast<double>(in_left[i]), sweep));
            out_right[i] = static_cast<SampleType>(
                run_channel(channels_[1], static_cast<double>(in_right[i]), sweep, 1));
        }
    }

    int latency_samples() const noexcept {
        return mode_ == Mode::through_zero ? fixed_delay_samples() : 0;
    }
 
    // ── Derived quantities (pure functions of the shipped constants) ───────

    double effective_depth_ms() const { return effective_depth_for(mode_); }

    double instantaneous_delay_ms(int channel = 0) const {
        return channels_[static_cast<std::size_t>(channel)].delay_ms;
    }

    int fixed_delay_samples() const noexcept {
        return static_cast<int>(std::lround(units::ms_to_samples(offset_ms_, sample_rate_)));
    }

    static double notch_hz(int k, double delay_ms, Polarity polarity) {
        const double d = delay_ms * 0.001;
        return polarity == Polarity::positive ? (2.0 * k + 1.0) / (2.0 * d)
                                              : static_cast<double>(k) / d;
    }

    static double notch_spacing_hz(double delay_ms) { return 1.0 / (delay_ms * 0.001); }

    static constexpr double worst_case_gain() {
        return 1.0 / (1.0 - kFbClamp * kLoopElementGainBound);
    }

    static void mix_gains(double wet01, double& dry_gain, double& wet_gain) {
        const double theta = std::clamp(wet01, 0.0, 1.0) * 0.5 * kPi;
        dry_gain = std::cos(theta);
        wet_gain = std::sin(theta);
    }
 
private:
    static constexpr double kPi = 3.14159265358979323846;
    static constexpr double kTwoPi = 6.283185307179586476925286766559;

    struct Sweep {
        double lfo[2] = {0.0, 0.0};
        double wet_scale = 1.0;
        double old_dry = 0.0;
        double new_dry = 1.0;
        bool switching = false;
        bool past_midpoint = true;
        bool snap_delay = false;
    };
 
    struct Channel {
        chardelay::FractionalDelayLine line{};
        std::vector<double> fixed{};
        std::size_t fixed_write = 0;
        std::size_t fixed_valid = 0;
        DcBlocker<double> blocker{};
        chardelay::BbdChannel bbd{};
        SsbFrequencyShifterT<double> shifter{};
        SmoothedValue<double> delay_smoother{};
        double feedback = 0.0;
        double delay_ms = 0.0;
    };
 
    Sweep advance_sweep() {
        Sweep s;
        // Both modulators advance every frame, in mono as in stereo. They are
        // two `LfoT` instances rather than one read at two offsets, and they
        // cannot drift apart: identical increments accumulated in `double`
        // from an identical reset produce identical phase forever, so the
        // spread is a fixed angular relationship rather than two clocks that
        // might disagree over a long render.
        s.lfo[0] = static_cast<double>(lfos_[0].next());
        s.lfo[1] = static_cast<double>(lfos_[1].next());
 
        const bool was_past = past_midpoint();
        if (mode_switch_remaining_ > 0) --mode_switch_remaining_;
        s.switching = mode_switch_remaining_ > 0;
        s.past_midpoint = past_midpoint();
        s.snap_delay = !was_past && s.past_midpoint;
 
        if (s.switching) {
            const double progress =
                1.0 - static_cast<double>(mode_switch_remaining_) /
                          static_cast<double>(mode_switch_samples_);
            crossfade_gains(crossfade_smoothstep(progress), CrossfadeGainLaw::EqualPower,
                            s.old_dry, s.new_dry);
            // A raised-cosine notch: 1 at both ends, exactly 0 at the midpoint
            // where the delay law changes hands.
            s.wet_scale = std::abs(std::cos(kPi * progress));
        }
        return s;
    }
 
    bool past_midpoint() const {
        return mode_switch_remaining_ <= 0 || mode_switch_remaining_ * 2 <= mode_switch_samples_;
    }

    double delay_samples_for(Mode mode, double lfo) const {
        double ms = 0.0;
        switch (mode) {
            case Mode::classic:
                ms = center_ms_ + effective_depth_for(mode) * lfo;
                break;
            case Mode::through_zero:
                // Anchored to the dry path's REALISED integer delay rather
                // than to `offset_ms` in the abstract. The spec's law is
                // written in milliseconds, but the dry line is an integer
                // buffer, so an offset that does not land on a whole sample
                // would put the crossing between two samples and the null
                // would never be exact. Sweeping about the integer the dry
                // path actually uses makes the crossing exact at every offset.
                return static_cast<double>(fixed_delay_samples()) +
                       units::ms_to_samples(effective_depth_for(mode), sample_rate_) * lfo;
            case Mode::barberpole:
                ms = center_ms_;  // fixed; the shift, not the delay, moves
                break;
        }
        return units::ms_to_samples(ms, sample_rate_);
    }
 
    double effective_depth_for(Mode mode) const {
        switch (mode) {
            case Mode::classic:
                return std::clamp(depth_ms_, 0.0, center_ms_ - kMinClassicDelayMs);
            case Mode::through_zero:
                return std::min(depth_ms_, offset_ms_);
            case Mode::barberpole:
                return 0.0;
        }
        return 0.0;
    }

    double run_channel(Channel& ch, double input, const Sweep& sweep, int index = 0) {
        const Mode active = sweep.past_midpoint ? mode_ : previous_mode_;
 
        // Delay-time target. Smoothed so a host automating the centre does not
        // step the read pointer.
        const double target = delay_samples_for(active, sweep.lfo[index]);
        if (sweep.snap_delay) ch.delay_smoother.set_immediate(target);
        ch.delay_smoother.set_target(target);
        const double delay = std::clamp(ch.delay_smoother.next(), 1.0, ch.line.max_delay());
        ch.delay_ms = units::samples_to_ms(delay, sample_rate_);
 
        // The dry reference. Both forms are maintained at all times — the
        // fixed line is written every sample regardless of mode — so a mode
        // change crossfades between two dry paths that are both already
        // correct, with no buffer to fill.
        const double dry_direct = input;
        const double dry_fixed = read_fixed(ch);
        push_fixed(ch, input);
        const double dry =
            sweep.switching
                ? sweep.old_dry * dry_for(previous_mode_, dry_direct, dry_fixed) +
                      sweep.new_dry * dry_for(mode_, dry_direct, dry_fixed)
                : dry_for(active, dry_direct, dry_fixed);
 
        // The transition window gates the wet path AT ITS SOURCE, not just on
        // the way to the mix, and that placement is the whole point. Silencing
        // only the mix contribution still writes a discontinuous feedback value
        // into the delay line at the instant the delay law changes hands — and
        // that step re-emerges one loop delay later, at full gain, long after
        // the crossfade has finished. Gating the tap instead means the line,
        // the DC blocker and the shifter all see a signal that goes smoothly to
        // zero and back, so there is nothing discontinuous anywhere to come
        // back around.
        const double sign = polarity_ == Polarity::negative ? -1.0 : 1.0;
        double wet = 0.0;
 
        if (engine_ == Engine::bbd) {
            // The bucket line owns its own delay, so its tap cannot be read
            // ahead of the write the way the clean line's can. Its loop
            // therefore carries one extra sample, which is inaudible against a
            // clocked line whose own delay quantises to its bucket count
            // anyway — but it is a real difference from the clean engine and
            // is stated rather than left to be discovered.
            const double recirculated = snap_to_zero(ch.blocker.process(ch.feedback));
            ch.bbd.update(kBbdCharacter, delay / sample_rate_);
            wet = ch.bbd.process(input + feedback_ * sign * recirculated) * sweep.wet_scale;
        } else {
            // The tap is read at `delay − 1` BEFORE the write, which is
            // bit-for-bit the same sample a read at `delay` after the write
            // would return — the same four taps at the same fractional offset,
            // with the buffer shifted by one instead of the request. Doing it
            // in this order is what makes the loop exactly `delay` samples
            // long rather than `delay + 1`.
            //
            // That one sample is not a rounding detail. The resonance sits
            // where the round-trip phase is zero, so a loop of `delay + 1`
            // puts the peaks at `1/(D+1)` while the feedforward comb's teeth
            // stay at `1/D` — 0.7 % apart at the default 3 ms delay, and 42 %
            // apart at the 0.05 ms floor, where the comb and its own resonance
            // would be audibly detuned from each other.
            wet = ch.line.read(std::max(1.0, delay - 1.0)) * sweep.wet_scale;
            // Barberpole puts the shifter INSIDE the loop, which is what makes
            // the pattern climb without end: every recirculation adds another
            // Δf, so the comb never lands back where it started the way an LFO
            // sweep does. The shifter is a pure translator here — its own
            // feedback and mix are off, because this module owns both.
            if (active == Mode::barberpole) wet = ch.shifter.process(wet);
            // The recirculating tap is DC-blocked so rounding cannot
            // accumulate a drift the (deliberately absent) saturator would
            // otherwise bound, then denormal-snapped because a decaying loop
            // tail approaches zero without reaching it. The FORWARD wet tap is
            // neither, which is what keeps the through-zero crossing an exact
            // cancellation rather than one filtered path against another.
            const double recirculated = snap_to_zero(ch.blocker.process(wet));
            ch.line.push(input + feedback_ * sign * recirculated);
        }
        ch.feedback = wet;
 
        double dry_gain = 0.0, wet_gain = 0.0;
        mix_gains(mix_, dry_gain, wet_gain);
        // `wet` already carries the transition gate — it was applied at the tap.
        return snap_to_zero(dry_gain * dry + wet_gain * sign * wet);
    }
 
    static double dry_for(Mode mode, double direct, double fixed) {
        return mode == Mode::through_zero ? fixed : direct;
    }
 
    double read_fixed(const Channel& ch) const {
        const auto delay = static_cast<std::size_t>(std::max(0, fixed_delay_samples()));
        const std::size_t capacity = ch.fixed.size();
        if (capacity == 0) return 0.0;
        if (ch.fixed_valid < capacity && delay >= ch.fixed_valid) return 0.0;
        const std::size_t index = (ch.fixed_write + capacity - (delay % capacity)) % capacity;
        return ch.fixed[index];
    }
 
    void push_fixed(Channel& ch, double x) {
        if (ch.fixed.empty()) return;
        ch.fixed[ch.fixed_write] = x;
        ch.fixed_write = (ch.fixed_write + 1u) % ch.fixed.size();
        ch.fixed_valid = std::min(ch.fixed_valid + 1u, ch.fixed.size());
    }
 
    void apply_lfo_settings() {
        for (std::size_t i = 0; i < lfos_.size(); ++i) {
            lfos_[i].set_rate_hz(rate_hz_);
            lfos_[i].set_wave(wave_);
            lfos_[i].set_phase_offset(i == 0 ? 0.0 : stereo_spread_);
        }
    }
 
    double sample_rate_ = 44100.0;
    std::size_t modulated_capacity_ = 8;
    std::size_t fixed_capacity_ = 8;
 
    Mode mode_ = Mode::classic;
    Mode previous_mode_ = Mode::classic;
    Polarity polarity_ = Polarity::positive;
    Engine engine_ = Engine::clean;
    Wave wave_ = LfoWave::sine;
 
    double rate_hz_ = 0.5;
    double depth_ms_ = 1.5;
    double center_ms_ = 3.0;
    double offset_ms_ = 4.0;
    double feedback_ = 0.6;
    double mix_ = 0.5;
    double stereo_spread_ = 0.25;
    double barberpole_hz_ = 3.0;
 
    int mode_switch_samples_ = 2;
    int mode_switch_remaining_ = 0;
 
    std::array<Channel, 2> channels_{};
    std::array<EffectLfoT<double>, 2> lfos_{};
};
 
using Flanger = FlangerT<float>;
using Flanger64 = FlangerT<double>;
 
}  // namespace pulp::signal