pitch_shifter.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/crossfade.hpp>
#include <pulp/signal/dc_blocker.hpp>
#include <pulp/signal/delay_line.hpp>
#include <pulp/signal/denormal.hpp>
#include <pulp/signal/interpolator.hpp>
#include <pulp/signal/rng.hpp>
#include <pulp/signal/slew_limiter.hpp>
#include <pulp/signal/units.hpp>
 
#include <algorithm>
#include <cmath>
#include <cstddef>
#include <cstdint>
 
namespace pulp::signal {

enum class PedalMode : std::uint8_t {
    whammy,   
    harmony,  
    detune,   
    dive,     
};

enum class PitchInterp : std::uint8_t {
    linear,  
    cubic,   
};

enum class ShiftSource : std::uint8_t {
    pedal,   
    direct,  
};

template <typename SampleType = float>
class PitchShifterT {
public:
    // ── Calibration table (§6) ────────────────────────────────────────────
    //
    // Every constant below is a [design parameter] with a default and a range,
    // per the HONEST GAP note in the file doc block, except where marked
    // definitional. Tests compute their expectations from these rather than
    // restating literals, so retuning one fails the case that documents it.

    static constexpr double kWindowMsDefault = 40.0;
    static constexpr double kWindowMsMin = 10.0;
    static constexpr double kWindowMsMax = 100.0;

    static constexpr double kGlideMsDefault = 60.0;
    static constexpr double kGlideMsMin = 0.0;
    static constexpr double kGlideMsMax = 2000.0;

    static constexpr double kDetuneCentsDefault = 12.0;
    static constexpr double kDetuneCentsMax = 50.0;

    static constexpr double kDiveFloorSemisDefault = -48.0;
    static constexpr double kDiveFloorSemisMin = -72.0;
    static constexpr double kDiveFloorSemisMax = -24.0;

    static constexpr double kHeelSemisDefault = 0.0;
    static constexpr double kToeSemisDefault = 12.0;
    static constexpr double kIntervalASemisDefault = 7.0;
    static constexpr double kIntervalBSemisDefault = 12.0;

    static constexpr double kShiftSemisMin = -48.0;
    static constexpr double kShiftSemisMax = 24.0;

    static constexpr double kSemitonesFloor = kDiveFloorSemisMin;
    static constexpr double kSemitonesCeil = kShiftSemisMax;

    static constexpr double kDetentTable[] = {-24.0, -12.0, -7.0, -5.0, 0.0,
                                              5.0,   7.0,   12.0, 24.0};
    static constexpr int kDetentCount = 9;

    static constexpr double kDetentSnapSemis = 0.35;

    static constexpr double kDetentReleaseRatio = 1.5;

    static constexpr double kDetentReleaseLimitSemis = 1.0;

    static constexpr int kInterpMargin = 4;

    static constexpr double kDriftMaxDepthPercent = 0.5;

    static constexpr std::uint32_t kDriftSeed = 0x57484D59u;  // 'WHMY'

    static constexpr double kDcBlockerCornerHz = 5.0;

    static constexpr double kClickBound = 0.25;

    static constexpr double kWorstCaseGain = 2.23606797749979;  // √5
    static_assert(kWorstCaseGain > 2.0, "the wet leg alone can reach 2x");

    static constexpr double kDcBlockerPeakGain = 2.0;

    double dc_blocker_magnitude_peak() const { return 2.0 / (1.0 + dc_pole()); }

    static constexpr double kDefaultSampleRate = 48000.0;

    static constexpr double default_mix_for(PedalMode mode) {
        switch (mode) {
            case PedalMode::harmony: return 0.5;
            case PedalMode::detune: return 0.4;
            case PedalMode::whammy:
            case PedalMode::dive:
            default: return 1.0;
        }
    }

    static constexpr bool mode_uses_detents(PedalMode mode) {
        return mode == PedalMode::whammy || mode == PedalMode::harmony;
    }
 
    // ── Lifecycle ─────────────────────────────────────────────────────────
 
    PitchShifterT() {
        dc_.set_pole(static_cast<SampleType>(dc_pole()));
        drift_.set_seed(kDriftSeed);
        drift_.set_depth_percent(0.0);
        glide_.set_mode(SlewMode::linear);
        glide_.set_rise_ms(kGlideMsDefault);
        glide_.set_fall_ms(kGlideMsDefault);
        update_window();
        glide_.set_immediate(target_semitones());
        semitones_ = target_semitones();
        update_ratio();
    }

