delay.hpp

Go to the documentation of this file.

// sbl/widgets/proc/delay.hpp — Stereo delay effect (Audio Stack — Widgets)
//
// Stereo delay with filtered feedback, dry/wet mix, and ping-pong mode.
// Tone control uses a one-pole lowpass in the feedback path — same damping
// formulation as the comb filter — simulating high-frequency absorption.
//
// Uses ModulatedDelayLine internally for buffer management and interpolated
// reads. The delay time glides smoothly via per-sample coefficient, producing
// tape-style pitch effects on time changes.
//
// Float-domain processing — STM32H7 (Cortex-M7) has hardware FPU with
// single-cycle float ops.
//
// Usage:
//   float buf_l[24000] = {}, buf_r[24000] = {};  // 500ms @ 48kHz
//   sbl::widgets::proc::Delay delay;
//   delay.init(buf_l, buf_r, 24000);
//   delay.set_sample_rate(48000);
//   delay.set_time_ms(300.0f);
//   delay.set_feedback(0.4f);
//   delay.set_mix(0.3f);
//   delay.process(left, right, frames);
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/modulated_delay_line.hpp>
#include <sbl/dsp/one_pole.hpp>
 
namespace sbl::widgets::proc {
 
class Delay {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /**
     * @brief Construct with caller-provided float buffers
     * @param buf_l Left delay buffer (must outlive the Delay)
     * @param buf_r Right delay buffer (must outlive the Delay)
     * @param max_samples Maximum delay in samples (buffer size)
     */
    Delay(float* buf_l, float* buf_r, uint32_t max_samples)
        : dl_l_(buf_l, max_samples), dl_r_(buf_r, max_samples) {}
 
    /// Default constructor (must call init() before use)
    Delay() = default;
 
    /**
     * @brief Initialize after default construction
     * @param buf_l Left delay buffer
     * @param buf_r Right delay buffer
     * @param max_samples Maximum delay in samples
     */
    void init(float* buf_l, float* buf_r, uint32_t max_samples) {
        dl_l_.init(buf_l, max_samples);
        dl_r_.init(buf_r, max_samples);
    }
 
    void set_sample_rate(uint32_t sr) { sample_rate_ = sr; }
 
    /**
     * @brief Set delay time in samples
     * @param samples Delay length (clamped to max_samples - 1)
     */
    void set_time(uint32_t samples) {
        uint32_t max = dl_l_.max_delay();
        target_samples_ = (samples < max) ? samples : max - 1;
        if (!time_initialized_) {
            current_samples_ = static_cast<float>(target_samples_);
            time_initialized_ = true;
        }
    }
 
    /**
     * @brief Set delay time in milliseconds
     * @param ms Delay time in milliseconds
     */
    void set_time_ms(float ms) {
        set_time(static_cast<uint32_t>(ms * static_cast<float>(sample_rate_) / 1000.0f));
    }
 
    /**
     * @brief Set delay time from BPM and note division
     * @param bpm Tempo in beats per minute
     * @param division Note division (1=whole, 2=half, 4=quarter, 8=eighth, etc.)
     */
    void set_time_bpm(float bpm, uint8_t division) {
        if (bpm < 1.0f) bpm = 1.0f;
        float seconds = 60.0f / (bpm * static_cast<float>(division));
        uint32_t samples = static_cast<uint32_t>(seconds * static_cast<float>(sample_rate_));
        set_time(samples);
    }
 
    /**
     * @brief Set feedback gain
     * @param fb Feedback 0.0–1.0 (clamped to 0.95 for stability)
     */
    void set_feedback(float fb) {
        feedback_ = (fb > 0.95f) ? 0.95f : (fb < 0.0f ? 0.0f : fb);
    }
 
    /**
     * @brief Set dry/wet mix
     * @param mix 0.0 = fully dry, 1.0 = fully wet
     */
    void set_mix(float mix) {
        mix_ = (mix > 1.0f) ? 1.0f : (mix < 0.0f ? 0.0f : mix);
    }
 
    /**
     * @brief Set tone (feedback damping)
     * @param tone 0.0 = dark (heavy HF absorption), 1.0 = bright (no filtering)
     */
    void set_tone(float tone) {
        if (tone > 1.0f) tone = 1.0f;
        if (tone < 0.0f) tone = 0.0f;
        // tone=1.0 (bright) → coeff=1.0 (passthrough)
        // tone=0.0 (dark)   → coeff=0.1 (heavy LP filtering)
        float coeff = 1.0f - (1.0f - tone) * 0.9f;
        tone_l_.set_coefficient(coeff);
        tone_r_.set_coefficient(coeff);
    }
 
    /** @brief Enable/disable ping-pong stereo bounce */
    void set_ping_pong(bool enable) { ping_pong_ = enable; }
 
    /** @brief Current delay time in samples */
    uint32_t time() const { return target_samples_; }
    float feedback() const { return feedback_; }
    float mix() const { return mix_; }
    bool ping_pong() const { return ping_pong_; }
 
    /**
     * @brief Process a stereo block in-place (float)
     *
     * @param left Left channel buffer (float, in-place)
     * @param right Right channel buffer (float, in-place)
     * @param frames Number of sample frames
     */
    void process(float* left, float* right, uint16_t frames) {
        const float fb = feedback_;
        const float wet = mix_;
        const float dry = 1.0f - wet;
        const float target = static_cast<float>(target_samples_);
 
        for (uint16_t i = 0; i < frames; ++i) {
            current_samples_ += TIME_SMOOTH * (target - current_samples_);
 
            float in_l = left[i];
            float in_r = right[i];
 
            float delayed_l = dl_l_.read(current_samples_);
            float delayed_r = dl_r_.read(current_samples_);
 
            float filtered_l = tone_l_.process(delayed_l);
            float filtered_r = tone_r_.process(delayed_r);
 
            float fb_l, fb_r;
            if (ping_pong_) {
                fb_l = filtered_r * fb;
                fb_r = filtered_l * fb;
            } else {
                fb_l = filtered_l * fb;
                fb_r = filtered_r * fb;
            }
 
            dl_l_.write(in_l + fb_l);
            dl_r_.write(in_r + fb_r);
 
            left[i]  = dry * in_l + wet * delayed_l;
            right[i] = dry * in_r + wet * delayed_r;
        }
    }
 
    /** @brief Clear delay buffers and reset all state */
    void reset() {
        dl_l_.clear();
        dl_r_.clear();
        current_samples_ = static_cast<float>(target_samples_);
        time_initialized_ = (target_samples_ > 0);
        tone_l_.reset();
        tone_r_.reset();
    }
 
private:
    static constexpr float TIME_SMOOTH = 0.002f;
 
    dsp::ModulatedDelayLine dl_l_;
    dsp::ModulatedDelayLine dl_r_;
 
    uint32_t target_samples_ = 0;
    float current_samples_ = 0.0f;
    bool time_initialized_ = false;
    float feedback_ = 0.4f;
    float mix_ = 0.3f;
    dsp::OnePole tone_l_;
    dsp::OnePole tone_r_;
    bool ping_pong_ = false;
    uint32_t sample_rate_ = 48000;
};
 
} // namespace sbl::widgets::proc