parameter_smoother.hpp

Go to the documentation of this file.

// sbl/dsp/primitives/parameter_smoother.hpp — One-pole parameter smoother
//
// Single-pole IIR for smoothing parameter transitions. Eliminates zipper
// noise from discrete control updates (knob steps, MIDI CC, block-rate
// parameter changes).
//
// Same y += a * (x - y) math as OnePole filter, but a different object with
// a different API and purpose. Settling time is a time constant, not a signal.
//
// Usage:
//   sbl::dsp::ParameterSmoother sm;
//   sm.set_time_ms(15.0f, 1000.0f);    // 15ms settling at 1kHz update rate
//   float smoothed = sm.process(target); // chase target value
 
#ifndef SBL_DSP_PRIMITIVES_PARAMETER_SMOOTHER_HPP_
#define SBL_DSP_PRIMITIVES_PARAMETER_SMOOTHER_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/math/fast_math.hpp>
 
namespace sbl::dsp::primitives {
 
class ParameterSmoother {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /**
     * @brief Set coefficient directly
     *
     * a = 0.0 → hold previous output, 1.0 → instant (no smoothing).
     */
    void set_coefficient(float a) { coeff_ = a; }
 
    /**
     * @brief Compute coefficient from settling time in milliseconds
     *
     * Sets coefficient so the smoother reaches ~95% of a step change in
     * the given time at the given update rate.
     *
     * @param ms Settling time in milliseconds (95% of step)
     * @param rate_hz Update rate in Hz (e.g., 1000 for block-rate at 1kHz)
     */
    void set_time_ms(float ms, float rate_hz) {
        if (ms <= 0.0f || rate_hz <= 0.0f) {
            coeff_ = 1.0f;  // instant
            return;
        }
        // 95% settling in T seconds requires τ = T/3 (since e^(-3) ≈ 0.05)
        // α = 1 - exp(-1 / (τ * rate)) = 1 - exp(-3 / (ms/1000 * rate))
        // Inverse Taylor: exp(-x) ≈ 1/(1 + x + x²/2 + x³/6)
        coeff_ = math::one_minus_exp_neg(3000.0f / (ms * rate_hz));
    }
 
    /**
     * @brief Process one sample toward target
     * @param target The value to approach
     * @return Smoothed value
     */
    float process(float target) {
        state_ += coeff_ * (target - state_);
        return state_;
    }
 
    /**
     * @brief Advance n steps toward target in one call
     *
     * Exactly equivalent to n consecutive process() calls. Lets a smoother
     * whose coefficient was computed for a per-sample rate be advanced at
     * block rate without stretching its settling time — pass the block
     * size as n.
     *
     * @param target The value to approach
     * @param n Number of steps to advance
     * @return Smoothed value after n steps
     */
    float process_steps(float target, uint32_t n) {
        for (uint32_t i = 0; i < n; ++i) {
            state_ += coeff_ * (target - state_);
        }
        return state_;
    }
 
    /** @brief Current smoothed value */
    float value() const { return state_; }
 
    /** @brief Current coefficient */
    float coefficient() const { return coeff_; }
 
    /** @brief Reset to zero */
    void reset() { state_ = 0.0f; }
 
    /** @brief Reset to a specific value */
    void reset(float initial) { state_ = initial; }
 
private:
    float coeff_ = 0.0f;
    float state_ = 0.0f;
};
 
} // namespace sbl::dsp::primitives
 
#endif // SBL_DSP_PRIMITIVES_PARAMETER_SMOOTHER_HPP_