shaper.hpp

Go to the documentation of this file.

// sbl/dsp/widgets/shaper.hpp — Timbre-sculpting processor (Audio Stack — Widgets)
//
// Opinionated waveshaping processor for the "West Coast position" in a voice
// signal chain — between oscillator and filter. Composes bias, ADAA wavefold,
// warm saturation, output compensation, and dry/wet mix into a single widget.
//
// Inspired by the Make Noise 0-Coast Overtone circuit: a single depth knob
// sweeps continuously from pure fundamental through progressive harmonic
// enrichment to full-spectrum overtone saturation.
//
// Internal 2x oversampling around fold + WarmSaturator together.
// Linear interpolation upsample, [0.25, 0.5, 0.25] symmetric FIR decimation.
// Both nonlinearities run at 2x rate to suppress aliasing from harmonic
// generation.
//
// Signal flow:
//   input -> [+ bias] -> [* depth] -> 2x { WavefoldAA -> WarmSaturator }
//         -> [.25,.5,.25] decimate -> [* compensation] -> mix(dry, wet) -> output
//
// Signal Unit API (FDP-052):
//   Widgets expose normalized [0,1] inputs via _su() methods. The widget
//   owns internal mapping and parameter conditioning. Depth and bias use
//   ParameterInterpolator (per-sample linear ramp — correct for nonlinear
//   params). Drive and mix use OnePole smoothing.
//
// Usage (new — signal units):
//   sbl::dsp::widgets::Shaper shaper;
//   shaper.set_depth_su(0.3f);       // [0,1] → 1.0–10.0 (linear)
//   shaper.set_drive_su(0.2f);       // [0,1] → 1.0–4.0 (linear)
//   shaper.process(buf, frames);     // per-sample smoothed parameters
 
#ifndef SBL_DSP_WIDGETS_SHAPER_HPP_
#define SBL_DSP_WIDGETS_SHAPER_HPP_
 
#include <cmath>
#include <cstdint>
 
#include <sbl/dsp/primitives/parameter_smoother.hpp>
#include <sbl/dsp/primitives/parameter_interpolator.hpp>
#include <sbl/dsp/comp/warm_saturator.hpp>
#include <sbl/dsp/comp/wavefold_aa.hpp>
#include <sbl/dsp/types/fixed.hpp>
 
namespace sbl::dsp::widgets {
 
class Shaper {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    // === Parameter range constants (for test helpers) ===
    static constexpr float kMinDepth = 1.0f;
    static constexpr float kMaxDepth = 10.0f;
    static constexpr float kMinBias = -0.1f;
    static constexpr float kMaxBias = 0.1f;
    static constexpr float kMinDrive = 1.0f;
    static constexpr float kMaxDrive = 4.0f;
 
    Shaper() = default;
 
    // === Signal Unit API (FDP-052) ===
 
    /**
     * @brief Set fold depth from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 1.0–10.0
     *
     * Depth uses ParameterInterpolator (per-sample linear ramp) inside
     * process(), not exponential smoothing. This is correct for nonlinear
     * parameters where the first-sample spike from exponential smoothers
     * would cause audible clicks in the wavefolder.
     */
    void set_depth_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        float d = kMinDepth + su * (kMaxDepth - kMinDepth);
        target_depth_ = d;
        if (!depth_init_) {
            depth_ = d;
            depth_init_ = true;
        }
    }
 
