sequencer.hpp

Go to the documentation of this file.

// sbl/protocol/midi/sequencer.hpp — Plays a Standard MIDI File into outputs (FDP-078)
//
// The sequencer owns a playhead over an SmfReader's tracks. It is told how
// many samples have passed and never assumes a call rate (ADR-011): advance()
// walks every track in tick order, converts ticks to time through the tempo
// map, and hands each event that is due to a sink with the output it belongs
// to. Events come out in the call where they fall due, so their timing is as
// fine as the calls: to the sample if advance() is called per sample, to the
// tick if it is called from a 1 kHz scheduler.
//
// Time is exact integer arithmetic. Tick → microseconds carries its remainder
// across segments, and "due" compares microseconds × sample rate against
// samples × 10^6, so nothing drifts over a long song or many loops.
//
// Routing. A format 1 file's track 0 is the conductor (the tempo map): its
// tempo events apply, its channel events go nowhere unless mapped. Tracks
// 1..N go to outputs 0..N-1. A format 0 file has one track, so it is split
// by channel: channels 0..N-1 go to outputs 0..N-1. Either map can be
// changed, and an output can rewrite every event's channel to one channel.
//
// Transport is standard MIDI:
//   start()   play from the top — All Notes Off and every controller's first
//             value in the file sent to each output, then play. Each run from
//             the top begins the same way.
//   stop()    stop where it is, All Notes Off; the playhead is kept.
//   resume()  play on from the playhead (MIDI Continue).
// With loop on, reaching the end sends All Notes Off and plays again from
// the top; with loop off the sequencer stops and sends All Notes Off.
//
// Program Changes play on the first pass of a Start only. A program is the
// voice's setup, not the song: a file names its sounds at tick 0, and a run
// from the top should load them so every run begins the same — but a loop
// wrap is the same run continuing, and a preset reloading on every wrap would
// undo anything the player has dialled since (Michael, 2026-09-14).
//
// The SmfReader's bytes must outlive the sequencer.
//
// Usage:
//   void sink(void*, uint8_t output, const sbl::midi::MidiEvent& e) { ... }
//   sbl::midi::Sequencer<4> seq(sink, nullptr);
//   seq.load(smf);
//   seq.start();
//   seq.advance(elapsed_samples);   // from the control tick
 
#ifndef SBL_PROTOCOL_MIDI_SEQUENCER_HPP_
#define SBL_PROTOCOL_MIDI_SEQUENCER_HPP_
 
#include <cstdint>
 
#include <sbl/protocol/midi/smf_reader.hpp>
#include <sbl/protocol/midi/types.hpp>
 
namespace sbl::midi {
 
template<uint8_t Outputs = 4>
class Sequencer {
    static_assert(Outputs >= 1, "a sequencer needs an output");
 
public:
    static constexpr uint8_t OUTPUTS = Outputs;
    static constexpr uint8_t MAX_TRACKS = SmfReader::MAX_TRACKS;
    static constexpr uint8_t CHANNELS = 16;
    static constexpr uint8_t NO_OUTPUT = 0xFF;
    static constexpr uint8_t KEEP_CHANNEL = 0xFF;
    static constexpr uint8_t MAX_SNAPSHOT = 64;           ///< distinct (output, channel, controller) first values
    static constexpr uint32_t DEFAULT_TEMPO_US = 500000;  ///< 120 bpm: the SMF default
    static constexpr uint32_t DEFAULT_SAMPLE_RATE = 48000;
    static constexpr uint8_t ALL_NOTES_OFF = 123;
 
    using Sink = void (*)(void* context, uint8_t output, const MidiEvent& event);
 
    Sequencer(Sink sink, void* context) : sink_(sink), context_(context) {
        for (uint8_t o = 0; o < Outputs; ++o) output_channel_[o] = KEEP_CHANNEL;
    }
 
    /// Natural units, before start(): the rate advance() counts in.
    void set_sample_rate(uint32_t hz) { sample_rate_ = hz > 0 ? hz : DEFAULT_SAMPLE_RATE; }
 
    /// Take a parsed file and apply the default map. Stops playback.
    bool load(const SmfReader& smf) {
        playing_ = false;
        loaded_ = smf.error() == SmfError::None && smf.track_count() > 0;
        if (!loaded_) return false;
        format_ = smf.format();
        track_count_ = smf.track_count();
        ticks_per_quarter_ = smf.ticks_per_quarter();
        for (uint8_t t = 0; t < MAX_TRACKS; ++t) {
            tracks_[t] = t < track_count_ ? smf.track(t) : SmfTrack{};
            track_output_[t] = (t >= 1 && t - 1 < Outputs) ? static_cast<uint8_t>(t - 1) : NO_OUTPUT;
        }
        for (uint8_t c = 0; c < CHANNELS; ++c) channel_output_[c] = c < Outputs ? c : NO_OUTPUT;
        rewind();
        scan();
        finished_ = false;
        return true;
    }
 