    void prepare(double sample_rate) {
        sample_rate_ = (std::isfinite(sample_rate) && sample_rate > 0.0)
                           ? sample_rate
                           : kDefaultSampleRate;
 
        const int capacity =
            static_cast<int>(
                std::ceil(units::ms_to_samples(kWindowMsMax, sample_rate_))) +
            2 * kInterpMargin;
        line_.prepare(capacity);
        max_read_samples_ =
            static_cast<double>(capacity - kInterpMargin);
 
        glide_.prepare(sample_rate_);
        drift_.prepare(sample_rate_);
        dc_.set_pole(static_cast<SampleType>(dc_pole()));
        update_window();
        reset();
    }

    void reset() {
        line_.reset();
        dc_.reset();
        drift_.reset();
        phase_ = 0.0;
        window_a_ = window_b_ = window_samples_;
        glide_.set_immediate(target_semitones());
        semitones_ = target_semitones();
        update_ratio();
    }

    void discard_history() noexcept {
        line_.discard_history();
        dc_.reset();
        drift_.reset();
        phase_ = 0.0;
        window_a_ = window_b_ = window_samples_;
        glide_.set_immediate(target_semitones());
        semitones_ = target_semitones();
        update_ratio();
    }
 
    // ── Control surface ───────────────────────────────────────────────────

    void set_shift_source(ShiftSource source) { source_ = source; }
    ShiftSource shift_source() const { return source_; }

    void set_shift_semitones(double semitones) {
        if (!std::isfinite(semitones)) return;
        shift_semitones_ = clamp_finite(semitones, kShiftSemisMin, kShiftSemisMax);
    }
    double shift_semitones() const { return shift_semitones_; }

    void set_pedal(double e01) {
        if (!std::isfinite(e01)) return;
        pedal_ = clamp_finite(e01, 0.0, 1.0);
    }
    double pedal() const { return pedal_; }

    void set_pedal_mode(PedalMode mode) { mode_ = mode; }
    PedalMode pedal_mode() const { return mode_; }

    void set_targets(double heel, double toe) {
        if (!std::isfinite(heel) || !std::isfinite(toe)) return;
        heel_semis_ = clamp_finite(heel, kShiftSemisMin, kShiftSemisMax);
        toe_semis_ = clamp_finite(toe, kShiftSemisMin, kShiftSemisMax);
    }

    void set_harmony(double a, double b) {
        if (!std::isfinite(a) || !std::isfinite(b)) return;
        interval_a_semis_ = clamp_finite(a, -24.0, 24.0);
        interval_b_semis_ = clamp_finite(b, -24.0, 24.0);
    }
 
    void set_detune_cents(double cents) {
        if (!std::isfinite(cents)) return;
        detune_cents_ = clamp_finite(cents, -kDetuneCentsMax, kDetuneCentsMax);
    }
 
    void set_dive_floor_semis(double semitones) {
        if (!std::isfinite(semitones)) return;
        dive_floor_semis_ =
            clamp_finite(semitones, kDiveFloorSemisMin, kDiveFloorSemisMax);
    }

    void set_window_ms(double ms) {
        if (!std::isfinite(ms)) return;
        window_ms_ = clamp_finite(ms, kWindowMsMin, kWindowMsMax);
        update_window();
    }
    double window_ms() const { return window_ms_; }

    void set_glide_ms(double up_ms, double down_ms) {
        if (!std::isfinite(up_ms) || !std::isfinite(down_ms)) return;
        glide_.set_rise_ms(clamp_finite(up_ms, kGlideMsMin, kGlideMsMax));
        glide_.set_fall_ms(clamp_finite(down_ms, kGlideMsMin, kGlideMsMax));
    }
    double glide_up_ms() const { return glide_.rise_ms(); }
    double glide_down_ms() const { return glide_.fall_ms(); }

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

    void set_detents(bool on) {
        detents_ = on;
        if (!on) detent_held_ = false;
    }
    bool detents() const { return detents_; }
 
    void set_interp(PitchInterp interp) { interp_ = interp; }
    PitchInterp interp() const { return interp_; }

    void set_drift_depth(double d01) {
        if (!std::isfinite(d01)) return;
        drift_depth_ = clamp_finite(d01, 0.0, 1.0);
        drift_.set_depth_percent(drift_depth_ * kDriftMaxDepthPercent);
    }
    double drift_depth() const { return drift_depth_; }

    void snap_to_target() {
        glide_.set_immediate(target_semitones());
        semitones_ = target_semitones();
        update_ratio();
    }
 
    // ── Reporting ─────────────────────────────────────────────────────────

    double target_semitones() const {
        if (source_ == ShiftSource::direct)
            return std::clamp(shift_semitones_, kSemitonesFloor, kSemitonesCeil);
        return std::clamp(detented(pedal_law(pedal_)), kSemitonesFloor,
                          kSemitonesCeil);
    }

