mixer.hpp

Go to the documentation of this file.

// sbl/dsp/modules/mixer.hpp — Mixing console module (Audio Stack — Modules)
//
// Ableton session view-inspired bus topology: Audio channels, Return channels,
// and a master bus. Composes Channel widgets with summing and master output.
//
// Three channel types:
//   Audio  — Sound sources (voices, inputs). Have sends to returns.
//   Return — FX processors (delay, reverb). Can also send to other returns.
//   Group  — Submix bus (future — not implemented).
//
// Solo-in-place: soloing an audio channel still lets its FX tails through.
// Audio and return solo scopes are independent (Ableton behavior).
//
// Return channels must be ordered so upstream returns (delay) precede
// downstream returns (reverb) for return-to-return sends to work correctly.
// This is a documented convention, not enforced.
//
// Effect callbacks:
//   Each return slot holds an optional FxProcess callback. The mixer calls it
//   after accumulating sends into the return's input buffers (buf_l/buf_r).
//   The callback processes audio in-place (e.g., delay, reverb). After the
//   callback, the return channel's process() applies gain + pan for master.
//   Returns without a callback pass the dry accumulated signal through.
//
// Single process(n) call replaces the old clear/route_sends/sum_to_master/
// apply_master sequence:
//   1. Clear return inputs and master bus
//   2. Process all audio channels (gain + pan)
//   3. Route audio channel sends to return inputs
//   4. Process returns in order (call FX, then route return-to-return sends)
//   5. Sum to master (respecting mute/solo)
//   6. Apply master gain (fader * bus_gain * output_trim)
//
// Usage:
//   sbl::dsp::modules::Mixer<48, 3, 2> mixer;
//   mixer.audio[0].add_send(0, 0.4f);      // voice 0 → delay return
//   mixer.audio[0].add_send(1, 0.2f);      // voice 0 → reverb return
//   mixer.set_return_processor(0, &delay, delay_process);
//   mixer.set_return_processor(1, &reverb, reverb_process);
//
//   // In audio callback:
//   mixer.audio[0].write_input_mono(voice_buf, n);
//   mixer.process(n);
//   // mixer.master_l/r ready for DAC
 
#ifndef SBL_DSP_MODULES_MIXER_HPP_
#define SBL_DSP_MODULES_MIXER_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/widgets/channel.hpp>
 
namespace sbl::dsp::modules {
 
/// Effect processor callback signature.
/// Called with the return channel's accumulated input buffers.
/// Must process audio in-place.
using FxProcess = void(*)(void* ctx, float* buf_l, float* buf_r, uint16_t n);
 
template <uint16_t MaxFrames, uint8_t NumAudio, uint8_t NumReturn, uint8_t MaxSends = 4>
class Mixer {
public:
    using Chan = widgets::Channel<MaxFrames, MaxSends>;
 
    Chan audio[NumAudio];     // Audio channels (voices, inputs)
 
    // Master output buffers
    float master_l[MaxFrames] = {};
    float master_r[MaxFrames] = {};
 
    // ── Master ports ─────────────────────────────────────────────────
 
    /// Port: master fader level [0,1].
    void set_master_fader_su(float su) { master_fader_.set_level_su(su); }
 
    // ── Master parameters ────────────────────────────────────────────
 
    void set_bus_gain(float g) { bus_gain_ = g; }
    void set_output_trim(float t) { output_trim_ = t; }
    void set_master_taper(comp::Taper t) { master_fader_.set_taper(t); }
 
    // ── Return channel access ────────────────────────────────────────
 
    /// Access a return channel by index.
    Chan& ret(uint8_t idx) { return returns_[idx].channel; }
    const Chan& ret(uint8_t idx) const { return returns_[idx].channel; }
 
    /// Register an effect processor callback for a return channel.
    /// The callback is called with the accumulated send input and must
    /// process audio in-place.
    void set_return_processor(uint8_t idx, void* ctx, FxProcess fn) {
        if (idx < NumReturn) {
            returns_[idx].processor = fn;
            returns_[idx].processor_ctx = ctx;
        }
    }
 
    // ── Processing — single call replaces old multi-step sequence ────
 
