lfo.hpp

Go to the documentation of this file.

// sbl/widgets/mod/lfo.hpp — Low Frequency Oscillator (Audio Stack — Widgets)
//
// Sub-audio modulation source. Composes PhaseAccumulator + WavetableReader
// with amplitude scaling. Output is normalized bipolar (-depth to +depth).
//
// The LFO outputs a domain-neutral signal — it doesn't know what it's
// modulating. The conversion to domain-specific units (Hz, octaves, etc.)
// belongs at the modulation application point, not here. This matches the
// analog modular convention: LFO outputs a voltage, the destination module
// interprets it via its exponential converter (V/Oct) or linear VCA.
//
// set_depth() controls output amplitude: 1.0 (default) = full ±1.0 swing.
// Do NOT encode destination units into depth (e.g., set_depth(200.0f) for
// "±200 Hz" — this breaks composability). Instead, use depth for amplitude
// scaling and apply domain conversion at the destination:
//
//   // Correct: normalized LFO + exponential modulation at destination
//   lfo.set_depth(1.0f);           // ±1.0 normalized signal (default)
//   filter.process_modulated(buf, n, lfo_buf, cutoff, 2.0f);  // ±2 octaves
//
//   // Also correct: attenuated LFO for subtle modulation
//   lfo.set_depth(0.3f);           // ±0.3 normalized signal
//   filter.process_modulated(buf, n, lfo_buf, cutoff, 4.0f);  // ±1.2 octaves
//
// See FDP-031 (Signal layer) and RPT-014 for architectural rationale.
//
// Usage:
//   sbl::widgets::mod::Lfo<1024> lfo;
//   lfo.set_wavetable(sbl::dsp::lut::sin_1024);
//   lfo.set_rate(2.0f);       // 2 Hz
//   lfo.set_depth(0.5f);      // ±0.5 output amplitude
//   lfo.process(buf, frames);
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/phase.hpp>
#include <sbl/dsp/wavetable.hpp>
 
namespace sbl::widgets::mod {
 
template<uint16_t TableSize>
class Lfo {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /** @brief Set wavetable (must have guard points for interpolation) */
    void set_wavetable(const float* table) { reader_.set_table(table); }
 
    /**
     * @brief Set LFO rate in Hz
     * @param freq_hz Rate in Hz (e.g., 2.0f)
     * @param sr Sample rate (default 48000)
     */
    void set_rate(float freq_hz, float sr = 48000.0f) {
        phase_.set_increment(dsp::PhaseAccumulator::freq_to_inc(freq_hz, sr));
    }
 
    /** @brief Set phase increment directly */
    void set_increment(uint32_t inc) { phase_.set_increment(inc); }
 
    /**
     * @brief Set output amplitude (depth)
     *
     * Controls the bipolar output range: output = wavetable * depth.
     * Default is 1.0 — full ±1.0 normalized swing. Use values in [0, 1]
     * for amplitude scaling. The caller applies domain conversion
     * (exponential for frequency, linear for amplitude) at the
     * modulation destination.
     *
     * @param depth Output amplitude (1.0 = full ±1.0 swing)
     */
    void set_depth(float depth) { depth_ = depth; }
 
    /**
     * @brief Generate modulation signal (bipolar: -depth to +depth)
     * @param out Output buffer (float)
     * @param frames Number of samples
     */
    void process(float* out, uint16_t frames) {
        for (uint16_t i = 0; i < frames; ++i) {
            phase_.advance();
            out[i] = reader_.read(phase_.phase()) * depth_;
        }
    }
 
    /** @brief Hard sync — reset phase to zero */
    void sync() { phase_.reset(); }
 
    /** @brief Current LFO value (bipolar, float) */
    float value() const {
        return reader_.read(phase_.phase()) * depth_;
    }
 
    /** @brief Current phase */
    uint32_t phase() const { return phase_.phase(); }
 
    /** @brief Current phase increment */
    uint32_t increment() const { return phase_.increment(); }
 
private:
    dsp::PhaseAccumulator phase_;
    dsp::WavetableReader<TableSize> reader_;
    float depth_ = 1.0f;
};
 
} // namespace sbl::widgets::mod