    double pedal_law(double e01) const {
        const double e = std::clamp(e01, 0.0, 1.0);
        switch (mode_) {
            case PedalMode::harmony:
                return lerp(interval_a_semis_, interval_b_semis_, e);
            case PedalMode::detune:
                return (detune_cents_ / units::kCentsPerSemitone) * e;
            case PedalMode::dive:
                return lerp(0.0, dive_floor_semis_, e);
            case PedalMode::whammy:
            default:
                return lerp(heel_semis_, toe_semis_, e);
        }
    }

    double current_semitones() const { return semitones_; }

    double current_ratio() const { return effective_ratio_; }

    double warble_hz() const {
        return window_ms_ > 0.0
                   ? std::abs(1.0 - effective_ratio_) * 1000.0 / window_ms_
                   : 0.0;
    }

    double tap_phase_pi(double hz) const {
        return hz * window_ms_ / 1000.0;
    }

    double window_samples() const { return window_samples_; }

    int latency_samples() const {
        return static_cast<int>(
            std::lround(window_ms_ * sample_rate_ / 2000.0));
    }
 
    // ── Audio ─────────────────────────────────────────────────────────────

    SampleType process(SampleType x) {
        if (!std::isfinite(static_cast<double>(x))) {
            discard_history();
            return SampleType{0};
        }
        const double dry = static_cast<double>(x);
        const double wet = advance(dry);
        double dry_gain = 0.0;
        double wet_gain = 0.0;
        crossfade_gains(mix_, CrossfadeGainLaw::EqualPower, dry_gain, wet_gain);
        return static_cast<SampleType>(dry_gain * dry + wet_gain * wet);
    }

    SampleType process_wet(SampleType x) {
        if (!std::isfinite(static_cast<double>(x))) {
            discard_history();
            return SampleType{0};
        }
        return static_cast<SampleType>(advance(static_cast<double>(x)));
    }
 
private:
    static constexpr double kPi = 3.14159265358979323846;
 
    static double lerp(double a, double b, double t) { return a + (b - a) * t; }
 
    static double clamp_finite(double v, double lo, double hi) {
        if (!std::isfinite(v)) return lo;
        return std::clamp(v, lo, hi);
    }

    double detented(double raw) const {
        if (!detents_ || !mode_uses_detents(mode_)) {
            detent_held_ = false;
            return raw;
        }
 
        const double release =
            std::min(kDetentSnapSemis * kDetentReleaseRatio,
                     kDetentReleaseLimitSemis);
 
        if (detent_held_) {
            const double held = kDetentTable[detent_index_];
            if (std::abs(raw - held) <= release) return held;
            detent_held_ = false;
        }
 
        int nearest = 0;
        double best = std::abs(raw - kDetentTable[0]);
        for (int i = 1; i < kDetentCount; ++i) {
            const double d = std::abs(raw - kDetentTable[i]);
            if (d < best) {
                best = d;
                nearest = i;
            }
        }
        if (best <= kDetentSnapSemis) {
            detent_held_ = true;
            detent_index_ = nearest;
            return kDetentTable[nearest];
        }
        return raw;
    }
 
    void update_window() {
        window_samples_ = units::ms_to_samples(window_ms_, sample_rate_);
        if (window_a_ <= 0.0) window_a_ = window_samples_;
        if (window_b_ <= 0.0) window_b_ = window_samples_;
    }
 
    void update_ratio() {
        ratio_ = units::semitones_to_ratio(semitones_);
        effective_ratio_ = ratio_;
    }

    double dc_pole() const {
        constexpr double kTwoPi = 2.0 * kPi;
        const double p = 1.0 - kTwoPi * kDcBlockerCornerHz / sample_rate_;
        return std::clamp(p, 0.0, 0.9999);
    }

    double read_tap(double delay_samples) const {
        // Not `std::clamp`: before `prepare` the two bounds cross, and a
        // crossed `clamp` is undefined behaviour rather than a zero read.
        //
        // The low bound is what keeps the stencil off the buffer seam. It bites
        // only for `p < kInterpMargin/L` — 0.2 % of a default window — where the
        // tap's own crossfade weight is already below `sin²(π·0.002) ≈ 4e-5`
        // (−88 dB), so the momentary ratio error it causes is inaudible by
        // construction rather than by tolerance.
        if (max_read_samples_ <= static_cast<double>(kInterpMargin)) return 0.0;
        const double d = std::max(static_cast<double>(kInterpMargin),
                                  std::min(delay_samples, max_read_samples_));
        const int i = static_cast<int>(std::floor(d));
        const double frac = d - static_cast<double>(i);
        const double y0 = static_cast<double>(line_.read(i));
        const double y1 = static_cast<double>(line_.read(i + 1));
        if (interp_ == PitchInterp::linear)
            return Interpolator::linear(frac, y0, y1);
        const double ym1 = static_cast<double>(line_.read(i - 1));
        const double y2 = static_cast<double>(line_.read(i + 2));
        return Interpolator::lagrange(frac, ym1, y0, y1, y2);
    }
 
