analog_drift.hpp

Go to the documentation of this file.

// sbl/dsp/comp/analog_drift.hpp — Analog oscillator drift simulation
//
// Slow stochastic pitch wander that simulates analog oscillator instability.
// Brownian random walk with mean reversion, heavily smoothed to produce
// sub-Hz movement in the ±cents range.
//
// Each instance has an independent PRNG — two instances produce uncorrelated
// drift, which is critical for realistic beating between oscillators.
//
// Call process() at control rate (~200 Hz). Output is in semitones.
// Multiply by the oscillator's frequency ratio to apply:
//   float freq = base_hz * semitones_to_ratio(drift.process(amount));
//
// Usage:
//   sbl::dsp::comp::AnalogDrift drift(42);  // unique seed per instance
//   drift.set_rate(200.0f);              // control rate in Hz
//   float offset = drift.process(0.05f); // ±5 cents peak, in semitones
 
#ifndef SBL_DSP_COMP_ANALOG_DRIFT_HPP_
#define SBL_DSP_COMP_ANALOG_DRIFT_HPP_
 
#include <sbl/dsp/primitives/rng.hpp>
 
namespace sbl::dsp::comp {
 
class AnalogDrift {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /// Construct with PRNG seed. Use a different seed for each instance.
    explicit AnalogDrift(uint32_t seed = 1) : rng_(seed) {}
 
    /// Set the control rate in Hz. Adjusts walk step and smoothing
    /// to maintain consistent drift character regardless of call rate.
    /// Call once at init, not per-sample.
    void set_rate(float control_rate_hz) {
        // Scale walk step inversely with rate so drift speed is rate-independent.
        // At 200 Hz: step_scale = 0.01, at 1000 Hz: step_scale = 0.002
        step_scale_ = 2.0f / control_rate_hz;
 
        // Mean-revert decay per tick. Target time constant ~2 seconds.
        // decay = exp(-1 / (tau * rate)) ≈ 1 - 1/(tau * rate) for small values
        decay_ = 1.0f - 1.0f / (2.0f * control_rate_hz);
 
        // LP smoothing coefficient. Target time constant ~0.5 seconds.
        // Produces sub-Hz movement (the "slow wander" character).
        smooth_ = 1.0f / (0.5f * control_rate_hz);
    }
 
    /// Process one control tick.
    /// @param amount Peak deviation in semitones (0.05 = ±5 cents)
    /// @return Pitch offset in semitones
    float process(float amount) {
        // Brownian walk: accumulate small random steps
        walk_ += rng_.bipolar() * step_scale_;
 
        // Mean reversion: prevent unbounded wander
        walk_ *= decay_;
 
        // Heavy LP smoothing: sub-Hz movement
        filtered_ += smooth_ * (walk_ - filtered_);
 
        return filtered_ * amount;
    }
 
    /// Current drift value (before amount scaling), for diagnostics.
    float value() const { return filtered_; }
 
    /// Reset drift state to zero.
    void reset() {
        walk_ = 0.0f;
        filtered_ = 0.0f;
    }
 
    /// Re-seed the PRNG (for test reproducibility).
    void seed(uint32_t s) { rng_.seed(s); }
 
private:
    primitives::Rng rng_;
    float walk_     = 0.0f;
    float filtered_ = 0.0f;
 
    // Rate-dependent coefficients (defaults for 200 Hz control rate)
    float step_scale_ = 0.01f;
    float decay_      = 0.9975f;
    float smooth_     = 0.01f;
};
 
} // namespace sbl::dsp::comp
 
#endif // SBL_DSP_COMP_ANALOG_DRIFT_HPP_