    /// Format 1: which output a track plays into (NO_OUTPUT for none).
    void set_track_output(uint8_t track, uint8_t output) {
        if (track >= MAX_TRACKS) return;
        track_output_[track] = output < Outputs ? output : NO_OUTPUT;
        if (loaded_) scan();
    }
 
    /// Format 0: which output a channel plays into (NO_OUTPUT for none).
    void set_channel_output(uint8_t channel, uint8_t output) {
        if (channel >= CHANNELS) return;
        channel_output_[channel] = output < Outputs ? output : NO_OUTPUT;
        if (loaded_) scan();
    }
 
    /// Send every event on an output on this channel (KEEP_CHANNEL to leave them).
    void set_output_channel(uint8_t output, uint8_t channel) {
        if (output >= Outputs) return;
        output_channel_[output] = channel < CHANNELS ? channel : KEEP_CHANNEL;
        if (loaded_) scan();
    }
 
    void set_loop(bool on) { loop_ = on; }
    bool looping() const { return loop_; }
 
    // ─── Transport (standard MIDI) ───────────────────────────────────
 
    /// Start: play from the top with every output reset.
    void start() {
        if (!loaded_) return;
        all_notes_off();
        for (uint8_t i = 0; i < snapshot_count_; ++i) {
            emit_cc(snapshot_[i].output, snapshot_[i].channel, snapshot_[i].controller, snapshot_[i].value);
        }
        rewind();
        pass_start_scaled_ = now_scaled_;
        pass_ = 0;
        finished_ = false;
        playing_ = true;
    }
 
    /// Stop: hold the playhead, silence the outputs.
    void stop() {
        if (!playing_) return;
        playing_ = false;
        all_notes_off();
    }
 
    /// Continue: play on from the playhead. Nothing to continue after the end.
    void resume() {
        if (loaded_ && !finished_) playing_ = true;
    }
 
    bool playing() const { return playing_; }
    bool finished() const { return finished_; }
    bool loaded() const { return loaded_; }
 
    /// Where the playhead is in the song, in microseconds from the top.
    uint64_t position_us() const { return song_us_; }
 
    /**
     * @brief Let `elapsed_samples` pass: emit every event that falls due
     *
     * Time counts while stopped too, so a resume picks up at the playhead
     * without replaying the pause.
     */
    void advance(uint32_t elapsed_samples) {
        const uint64_t step = static_cast<uint64_t>(elapsed_samples) * MICROS_PER_SECOND;
        if (!loaded_ || !playing_) {
            pass_start_scaled_ += step;   // the song does not move while stopped
            now_scaled_ += step;
            return;
        }
        now_scaled_ += step;
 
        for (;;) {
            uint8_t best = NO_TRACK;
            uint32_t best_tick = 0;
            for (uint8_t t = 0; t < track_count_; ++t) {
                const SmfEvent* ev = tracks_[t].peek();
                if (ev != nullptr && (best == NO_TRACK || ev->tick < best_tick)) {
                    best = t;
                    best_tick = ev->tick;
                }
            }
 
            if (best == NO_TRACK) {   // every track has ended
                if (!loop_ || song_us_ == 0) {
                    playing_ = false;
                    finished_ = true;
                    all_notes_off();
                    return;
                }
                all_notes_off();
                pass_start_scaled_ += song_us_ * sample_rate_;
                rewind();
                ++pass_;
                continue;
            }
 
            const uint64_t numerator =
                static_cast<uint64_t>(best_tick - last_tick_) * tempo_us_ + tick_remainder_;
            const uint64_t event_us = song_us_ + numerator / ticks_per_quarter_;
            if (pass_start_scaled_ + event_us * sample_rate_ > now_scaled_) return;   // not due yet
 
            song_us_ = event_us;
            tick_remainder_ = numerator % ticks_per_quarter_;
            last_tick_ = best_tick;
 
            const SmfEvent ev = *tracks_[best].peek();
            tracks_[best].pop();
            if (ev.kind == SmfEvent::Kind::Tempo && ev.tempo_us > 0) {
                tempo_us_ = ev.tempo_us;
            } else if (ev.kind == SmfEvent::Kind::Channel) {
                route(best, ev.midi);
            }
        }
    }
 
private:
    static constexpr uint64_t MICROS_PER_SECOND = 1000000;
    static constexpr uint8_t NO_TRACK = 0xFF;
 
