vibrato.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/delay_line.hpp>
#include <pulp/signal/envelope.hpp>
#include <pulp/signal/interpolator.hpp>
#include <pulp/signal/lfo.hpp>
#include <pulp/signal/tpt_filter.hpp>
#include <pulp/signal/units.hpp>
#include <pulp/signal/vactrol.hpp>
 
#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>
 
namespace pulp::signal {

template <typename SampleType = float>
class DelayVibratoT {
public:
    static constexpr double kDefaultRateHz = 5.5;
    static constexpr double kMinRateHz = 0.1;
    static constexpr double kMaxRateHz = 20.0;

    static constexpr double kDefaultDepthCents = 20.0;
    static constexpr double kMaxDepthCents = 100.0;

    static constexpr double kBaseDelayHeadroom = 2.0;

    static constexpr double kMinBaseDelaySamples = 2.0;

    static constexpr int kInterpolatorMarginSamples = 4;

    static constexpr double kMaxLifecycleMs = 5000.0;

    static constexpr double kInterpolatorPeakGain = 1.25;
 
    DelayVibratoT() {
        lfo_.set_wave(LfoWave::sine);
        lifecycle_.set_curve(0.0);
        lifecycle_.set_attack_ms(0.0);
        lifecycle_.set_hold_ms(0.0);
        lifecycle_.set_decay_ms(0.0);
        lifecycle_.set_sustain(1.0);
        update();
    }

    void prepare(double sample_rate) {
        sample_rate_ = sample_rate > 0.0 ? sample_rate : sample_rate_;
        lfo_.prepare(sample_rate_);
        lifecycle_.prepare(sample_rate_);
        line_.prepare(worst_case_read_index(sample_rate_));
        update();
        arm();
    }
 
    void set_rate_hz(double hz) {
        if (!std::isfinite(hz)) return;
        rate_hz_ = std::clamp(hz, kMinRateHz, kMaxRateHz);
        lfo_.set_rate_hz(rate_hz_);
        update();
    }
 
    double rate_hz() const { return rate_hz_; }

    void set_depth_cents(double cents) {
        if (!std::isfinite(cents)) return;
        depth_cents_ = std::clamp(cents, 0.0, kMaxDepthCents);
        update();
    }
 
    double depth_cents() const { return depth_cents_; }

    void set_delay_ms(double ms) {
        if (!std::isfinite(ms)) return;
        delay_ms_ = std::clamp(ms, 0.0, kMaxLifecycleMs);
        lifecycle_.set_delay_ms(delay_ms_);
        arm();
    }

    void set_fade_in_ms(double ms) {
        if (!std::isfinite(ms)) return;
        fade_in_ms_ = std::clamp(ms, 0.0, kMaxLifecycleMs);
        lifecycle_.set_attack_ms(fade_in_ms_);
        arm();
    }

    double base_delay_samples() const { return base_delay_samples_; }

    double modulation_amplitude_samples() const { return amplitude_samples_; }

    double depth_envelope() const { return lifecycle_active_ ? depth_env_ : 1.0; }

    std::size_t latency_samples() const {
        return static_cast<std::size_t>(
            std::ceil(base_delay_samples_ + amplitude_samples_));
    }
 
    void reset() {
        line_.reset();
        lfo_.reset();
        depth_env_ = 0.0;
        arm();
    }
 
    void discard_history() noexcept {
        line_.discard_history();
        lfo_.reset();
        depth_env_ = 0.0;
        arm();
    }
 
    SampleType process(SampleType input) {
        if (!std::isfinite(static_cast<double>(input))) {
            discard_history();
            return SampleType{0};
        }
        const double env = lifecycle_active_ ? advance_lifecycle() : 1.0;
        const double modulation = static_cast<double>(lfo_.next());
        const double delay = base_delay_samples_ + amplitude_samples_ * env * modulation;
 
        line_.push(input);
 
        const int index = static_cast<int>(std::floor(delay));
        const double frac = delay - static_cast<double>(index);
        // Weights in double even when the samples are float: the fractional
        // position is a double, and rounding it to float would put a
        // quantisation staircase directly on the modulation the effect exists
        // to produce.
        const double interpolated = Interpolator::lagrange(
            frac,
            static_cast<double>(line_.read(index - 1)),
            static_cast<double>(line_.read(index)),
            static_cast<double>(line_.read(index + 1)),
            static_cast<double>(line_.read(index + 2)));
        return static_cast<SampleType>(interpolated);
    }
 
private:
    static constexpr double kTwoPi = 6.283185307179586476925286766559;

    static double amplitude_seconds(double cents, double rate_hz) {
        return (units::cents_to_ratio(cents) - 1.0) / (kTwoPi * rate_hz);
    }

    static int worst_case_read_index(double sample_rate) {
        const double amplitude = amplitude_seconds(kMaxDepthCents, kMinRateHz) * sample_rate;
        const double base = std::max(kBaseDelayHeadroom * amplitude, kMinBaseDelaySamples);
        return static_cast<int>(std::ceil(base + amplitude)) + kInterpolatorMarginSamples;
    }
 
