synthesiser.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/midi/buffer.hpp>
#include <pulp/midi/message.hpp>
#include <pulp/runtime/budget_policy.hpp>
 
#include <algorithm>
#include <array>
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <limits>
#include <type_traits>
#include <vector>
 
namespace pulp::midi {

struct SynthesiserNote {
    uint8_t channel = 0;          
    uint8_t note = 0;             
    uint8_t velocity = 0;         
    int8_t priority = 0;          
    uint8_t voice_group = 0;      
    uint32_t note_id = 0;         
    bool active = false;          
    bool releasing = false;       
    bool sustained = false;       
    bool sostenuto = false;       
    bool soft_pedal = false;      
};

enum class VoiceStealStrategy : uint8_t {
    Oldest,
    Quietest,
    Lowest,
    Highest,
    Priority,
};
 
struct SynthesiserTelemetry {
    std::size_t polyphony = 0;
    std::size_t active_voice_count = 0;
    std::size_t releasing_voice_count = 0;
    std::uint64_t steal_count = 0;
    VoiceStealStrategy steal_strategy = VoiceStealStrategy::Oldest;
};
 
struct SynthesiserRuntimeBudgetReport {
    runtime::RuntimeBudgetDecision decision{};
    runtime::RuntimeBudgetFrameStats frame_stats{};
    SynthesiserTelemetry telemetry{};
    std::uint64_t estimated_cost = 0;
 
    bool should_run_optional_work() const noexcept {
        return decision.should_run();
    }
};

class SynthesiserVoice {
public:
    virtual ~SynthesiserVoice() = default;

    virtual void on_note_on(const SynthesiserNote& note) {
        note_ = note;
        active_ = true;
        releasing_ = false;
        note_.sustained = false;
        note_.sostenuto = false;
    }

    virtual void on_note_off() {
        releasing_ = true;
        note_.releasing = true;
        note_.sustained = false;
        note_.sostenuto = false;
    }

    virtual void on_choke(float fade_ms) {
        (void)fade_ms;
        on_note_off();
    }

    virtual void on_pitch_bend(float bend_semitones) { (void)bend_semitones; }

    virtual void on_aftertouch(float pressure) { (void)pressure; }

    virtual void on_cc(uint8_t cc_number, uint8_t value) {
        (void)cc_number; (void)value;
    }

    virtual void render(float* out, int num_samples) = 0;

    virtual float peak_level() const { return 0.0f; }

    virtual void reset() {
        note_ = {};
        active_ = false;
        releasing_ = false;
    }
 
    bool active() const { return active_; }
    bool releasing() const { return releasing_; }
    const SynthesiserNote& note() const { return note_; }

    void defer_note_off_for_sustain() {
        if (!active_ || releasing_) return;
        note_.sustained = true;
    }

    void release_sustained_note() {
        if (!active_ || releasing_ || !note_.sustained) return;
        note_.sustained = false;
        if (!note_.sostenuto) on_note_off();
    }

    void capture_for_sostenuto() {
        if (!active_ || releasing_) return;
        note_.sostenuto = true;
    }

    void release_sostenuto_note() {
        if (!active_ || releasing_ || !note_.sostenuto) return;
        note_.sostenuto = false;
        if (!note_.sustained) on_note_off();
    }

    void set_soft_pedal(bool down) {
        if (!active_ || releasing_) return;
        note_.soft_pedal = down;
    }
 
protected:
    void mark_inactive() { active_ = false; releasing_ = false; }
 
    SynthesiserNote note_{};
    bool active_ = false;
    bool releasing_ = false;
};

struct SynthesiserNoteOnPolicy {
    uint8_t voice_group = 0;
    bool choke_group = false;
    float choke_fade_ms = 0.0f;
    int8_t priority = 0;          
};

template <typename Voice>
class Synthesiser {
    static_assert(std::is_base_of<SynthesiserVoice, Voice>::value,
                  "Voice must derive from SynthesiserVoice");
 
public:
    explicit Synthesiser(std::size_t polyphony = 16)
        : voices_(polyphony) {}
 
    void set_steal_strategy(VoiceStealStrategy s) { strategy_ = s; }
    VoiceStealStrategy steal_strategy() const { return strategy_; }

    void set_pitch_bend_range_semitones(float r) {
        if (r > 0.0f) bend_range_semi_ = r;
    }
    float pitch_bend_range_semitones() const { return bend_range_semi_; }