    struct Controller {
        uint8_t output;
        uint8_t channel;
        uint8_t controller;
        uint8_t value;
    };
 
    void rewind() {
        for (uint8_t t = 0; t < track_count_; ++t) tracks_[t].rewind();
        tempo_us_ = DEFAULT_TEMPO_US;
        song_us_ = 0;
        last_tick_ = 0;
        tick_remainder_ = 0;
    }
 
    /// The output an event plays into, and its channel after any rewrite.
    bool destination(uint8_t track, const MidiEvent& e, uint8_t& output, uint8_t& channel) const {
        output = format_ == 0 ? channel_output_[e.channel & (CHANNELS - 1)] : track_output_[track];
        if (output >= Outputs) return false;
        channel = output_channel_[output] == KEEP_CHANNEL ? e.channel : output_channel_[output];
        return true;
    }
 
    void route(uint8_t track, MidiEvent e) {
        if (e.type == MessageType::ProgramChange && pass_ > 0) return;   // setup, not song
        uint8_t output = 0;
        uint8_t channel = 0;
        if (!destination(track, e, output, channel)) return;
        e.channel = channel;
        if (sink_ != nullptr) sink_(context_, output, e);
    }
 
    void emit_cc(uint8_t output, uint8_t channel, uint8_t controller, uint8_t value) {
        MidiEvent e;
        e.type = MessageType::ControlChange;
        e.channel = channel;
        e.data1 = controller;
        e.data2 = value;
        if (sink_ != nullptr) sink_(context_, output, e);
    }
 
    void all_notes_off() {
        for (uint8_t o = 0; o < Outputs; ++o) {
            for (uint8_t c = 0; c < CHANNELS; ++c) {
                if (used_channels_[o] & (1u << c)) emit_cc(o, c, ALL_NOTES_OFF, 0);
            }
        }
    }
 
    /// Which channels each output uses, and each controller's first value.
    void scan() {
        for (uint8_t o = 0; o < Outputs; ++o) used_channels_[o] = 0;
        snapshot_count_ = 0;
        for (uint8_t t = 0; t < track_count_; ++t) {
            SmfTrack cursor = tracks_[t];
            cursor.rewind();
            while (const SmfEvent* ev = cursor.peek()) {
                uint8_t output = 0;
                uint8_t channel = 0;
                if (ev->kind == SmfEvent::Kind::Channel && destination(t, ev->midi, output, channel)) {
                    used_channels_[output] |= static_cast<uint16_t>(1u << channel);
                    if (ev->midi.type == MessageType::ControlChange) remember(output, channel, ev->midi);
                }
                cursor.pop();
            }
        }
    }
 
    void remember(uint8_t output, uint8_t channel, const MidiEvent& e) {
        for (uint8_t i = 0; i < snapshot_count_; ++i) {
            const Controller& c = snapshot_[i];
            if (c.output == output && c.channel == channel && c.controller == e.data1) return;
        }
        if (snapshot_count_ < MAX_SNAPSHOT) {
            snapshot_[snapshot_count_++] = Controller{output, channel, e.data1, e.data2};
        }
    }
 
    Sink sink_;
    void* context_;
 
    SmfTrack tracks_[MAX_TRACKS];
    uint8_t track_output_[MAX_TRACKS] = {};
    uint8_t channel_output_[CHANNELS] = {};
    uint8_t output_channel_[Outputs] = {};
    uint16_t used_channels_[Outputs] = {};
    Controller snapshot_[MAX_SNAPSHOT] = {};
    uint8_t snapshot_count_ = 0;
 
    uint16_t format_ = 0;
    uint8_t track_count_ = 0;
    uint16_t ticks_per_quarter_ = 1;
    uint32_t sample_rate_ = DEFAULT_SAMPLE_RATE;
 
    bool loaded_ = false;
    bool playing_ = false;
    bool finished_ = false;
    bool loop_ = false;
 
    uint32_t tempo_us_ = DEFAULT_TEMPO_US;
    uint64_t song_us_ = 0;            ///< time of the last event reached, from the top
    uint32_t last_tick_ = 0;
    uint64_t tick_remainder_ = 0;     ///< the part of a microsecond carried between segments
    uint64_t now_scaled_ = 0;         ///< samples elapsed × 10^6
    uint64_t pass_start_scaled_ = 0;  ///< where this pass of the song began, same units
    uint32_t pass_ = 0;               ///< 0 on the first pass after a Start; loop wraps count up
};
 
} // namespace sbl::midi
 
#endif // SBL_PROTOCOL_MIDI_SEQUENCER_HPP_