    /**
     * @brief Set asymmetric bias from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to -0.1–0.1
     *
     * 0.5 = no bias (symmetric, odd harmonics only).
     * 0.0 = negative bias (-0.1), 1.0 = positive bias (+0.1).
     * Uses ParameterInterpolator internally (same rationale as depth).
     */
    void set_bias_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        float b = kMinBias + su * (kMaxBias - kMinBias);
        target_bias_ = b;
        if (!bias_init_) {
            bias_ = b;
            bias_init_ = true;
        }
    }
 
    /**
     * @brief Set saturation drive from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 1.0–4.0
     *
     * Smoothed via OnePole (20ms timbral settling).
     */
    void set_drive_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        float drive = kMinDrive + su * (kMaxDrive - kMinDrive);
        target_drive_ = drive;
        ensure_smoothers();
        if (!drive_init_) {
            op_drive_.reset(drive);
            drive_ = drive;
            drive_init_ = true;
        }
    }
 
    /**
     * @brief Set dry/wet mix from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — 0 = dry, 1 = full wet
     *
     * Smoothed via OnePole (15ms gain settling).
     */
    void set_mix_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        target_mix_ = su;
        ensure_smoothers();
        if (!mix_init_) {
            op_mix_.reset(su);
            mix_ = su;
            mix_init_ = true;
        }
    }
 
    /// Output level compensation: when true (default), output level stays
    /// roughly constant as depth increases. When false, higher depth = more
    /// level into downstream.
    void set_compensate(bool compensate) { compensate_ = compensate; }
 
    // --- Processing --------------------------------------------------------
 
    /// Process block in-place (mono).
    /// Per-sample ParameterInterpolator ramp for depth and bias.
    /// OnePole smoothing for drive and mix.
    /// When depth_mod is provided, additive depth modulation is applied
    /// per-sample on top of the ParameterInterpolator ramp.
    ///
    /// @param buf       Float audio buffer (modified in-place)
    /// @param frames    Number of samples
    /// @param depth_mod Depth modulation signal [-1,1] (nullptr = no modulation)
    /// @param mod_depth Modulation range in fold-depth units (e.g., 3.0 = ±3)
    void process(float* buf, uint16_t frames,
                 const float* depth_mod = nullptr, float mod_depth = 0.0f) {
        ensure_smoothers();
        float drive_target = target_drive_;
        float mix_target = target_mix_;
 
        // Per-sample linear ramp for depth and bias
        primitives::ParameterInterpolator depth_ramp(&depth_, target_depth_, frames);
        primitives::ParameterInterpolator bias_ramp(&bias_, target_bias_, frames);
 
        for (uint16_t i = 0; i < frames; ++i) {
            float d = depth_ramp.next();
            if (depth_mod != nullptr) {
                d += depth_mod[i] * mod_depth;
                if (d < 0.0f) d = 0.0f;
            }
            float bias = bias_ramp.next();
            float drive = op_drive_.process(drive_target);
            float mix = op_mix_.process(mix_target);
 
            float dry = buf[i];
            float x = dry + bias;
 
            if (d <= 1.0f) {
                // No folding — just bias + saturate
                x = saturator_.process(x, drive);
            } else {
                float x_scaled = x * d;
 
                // 2x oversample: linear interpolation upsample
                float x_mid = (os_prev_ + x_scaled) * 0.5f;
                os_prev_ = x_scaled;
 
                // Process fold + saturate at 2x rate
                float y0 = saturator_.process(fold_.process(x_mid), drive);
                float y1 = saturator_.process(fold_.process(x_scaled), drive);
 
                // [0.25, 0.5, 0.25] symmetric FIR decimation
                x = 0.25f * decim_prev_ + 0.5f * y0 + 0.25f * y1;
                decim_prev_ = y1;
 
                if (compensate_) {
                    x *= compensation_gain(d);
                }
            }
 
            buf[i] = dry + (x - dry) * mix;
        }
 
        // Sync cached state from smoothers
        drive_ = op_drive_.value();
        mix_ = op_mix_.value();
    }
 
    /// Reset internal state (WavefoldAA history + oversampling)
    void reset() {
        fold_.reset();
        os_prev_ = 0.0f;
        decim_prev_ = 0.0f;
    }
 
private:
    // Test-only access to engineering-unit setters
    friend struct ShaperTestAccess;
 
    /// Set fold depth directly — immediate, no smoothing (private)
    void set_depth(float depth) {
        depth_ = (depth < 0.0f) ? 0.0f : depth;
        target_depth_ = depth_;
        depth_init_ = true;
    }
 
    /// Set bias directly — immediate, no smoothing (private)
    void set_bias(float bias) {
        bias_ = bias;
        target_bias_ = bias;
        bias_init_ = true;
    }
 
    /// Set drive directly — immediate, no smoothing (private)
    void set_drive(float drive) {
        drive_ = (drive < 1.0f) ? 1.0f : drive;
        target_drive_ = drive_;
        op_drive_.reset(drive_);
        drive_init_ = true;
    }
 
    /// Set mix directly — immediate, no smoothing (private)
    void set_mix(float mix) {
        if (mix < 0.0f) mix = 0.0f;
        if (mix > 1.0f) mix = 1.0f;
        mix_ = mix;
        target_mix_ = mix;
        op_mix_.reset(mix);
        mix_init_ = true;
    }
 
    void ensure_smoothers() {
        if (!smoothers_configured_) {
            op_drive_.set_time_ms(20.0f, types::SAMPLE_RATE_F);
            op_mix_.set_time_ms(15.0f, types::SAMPLE_RATE_F);
            op_drive_.reset(target_drive_);
            op_mix_.reset(target_mix_);
            saturator_.set_asymmetry(0.1f);
            smoothers_configured_ = true;
        }
    }
 
    comp::WavefoldAA fold_;
    comp::WarmSaturator saturator_;
    float depth_ = 1.0f;
    float bias_ = 0.03f;
    float drive_ = 1.3f;
    float mix_ = 1.0f;
    bool compensate_ = true;
    float os_prev_ = 0.0f;      // Previous scaled input for 2x upsample
    float decim_prev_ = 0.0f;   // Previous oversampled output for FIR decimation
 
    // ParameterSmoother for drive and mix (FDP-052)
    primitives::ParameterSmoother op_drive_;
    primitives::ParameterSmoother op_mix_;
    float target_depth_ = 1.0f;
    float target_bias_ = 0.03f;
    float target_drive_ = 1.3f;
    float target_mix_ = 1.0f;
    bool depth_init_ = false;
    bool bias_init_ = false;
    bool drive_init_ = false;
    bool mix_init_ = false;
    bool smoothers_configured_ = false;
 
    /// Inverse square root compensation — keeps output level roughly
    /// constant as fold depth increases.
    static float compensation_gain(float depth) {
        return (depth > 1.0f) ? 1.0f / sqrtf(depth) : 1.0f;
    }
};
 
} // namespace sbl::dsp::widgets
 
#endif // SBL_DSP_WIDGETS_SHAPER_HPP_