    static double frac1(double v) { return v - std::floor(v); }

    double advance(double x) {
        // An unprepared instance emits silence rather than faulting. The
        // contract says `prepare` must precede `process`, but `DelayLineT::push`
        // writes its buffer unguarded, so the penalty for a host that calls
        // `process` early — which real hosts do — would be an out-of-bounds
        // write rather than a diagnosable silence. Guarding the read while
        // leaving the write to fault would be the worst of both.
        if (max_read_samples_ <= static_cast<double>(kInterpMargin)) return 0.0;
 
        line_.push(static_cast<SampleType>(x));
 
        // Control cadence: pedal law → detents → glide → r. `semitones_to_ratio`
        // is a `pow`, so it is recomputed only when the glide actually moved.
        const double slewed = glide_.process(
            std::clamp(target_semitones(), kSemitonesFloor, kSemitonesCeil));
        if (slewed != semitones_) {
            semitones_ = slewed;
            update_ratio();
        }
        effective_ratio_ = ratio_;
        if (drift_depth_ > 0.0)
            effective_ratio_ *= static_cast<double>(drift_.next());
        const double r = effective_ratio_;
 
        // Two taps, half a window apart, each on its own latched window length.
        const double pa = phase_;
        const double pb = frac1(phase_ + 0.5);
        const double tap_a = read_tap(pa * window_a_);
        const double tap_b = read_tap(pb * window_b_);
 
        // Eq. 3.4 through the house law. `1 − wA` for the second weight keeps
        // `wA + wB ≡ 1` EXACT regardless of how `sin` rounds, which is what
        // bounds the wet leg by the buffer peak.
        const double s = std::sin(kPi * pa);
        double w_b = 0.0;
        double w_a = 0.0;
        crossfade_gains(s * s, CrossfadeGainLaw::EqualGain, w_b, w_a);
        const double wet = static_cast<double>(
            dc_.process(static_cast<SampleType>(w_a * tap_a + w_b * tap_b)));
 
        // Advance the sawtooth (Eq. 3.3) and latch any pending window change at
        // each tap's own zero crossing, where its delay and its weight are both
        // zero. `window_a_` drives the increment, so tap A is always exactly on
        // ratio; tap B is only ever off during the half cycle after a change.
        const double dphi = window_a_ > 0.0 ? (1.0 - r) / window_a_ : 0.0;
        const double pa_next = frac1(phase_ + dphi);
        const double pb_next = frac1(pa_next + 0.5);
        const bool rising = dphi > 0.0;
        const bool wrapped_a = rising ? (pa_next < pa) : (pa_next > pa);
        const bool wrapped_b = rising ? (pb_next < pb) : (pb_next > pb);
        if (wrapped_a) window_a_ = window_samples_;
        if (wrapped_b) window_b_ = window_samples_;
        phase_ = pa_next;
 
        return wet;
    }
 
    // ── Composed primitives ───────────────────────────────────────────────
    DelayLineT<SampleType> line_{};
    DcBlocker<SampleType> dc_{};
    ConstantTimeSlewLimiterT<double> glide_{};
    DriftT<double> drift_{};
 
    // ── Configuration ─────────────────────────────────────────────────────
    double sample_rate_ = kDefaultSampleRate;
    PedalMode mode_ = PedalMode::whammy;
    ShiftSource source_ = ShiftSource::pedal;
    PitchInterp interp_ = PitchInterp::linear;
 
    double pedal_ = 0.0;
    double shift_semitones_ = 0.0;
    double heel_semis_ = kHeelSemisDefault;
    double toe_semis_ = kToeSemisDefault;
    double interval_a_semis_ = kIntervalASemisDefault;
    double interval_b_semis_ = kIntervalBSemisDefault;
    double detune_cents_ = kDetuneCentsDefault;
    double dive_floor_semis_ = kDiveFloorSemisDefault;
    double window_ms_ = kWindowMsDefault;
    double mix_ = 1.0;
    double drift_depth_ = 0.0;
    bool detents_ = false;
 
    // ── Running state ─────────────────────────────────────────────────────
    double window_samples_ = 0.0;
    double window_a_ = 0.0;
    double window_b_ = 0.0;
    double max_read_samples_ = static_cast<double>(kInterpMargin);
    double phase_ = 0.0;
    double semitones_ = 0.0;
    double ratio_ = 1.0;
    double effective_ratio_ = 1.0;
 
    // Schmitt state for the detent capture. Mutable because `target_semitones`
    // is the natural place to read the law from and callers expect it to be a
    // query; the state it carries is the hysteresis memory, not a result.
    mutable bool detent_held_ = false;
    mutable int detent_index_ = 0;
};
 
using PitchShifter = PitchShifterT<float>;
using PitchShifter64 = PitchShifterT<double>;
 
}  // namespace pulp::signal