    void note_on(uint8_t channel, uint8_t note, uint8_t velocity,
                 int8_t priority = 0, uint8_t voice_group = 0,
                 bool choke_group = false, float choke_fade_ms = 0.0f) {
        if (velocity == 0) { note_off(channel, note); return; }
        const auto masked_channel = static_cast<uint8_t>(channel & 0x0F);
        const auto masked_group = static_cast<uint8_t>(voice_group & 0x7F);
        if (choke_group && masked_group != 0) {
            choke_voice_group(masked_channel, masked_group, choke_fade_ms);
        }
        Voice* v = find_free_voice();
        if (!v) v = steal_voice();
        if (!v) return;
        SynthesiserNote n;
        n.channel = masked_channel;
        n.note = static_cast<uint8_t>(note & 0x7F);
        n.velocity = static_cast<uint8_t>(velocity & 0x7F);
        n.priority = priority;
        n.voice_group = masked_group;
        n.note_id = ++next_id_;
        n.active = true;
        n.releasing = false;
        n.soft_pedal = soft_pedal_down_[n.channel];
        v->on_note_on(n);
    }
 
    void note_off(uint8_t channel, uint8_t note) {
        const auto masked_channel = static_cast<uint8_t>(channel & 0x0F);
        for (auto& v : voices_) {
            if (v.active() && !v.releasing()
                && v.note().channel == masked_channel
                && v.note().note == (note & 0x7F)) {
                bool deferred = false;
                if (sustain_down_[masked_channel]) {
                    v.defer_note_off_for_sustain();
                    deferred = true;
                }
                if (v.note().sostenuto) {
                    deferred = true;
                }
                if (!deferred) {
                    v.on_note_off();
                }
            }
        }
    }
 
    void pitch_bend(uint8_t channel, float bend_semitones) {
        for (auto& v : voices_) {
            if (v.active() && v.note().channel == (channel & 0x0F)) {
                v.on_pitch_bend(bend_semitones);
            }
        }
    }
 
    void aftertouch(uint8_t channel, float pressure) {
        for (auto& v : voices_) {
            if (v.active() && v.note().channel == (channel & 0x0F)) {
                v.on_aftertouch(pressure);
            }
        }
    }
 
    void cc(uint8_t channel, uint8_t cc_number, uint8_t value) {
        const auto masked_channel = static_cast<uint8_t>(channel & 0x0F);
        for (auto& v : voices_) {
            if (v.active() && v.note().channel == masked_channel) {
                v.on_cc(cc_number, value);
            }
        }
        if ((cc_number & 0x7F) == 64) {
            const bool was_down = sustain_down_[masked_channel];
            const bool is_down = value >= 64;
            sustain_down_[masked_channel] = is_down;
            if (was_down && !is_down) {
                release_sustained_notes(masked_channel);
            }
        } else if ((cc_number & 0x7F) == 66) {
            const bool was_down = sostenuto_down_[masked_channel];
            const bool is_down = value >= 64;
            sostenuto_down_[masked_channel] = is_down;
            if (!was_down && is_down) {
                capture_sostenuto_notes(masked_channel);
            } else if (was_down && !is_down) {
                release_sostenuto_notes(masked_channel);
            }
        } else if ((cc_number & 0x7F) == 67) {
            const bool is_down = value >= 64;
            soft_pedal_down_[masked_channel] = is_down;
            set_soft_pedal_notes(masked_channel, is_down);
        }
    }

    void process(const MidiBuffer& events, float* out, int num_samples) {
        process(events, out, num_samples, {});
    }

    void process(const MidiBuffer& events, float* out, int num_samples,
                 const SynthesiserNoteOnPolicy& note_on_policy) {
        auto constant = [&note_on_policy](uint8_t, uint8_t, uint8_t) {
            return note_on_policy;
        };
        render_block(events, out, num_samples, constant);
    }

    template <typename PolicyFn>
        requires std::is_invocable_r_v<SynthesiserNoteOnPolicy, PolicyFn&,
                                       uint8_t, uint8_t, uint8_t>
    void process(const MidiBuffer& events, float* out, int num_samples,
                 PolicyFn&& policy_for_note) {
        render_block(events, out, num_samples, policy_for_note);
    }
 
    std::size_t polyphony() const { return voices_.size(); }
    Voice& voice(std::size_t i) { return voices_[i]; }
    const Voice& voice(std::size_t i) const { return voices_[i]; }
 
    std::size_t active_count() const {
        std::size_t n = 0;
        for (const auto& v : voices_) if (v.active()) ++n;
        return n;
    }
 
    std::size_t releasing_count() const {
        std::size_t n = 0;
        for (const auto& v : voices_) if (v.active() && v.releasing()) ++n;
        return n;
    }
 
    std::uint64_t steal_count() const {
        return steal_count_.load(std::memory_order_relaxed);
    }
 
    void reset_steal_count() {
        steal_count_.store(0, std::memory_order_relaxed);
    }