    void update() {
        amplitude_samples_ = amplitude_seconds(depth_cents_, rate_hz_) * sample_rate_;
        base_delay_samples_ =
            std::max(kBaseDelayHeadroom * amplitude_samples_, kMinBaseDelaySamples);
    }
 
    void arm() {
        lifecycle_active_ = delay_ms_ > 0.0 || fade_in_ms_ > 0.0;
        depth_env_ = 0.0;
        if (lifecycle_active_) lifecycle_.gate_on();
    }
 
    double advance_lifecycle() {
        depth_env_ = static_cast<double>(lifecycle_.next());
        return depth_env_;
    }
 
    double sample_rate_ = 44100.0;
    double rate_hz_ = kDefaultRateHz;
    double depth_cents_ = kDefaultDepthCents;
    double delay_ms_ = 0.0;
    double fade_in_ms_ = 0.0;
 
    double amplitude_samples_ = 0.0;
    double base_delay_samples_ = kMinBaseDelaySamples;
    double depth_env_ = 0.0;
    bool lifecycle_active_ = false;
 
    DelayLineT<SampleType> line_{};
    EffectLfoT<double> lfo_{};
    DahdsrT<double> lifecycle_{};
};
 
using DelayVibrato = DelayVibratoT<float>;
using DelayVibrato64 = DelayVibratoT<double>;

template <typename SampleType = float>
class PhaseVibratoT {
public:
    static constexpr double kDefaultRateHz = 0.8;
    static constexpr double kMinRateHz = 0.05;
    static constexpr double kMaxRateHz = 10.0;

    static constexpr double kDefaultDepth = 0.6;

    static constexpr double kSweepOctaves = 1.5;

    static constexpr double kDefaultCenterHz = 500.0;
    static constexpr double kMinCenterHz = 200.0;
    static constexpr double kMaxCenterHz = 2000.0;

    static constexpr int kDefaultStageCount = 2;
    static constexpr int kMaxStages = 4;

    static constexpr double kDefaultMix = 0.5;

    static constexpr double kSinusoidalGainBound = 1.0;
 
    PhaseVibratoT() {
        lfo_.set_wave(LfoWave::sine);
        lfo_.set_rate_hz(rate_hz_);
    }
 
    void prepare(double sample_rate) {
        sample_rate_ = sample_rate > 0.0 ? sample_rate : sample_rate_;
        lfo_.prepare(sample_rate_);
        for (auto& stage : stages_) stage.prepare(static_cast<SampleType>(sample_rate_));
    }
 
    void set_rate_hz(double hz) {
        if (!std::isfinite(hz)) return;
        rate_hz_ = std::clamp(hz, kMinRateHz, kMaxRateHz);
        lfo_.set_rate_hz(rate_hz_);
    }
 
    double rate_hz() const { return rate_hz_; }
 
    void set_depth(double depth) {
        if (!std::isfinite(depth)) return;
        depth_ = std::clamp(depth, 0.0, 1.0);
    }
    double depth() const { return depth_; }
 
    void set_center_hz(double hz) {
        if (!std::isfinite(hz)) return;
        center_hz_ = std::clamp(hz, kMinCenterHz, kMaxCenterHz);
    }
    double center_hz() const { return center_hz_; }

    void set_stage_count(int count) {
        const int clamped = std::clamp(count, 1, kMaxStages);
        for (int i = stage_count_; i < clamped; ++i) stages_[static_cast<std::size_t>(i)].reset();
        stage_count_ = clamped;
    }
 
    int stage_count() const { return stage_count_; }
 
    void set_mix(double mix) {
        if (!std::isfinite(mix)) return;
        mix_ = std::clamp(mix, 0.0, 1.0);
    }
    double mix() const { return mix_; }

    double corner_hz() const { return corner_hz_; }

    std::size_t latency_samples() const { return 0; }
 
    void reset() {
        lfo_.reset();
        for (auto& stage : stages_) stage.reset();
        corner_hz_ = center_hz_;
    }
 
    SampleType process(SampleType input) {
        if (!std::isfinite(static_cast<double>(input))) {
            reset();
            return SampleType{0};
        }
        const double modulation = static_cast<double>(lfo_.next());
        corner_hz_ = center_hz_ * std::exp2(depth_ * kSweepOctaves * modulation);
 
        double shifted = static_cast<double>(input);
        for (int i = 0; i < stage_count_; ++i) {
            auto& stage = stages_[static_cast<std::size_t>(i)];
            // The corner moves every sample, so the coefficient is recomputed
            // every sample. Sharing one `tan` across stages would need a
            // coefficient setter the shared TPT filter does not expose; paying
            // it per stage keeps this composed rather than forked.
            stage.set_cutoff(static_cast<SampleType>(corner_hz_));
            shifted = static_cast<double>(
                stage.process_allpass(static_cast<SampleType>(shifted)));
        }
 
        const double direct = static_cast<double>(input);
        return static_cast<SampleType>(direct + mix_ * (shifted - direct));
    }
 
private:
    double sample_rate_ = 44100.0;
    double rate_hz_ = kDefaultRateHz;
    double depth_ = kDefaultDepth;
    double center_hz_ = kDefaultCenterHz;
    double mix_ = kDefaultMix;
    int stage_count_ = kDefaultStageCount;
    double corner_hz_ = kDefaultCenterHz;
 