    /// Process the entire mixer for one block.
    ///
    /// Prerequisites: audio channels have been written via write_input_mono/stereo.
    ///
    /// Steps:
    ///   1. Clear return input buffers and master bus
    ///   2. Process all audio channels (fader gain + pan)
    ///   3. Route audio channel sends to return inputs
    ///   4. For each return in order:
    ///      a. Call effect processor (if registered)
    ///      b. Process return channel (fader gain + pan)
    ///      c. Route return-to-return sends
    ///   5. Sum all channels to master bus (mute/solo)
    ///   6. Apply master gain (fader * bus_gain * output_trim)
    void process(uint16_t n) {
        // 1. Clear return input buffers and master bus
        for (uint8_t i = 0; i < NumReturn; ++i)
            clear_buf(returns_[i].channel.buf_l, returns_[i].channel.buf_r, n);
        clear_buf(master_l, master_r, n);
 
        // 2. Process all audio channels (gain + pan)
        for (uint8_t i = 0; i < NumAudio; ++i)
            audio[i].process(n);
 
        // 3. Route audio channel sends to return inputs
        for (uint8_t i = 0; i < NumAudio; ++i)
            route_channel_sends(audio[i], n);
 
        // 4. Process returns in order
        for (uint8_t i = 0; i < NumReturn; ++i) {
            auto& slot = returns_[i];
 
            // 4a. Call effect processor (operates on accumulated input in-place)
            if (slot.processor) {
                slot.processor(slot.processor_ctx,
                               slot.channel.buf_l, slot.channel.buf_r, n);
            }
 
            // 4b. Process return channel (gain + pan → post_l/post_r)
            // After this, buf_l/buf_r contain the wet signal (post-effect,
            // pre-fader) and post_l/post_r contain the master-ready signal.
            slot.channel.process(n);
 
            // 4c. Route return-to-return sends (serial FX chains)
            route_channel_sends(slot.channel, n);
        }
 
        // 5. Sum to master (respecting mute/solo)
        sum_to_master(n);
 
        // 6. Apply master gain
        apply_master_gain(n);
    }
 
    // ── Accessors ────────────────────────────────────────────────────
 
    comp::Fader& master_fader() { return master_fader_; }
 
private:
    struct ReturnSlot {
        Chan channel;
        FxProcess processor = nullptr;
        void* processor_ctx = nullptr;
    };
 
    comp::Fader master_fader_;       // master level
    float bus_gain_ = 0.707f;           // -3dB headroom
    float output_trim_ = 0.5f;          // DAC calibration
    ReturnSlot returns_[NumReturn] = {};
 
    // ── Private helpers ──────────────────────────────────────────────
 
    static void clear_buf(float* l, float* r, uint16_t n) {
        for (uint16_t i = 0; i < n; ++i) {
            l[i] = 0.0f;
            r[i] = 0.0f;
        }
    }
 
    /// Route one channel's sends to return channel input buffers.
    /// Reads from buf_l/buf_r (pre-pan). Gain depends on send type:
    ///   PreFader:  send_level only
    ///   PostFader: fader_gain * send_level
    void route_channel_sends(Chan& ch, uint16_t n) {
        for (uint8_t s = 0; s < ch.send_count(); ++s) {
            auto& send = ch.send(s);
            // Advance the send fader smoother by the block's worth of samples
            // for control-rate smoothed gain. Advances even when skipped.
            float send_gain = send.level.tick(n);
            if (send_gain < 0.001f) continue;
 
            Chan& tgt = returns_[send.target].channel;
            const float* src_l = ch.buf_l;
            const float* src_r = (ch.format() == widgets::Format::Mono)
                                     ? ch.buf_l
                                     : ch.buf_r;
 
            float gain = (send.type == widgets::SendType::PreFader)
                             ? send_gain
                             : ch.fader_gain() * send_gain;
 
            for (uint16_t i = 0; i < n; ++i) {
                tgt.buf_l[i] += src_l[i] * gain;
                tgt.buf_r[i] += src_r[i] * gain;
            }
        }
    }
 
    /// Sum all channels to master bus. Applies per-channel post output,
    /// respects mute/solo. Solo-in-place: audio and return solo
    /// scopes are independent.
    void sum_to_master(uint16_t n) {
        // Detect solo state per scope
        bool any_audio_solo = false;
        for (uint8_t i = 0; i < NumAudio; ++i)
            if (audio[i].soloed()) any_audio_solo = true;
 
        bool any_ret_solo = false;
        for (uint8_t i = 0; i < NumReturn; ++i)
            if (returns_[i].channel.soloed()) any_ret_solo = true;
 
        // Sum audio channels (from post-processed output)
        for (uint8_t ch = 0; ch < NumAudio; ++ch) {
            if (audio[ch].muted()) continue;
            if (any_audio_solo && !audio[ch].soloed()) continue;
 
            const float* src_l = audio[ch].post_l();
            const float* src_r = audio[ch].post_r();
 
            for (uint16_t i = 0; i < n; ++i) {
                master_l[i] += src_l[i];
                master_r[i] += src_r[i];
            }
        }
 
        // Sum return channels (solo-in-place: returns independent of audio solo)
        for (uint8_t ch = 0; ch < NumReturn; ++ch) {
            if (returns_[ch].channel.muted()) continue;
            if (any_ret_solo && !returns_[ch].channel.soloed()) continue;
 
            const float* src_l = returns_[ch].channel.post_l();
            const float* src_r = returns_[ch].channel.post_r();
 
            for (uint16_t i = 0; i < n; ++i) {
                master_l[i] += src_l[i];
                master_r[i] += src_r[i];
            }
        }
    }
 
    /// Apply bus gain (headroom), master fader, and output trim (DAC calibration).
    void apply_master_gain(uint16_t n) {
        float master_gain = master_fader_.tick(n);
        float gain = master_gain * bus_gain_ * output_trim_;
        for (uint16_t i = 0; i < n; ++i) {
            master_l[i] *= gain;
            master_r[i] *= gain;
        }
    }
};
 
} // namespace sbl::dsp::modules
 
#endif // SBL_DSP_MODULES_MIXER_HPP_