    SynthesiserTelemetry telemetry() const {
        return {
            .polyphony = polyphony(),
            .active_voice_count = active_count(),
            .releasing_voice_count = releasing_count(),
            .steal_count = steal_count(),
            .steal_strategy = strategy_,
        };
    }
 
    std::uint64_t estimate_optional_runtime_cost() const {
        const auto t = telemetry();
        std::uint64_t cost = 0;
        cost = saturating_add_u64_(
            cost, saturating_mul_u64_(
                static_cast<std::uint64_t>(t.polyphony), 4));
        cost = saturating_add_u64_(
            cost, saturating_mul_u64_(
                static_cast<std::uint64_t>(t.active_voice_count), 64));
        cost = saturating_add_u64_(
            cost, saturating_mul_u64_(
                static_cast<std::uint64_t>(t.releasing_voice_count), 32));
        return cost;
    }
 
    SynthesiserRuntimeBudgetReport evaluate_optional_runtime_budget(
        runtime::RuntimeBudgetFrame& frame,
        runtime::RuntimeWorkLane lane = runtime::RuntimeWorkLane::Background,
        bool required = false) const {
        const auto t = telemetry();
        const auto cost = estimate_optional_runtime_cost();
        const auto decision = frame.evaluate(lane, cost, required);
        return {
            .decision = decision,
            .frame_stats = frame.stats(),
            .telemetry = t,
            .estimated_cost = cost,
        };
    }

    void panic(bool immediate) {
        if (immediate) {
            reset();
            return;
        }
        sustain_down_.fill(false);
        sostenuto_down_.fill(false);
        for (auto& v : voices_) {
            if (v.active() && !v.releasing())
                v.on_note_off();
        }
    }
 
    void reset() {
        for (auto& v : voices_) v.reset();
        sustain_down_.fill(false);
        sostenuto_down_.fill(false);
        soft_pedal_down_.fill(false);
        next_id_ = 0;
    }
 
private:
    static std::uint64_t saturating_add_u64_(std::uint64_t a,
                                             std::uint64_t b) {
        const auto max = std::numeric_limits<std::uint64_t>::max();
        return b > max - a ? max : a + b;
    }
 
    static std::uint64_t saturating_mul_u64_(std::uint64_t a,
                                             std::uint64_t b) {
        const auto max = std::numeric_limits<std::uint64_t>::max();
        if (a == 0 || b == 0) return 0;
        return a > max / b ? max : a * b;
    }
 
    Voice* find_free_voice() {
        for (auto& v : voices_) if (!v.active()) return &v;
        return nullptr;
    }
 
    Voice* steal_voice() {
        if (voices_.empty()) return nullptr;
        Voice* chosen = nullptr;
        switch (strategy_) {
            case VoiceStealStrategy::Oldest: {
                uint32_t oldest_id = std::numeric_limits<uint32_t>::max();
                for (auto& v : voices_) {
                    if (v.active() && v.note().note_id < oldest_id) {
                        chosen = &v;
                        oldest_id = v.note().note_id;
                    }
                }
                break;
            }
            case VoiceStealStrategy::Quietest: {
                float min_level = std::numeric_limits<float>::infinity();
                uint32_t tie_id = std::numeric_limits<uint32_t>::max();
                for (auto& v : voices_) {
                    if (!v.active()) continue;
                    const float lvl = v.peak_level();
                    if (lvl < min_level
                        || (lvl == min_level && v.note().note_id < tie_id)) {
                        chosen = &v;
                        min_level = lvl;
                        tie_id = v.note().note_id;
                    }
                }
                break;
            }
            case VoiceStealStrategy::Lowest: {
                uint8_t lowest = 127;
                uint32_t tie_id = std::numeric_limits<uint32_t>::max();
                for (auto& v : voices_) {
                    if (!v.active()) continue;
                    const uint8_t n = v.note().note;
                    if (n < lowest || (n == lowest && v.note().note_id < tie_id)) {
                        chosen = &v;
                        lowest = n;
                        tie_id = v.note().note_id;
                    }
                }
                break;
            }
            case VoiceStealStrategy::Highest: {
                int highest = -1;
                uint32_t tie_id = std::numeric_limits<uint32_t>::max();
                for (auto& v : voices_) {
                    if (!v.active()) continue;
                    const int n = v.note().note;
                    if (n > highest
                        || (n == highest && v.note().note_id < tie_id)) {
                        chosen = &v;
                        highest = n;
                        tie_id = v.note().note_id;
                    }
                }
                break;
            }
            case VoiceStealStrategy::Priority: {
                int lowest_prio = std::numeric_limits<int>::max();
                uint32_t tie_id = std::numeric_limits<uint32_t>::max();
                for (auto& v : voices_) {
                    if (!v.active()) continue;
                    const int p = v.note().priority;
                    if (p < lowest_prio
                        || (p == lowest_prio && v.note().note_id < tie_id)) {
                        chosen = &v;
                        lowest_prio = p;
                        tie_id = v.note().note_id;
                    }
                }
                break;
            }
        }
        if (chosen) {
            steal_count_.fetch_add(1, std::memory_order_relaxed);
            chosen->reset();
        }
        return chosen;
    }