    EffectLfoT<double> lfo_{};
    std::array<TptFilterT<SampleType>, kMaxStages> stages_{};
};
 
using PhaseVibrato = PhaseVibratoT<float>;
using PhaseVibrato64 = PhaseVibratoT<double>;

template <typename SampleType = float>
class UniVibeT {
public:
    enum class Mode : std::uint8_t { vibrato, chorus };
 
    static constexpr int kStageCount = 4;

    static constexpr std::array<double, kStageCount> kStageBaseHz{200.0, 430.0, 900.0, 1900.0};

    static constexpr double kDefaultRateHz = 3.0;
    static constexpr double kMinRateHz = 0.3;
    static constexpr double kMaxRateHz = 8.0;

    static constexpr double kDefaultDepth = 0.7;

    static constexpr double kSweepOctaves = 1.0;

    static constexpr double kVactrolRiseMs = 0.8;
    static constexpr double kVactrolFallMs = 35.0;

    static constexpr double kControlExponent = 1.2;

    static constexpr double kVibratoMix = 0.9;

    static constexpr double kChorusBlend = 0.5;

    static constexpr double kSinusoidalGainBound = 1.0;
 
    UniVibeT() {
        lfo_.set_wave(LfoWave::sine);
        lfo_.set_rate_hz(rate_hz_);
        vactrol_.set_rise_ms(kVactrolRiseMs);
        vactrol_.set_fall_ms(kVactrolFallMs);
        corners_ = kStageBaseHz;
    }
 
    void prepare(double sample_rate) {
        sample_rate_ = sample_rate > 0.0 ? sample_rate : sample_rate_;
        lfo_.prepare(sample_rate_);
        vactrol_.prepare(sample_rate_);
        for (auto& stage : stages_) stage.prepare(static_cast<SampleType>(sample_rate_));
    }
 
    void set_rate_hz(double hz) {
        if (!std::isfinite(hz)) return;
        rate_hz_ = std::clamp(hz, kMinRateHz, kMaxRateHz);
        lfo_.set_rate_hz(rate_hz_);
    }
 
    double rate_hz() const { return rate_hz_; }
 
    void set_depth(double depth) {
        if (!std::isfinite(depth)) return;
        depth_ = std::clamp(depth, 0.0, 1.0);
    }
    double depth() const { return depth_; }
 
    void set_mode(Mode mode) { mode_ = mode; }
    Mode mode() const { return mode_; }

    double control() const { return vactrol_.control(); }

    double stage_corner_hz(int index) const {
        return corners_[static_cast<std::size_t>(std::clamp(index, 0, kStageCount - 1))];
    }

    static double corner_scale(double control, double depth) {
        return std::exp2(depth * kSweepOctaves * (2.0 * std::pow(control, kControlExponent) - 1.0));
    }
 
    std::size_t latency_samples() const { return 0; }
 
    void reset() {
        lfo_.reset();
        vactrol_.reset();
        for (auto& stage : stages_) stage.reset();
        corners_ = kStageBaseHz;
    }
 
    void process(SampleType input, SampleType& out_left, SampleType& out_right) {
        if (!std::isfinite(static_cast<double>(input))) {
            reset();
            out_left = out_right = SampleType{0};
            return;
        }
        const double lamp = static_cast<double>(lfo_.next_unipolar());
        const double control = vactrol_.process(lamp);
        const double scale = corner_scale(control, depth_);
 
        double shifted = static_cast<double>(input);
        for (int i = 0; i < kStageCount; ++i) {
            const auto slot = static_cast<std::size_t>(i);
            corners_[slot] = kStageBaseHz[slot] * scale;
            stages_[slot].set_cutoff(static_cast<SampleType>(corners_[slot]));
            shifted = static_cast<double>(
                stages_[slot].process_allpass(static_cast<SampleType>(shifted)));
        }
 
        const double direct = static_cast<double>(input);
        if (mode_ == Mode::vibrato) {
            const auto wet =
                static_cast<SampleType>(direct + kVibratoMix * (shifted - direct));
            out_left = wet;
            out_right = wet;
            return;
        }
        // Chorus splits the paths: one output stays untouched, which is why it
        // is asserted bit-exact rather than to a tolerance.
        out_left = input;
        out_right = static_cast<SampleType>(direct + kChorusBlend * (shifted - direct));
    }
 
private:
    double sample_rate_ = 44100.0;
    double rate_hz_ = kDefaultRateHz;
    double depth_ = kDefaultDepth;
    Mode mode_ = Mode::vibrato;
 
    std::array<double, kStageCount> corners_{};
 
    EffectLfoT<double> lfo_{};
    VactrolConditionerT<SampleType> vactrol_{};
    std::array<TptFilterT<SampleType>, kStageCount> stages_{};
};
 
using UniVibe = UniVibeT<float>;
using UniVibe64 = UniVibeT<double>;
 
}  // namespace pulp::signal