sysex_accumulator.hpp

Go to the documentation of this file.

#pragma once
 
// SysExAccumulator — shared MIDI SysEx aggregation state machine.
//
// MIDI SysEx messages (F0 ... F7) can span multiple transport packets:
// Android's MIDI API delivers raw bytes whenever they arrive, BLE MIDI
// fragments into ~20-byte chunks, USB-MIDI sends 4-byte event packets,
// etc. None of those transports guarantee a full sysex arrives in one
// delivery. This accumulator buffers until F7 or an abort, then emits
// the complete payload.
//
// State machine:
//
//   Idle     --[F0]-->   Buffering
//   Buffering --[data]->  Buffering (append)
//   Buffering --[F7]-->   emit complete, back to Idle
//   Buffering --[status != F7, != realtime]--> emit aborted, retry with status
//   Any       --[realtime (F8-FF except F7)]--> pass-through (realtime bytes
//                         can interrupt sysex without terminating it per
//                         the MIDI 1.0 spec — they're delivered outside
//                         the sysex stream).
//
// The accumulator is not thread-safe; wrap it per-port. Android's MIDI
// receiver is single-threaded per device, so the per-port model fits.
//
// RT-safety contract:
//
//   - Call reserve(N) before entering the audio/MIDI callback, where N is at
//     least the largest F0...F7 payload the port will accept.
//   - After that preparation, feed(), reset(), in_progress(), and
//     partial_size() do not allocate while messages stay within the reserved
//     size.
//   - The emit callback and its destination storage are caller-owned. Keep
//     the SysexEmitFn object and any payload consumer preconstructed and
//     allocation-free when using this accumulator from realtime code.
//
// Unit tests live in test/test_sysex_accumulator.cpp — see that file
// for coverage of the edge cases referenced in the state machine above.
 
#include <cstdint>
#include <functional>
#include <vector>
 
namespace pulp::midi {

using SysexEmitFn =
    std::function<void(const std::vector<std::uint8_t>& payload, bool complete)>;
 
class SysexAccumulator {
public:
    void reserve(std::size_t worst_case_bytes) {
        buffer_.reserve(worst_case_bytes);
    }

    enum class Classification {
        in_sysex,
        completed,
        aborted,
        passthrough,
    };
 
    Classification feed(std::uint8_t byte, const SysexEmitFn& emit) {
        // Realtime messages F8-FE are delivered asynchronously and
        // don't participate in sysex framing. Pass them through.
        if (is_realtime(byte)) return Classification::passthrough;
 
        if (!in_sysex_) {
            if (byte == 0xF0) {
                in_sysex_ = true;
                buffer_.clear();
                buffer_.push_back(0xF0);
                return Classification::in_sysex;
            }
            // Regular short-message byte — caller handles it.
            return Classification::passthrough;
        }
 
        // In-sysex branch.
        if (byte == 0xF7) {
            buffer_.push_back(0xF7);
            emit(buffer_, /*complete=*/true);
            in_sysex_ = false;
            buffer_.clear();
            return Classification::completed;
        }
 
        if (is_status(byte)) {
            // New status interrupted an unterminated F0. Flush the
            // partial payload (without F7) and return without consuming
            // the aborter — caller re-feeds it as a fresh status.
            emit(buffer_, /*complete=*/false);
            in_sysex_ = false;
            buffer_.clear();
            return Classification::aborted;
        }
 
        // Normal data byte inside an active sysex.
        buffer_.push_back(byte);
        return Classification::in_sysex;
    }

    void feed(const std::uint8_t* data, std::size_t count,
              const SysexEmitFn& emit) {
        for (std::size_t i = 0; i < count; ++i) {
            auto cls = feed(data[i], emit);
            if (cls == Classification::aborted) {
                // Re-feed the aborter byte as a fresh status.
                feed(data[i], emit);
            }
        }
    }

    bool in_progress() const noexcept { return in_sysex_; }

    void reset() noexcept {
        in_sysex_ = false;
        buffer_.clear();
    }

    std::size_t partial_size() const noexcept { return buffer_.size(); }
 
private:
    static bool is_status(std::uint8_t b) noexcept { return (b & 0x80) != 0; }
    static bool is_realtime(std::uint8_t b) noexcept {
        // MIDI 1.0 System Realtime Messages occupy 0xF8-0xFF, minus
        // 0xF7 (EOX, handled explicitly in feed()). 0xF9 and 0xFD are
        // officially undefined/reserved by MIDI 1.0, but the contract
        // documented at the top of this file — and the behavior
        // required by transports that emit them — is that everything
        // in 0xF8-0xFF *except F7* passes through without disturbing
        // the SysEx state machine. Treating 0xF9/0xFD as generic
        // status bytes aborted otherwise-valid SysEx on devices that
        // forward the reserved codes.
        //
        // Pass-through is safe because the accumulator only classifies
        // the byte — the caller's normal short-message path decides
        // whether to ignore, log, or forward the reserved code.
        return b >= 0xF8 && b <= 0xFF;
    }
 
    bool in_sysex_ = false;
    std::vector<std::uint8_t> buffer_;
};
 
} // namespace pulp::midi