    template <typename PolicyFn>
    void render_block(const MidiBuffer& events, float* out, int num_samples,
                      PolicyFn& policy_for_note) {
        if (num_samples <= 0) return;
        int sample_index = 0;
        for (std::size_t i = 0; i < events.size(); ++i) {
            const auto& e = events[i];
            int target = static_cast<int>(e.sample_offset);
            if (target < sample_index) target = sample_index;
            if (target > num_samples) target = num_samples;
            if (target > sample_index) {
                render_active(out + sample_index, target - sample_index);
                sample_index = target;
            }
            dispatch_event(e, policy_for_note);
        }
        if (sample_index < num_samples) {
            render_active(out + sample_index, num_samples - sample_index);
        }
    }
 
    template <typename PolicyFn>
    void dispatch_event(const MidiEvent& e, PolicyFn& policy_for_note) {
        const uint8_t status_top = static_cast<uint8_t>(e.data()[0] & 0xF0);
        const uint8_t channel = e.channel();
        if (e.is_note_on() && e.velocity() > 0) {
            // Resolved here rather than per buffer so a kit can give each note
            // its own choke group, and only for note-ons so a CC never pays for
            // the lookup.
            const SynthesiserNoteOnPolicy note_on_policy =
                policy_for_note(channel, e.note(), e.velocity());
            note_on(channel, e.note(), e.velocity(), note_on_policy.priority,
                    note_on_policy.voice_group, note_on_policy.choke_group,
                    note_on_policy.choke_fade_ms);
            return;
        }
        if (e.is_note_off() || (e.is_note_on() && e.velocity() == 0)) {
            note_off(channel, e.note());
            return;
        }
        if (e.is_pitch_bend()) {
            const uint16_t raw = static_cast<uint16_t>(
                e.data()[1] | (uint16_t(e.data()[2]) << 7));
            const float norm = (static_cast<float>(raw) - 8192.0f) / 8192.0f;
            pitch_bend(channel, norm * bend_range_semi_);
            return;
        }
        if (status_top == 0xD0) {
            aftertouch(channel, e.data()[1] / 127.0f);
            return;
        }
        if (e.is_cc()) {
            cc(channel, e.cc_number(), e.cc_value());
            return;
        }
        // PolyAftertouch (0xA0), ProgramChange (0xC0), system messages
        // are ignored at this layer — subclasses can route them via
        // direct event taps if needed.
    }
 
    void render_active(float* out, int n) {
        for (auto& v : voices_) {
            if (v.active()) v.render(out, n);
        }
    }
 
    void release_sustained_notes(uint8_t channel) {
        for (auto& v : voices_) {
            if (v.active() && !v.releasing()
                && v.note().channel == channel
                && v.note().sustained) {
                v.release_sustained_note();
            }
        }
    }
 
    void capture_sostenuto_notes(uint8_t channel) {
        for (auto& v : voices_) {
            if (v.active() && !v.releasing() && v.note().channel == channel) {
                v.capture_for_sostenuto();
            }
        }
    }
 
    void release_sostenuto_notes(uint8_t channel) {
        for (auto& v : voices_) {
            if (v.active() && !v.releasing()
                && v.note().channel == channel
                && v.note().sostenuto) {
                v.release_sostenuto_note();
            }
        }
    }
 
    void set_soft_pedal_notes(uint8_t channel, bool down) {
        for (auto& v : voices_) {
            if (v.active() && !v.releasing() && v.note().channel == channel) {
                v.set_soft_pedal(down);
            }
        }
    }
 
    void choke_voice_group(uint8_t channel, uint8_t voice_group,
                           float fade_ms) {
        for (auto& v : voices_) {
            if (v.active() && v.note().channel == channel
                && v.note().voice_group == voice_group) {
                v.on_choke(fade_ms);
            }
        }
    }
 
    std::vector<Voice> voices_;
    std::array<bool, 16> sustain_down_{};
    std::array<bool, 16> sostenuto_down_{};
    std::array<bool, 16> soft_pedal_down_{};
    VoiceStealStrategy strategy_ = VoiceStealStrategy::Oldest;
    float bend_range_semi_ = 2.0f;
    uint32_t next_id_ = 0;
    std::atomic<std::uint64_t> steal_count_{0};
};
 
} // namespace pulp::midi