smf_reader.hpp

Go to the documentation of this file.

// sbl/protocol/midi/smf_reader.hpp — Standard MIDI File reader (FDP-078)
//
// Reads a Standard MIDI File already in memory: no filesystem, no allocation,
// nothing copied. The reader checks the header and finds the track chunks;
// an SmfTrack walks one track's events in order, one at a time.
//
// What it understands (Standard MIDI Files 1.0, shelf `smf-1-0`):
//   - formats 0 and 1 (format 2 is refused)
//   - ticks-per-quarter-note division (SMPTE division is refused)
//   - variable-length delta times
//   - running status, which carries across delta times and is cancelled by
//     SysEx and meta events (p. 5, p. 7)
//   - the meta events a player needs: Set Tempo, Time Signature, Track Name
//     and End of Track (p. 8); other meta events and SysEx are skipped
//   - chunks that are not MTrk, which are skipped
//
// Usage:
//   sbl::midi::SmfReader smf;
//   if (smf.parse(bytes, size) != sbl::midi::SmfError::None) { ... }
//   sbl::midi::SmfTrack track = smf.track(1);
//   while (const sbl::midi::SmfEvent* ev = track.peek()) { ...; track.pop(); }
 
#ifndef SBL_PROTOCOL_MIDI_SMF_READER_HPP_
#define SBL_PROTOCOL_MIDI_SMF_READER_HPP_
 
#include <cstddef>
#include <cstdint>
 
#include <sbl/protocol/midi/types.hpp>
 
namespace sbl::midi {
 
enum class SmfError : uint8_t {
    None,
    NotSmf,              ///< no MThd header chunk at the start
    BadHeader,           ///< header too short, zero division, or format 0 with more than one track
    UnsupportedFormat,   ///< format 2
    SmpteDivision,       ///< division in SMPTE frames rather than ticks per quarter note
    TooManyTracks,       ///< more tracks than SmfReader::MAX_TRACKS
    Truncated,           ///< a chunk runs past the end of the data, or tracks are missing
};
 
/// One event from a track, with its absolute tick.
struct SmfEvent {
    enum class Kind : uint8_t { Channel, Tempo, TimeSignature, TrackName, EndOfTrack };
 
    Kind kind = Kind::EndOfTrack;
    uint32_t tick = 0;                ///< ticks from the start of the track
    MidiEvent midi{};                 ///< Channel
    uint32_t tempo_us = 0;            ///< Tempo: microseconds per quarter note
    uint8_t numerator = 0;            ///< TimeSignature
    uint8_t denominator_power = 0;    ///< TimeSignature: the denominator is 2^power
    const uint8_t* text = nullptr;    ///< TrackName: points into the file, not terminated
    uint32_t text_length = 0;
};
 
/**
 * @brief A cursor over one track chunk
 *
 * peek() decodes the next event without consuming it; pop() consumes it. A
 * malformed event ends the track and sets error(). The file's bytes must
 * outlive the cursor.
 */
class SmfTrack {
public:
    SmfTrack() = default;
    SmfTrack(const uint8_t* data, uint32_t length) : data_(data), length_(length) { rewind(); }
 
    void rewind() {
        pos_ = 0;
        tick_ = 0;
        running_status_ = 0;
        has_pending_ = false;
        error_ = false;
        done_ = (data_ == nullptr);
    }
 
    /// The next event, or nullptr when the track has ended.
    const SmfEvent* peek() {
        if (!has_pending_ && !done_) has_pending_ = decode(pending_);
        return has_pending_ ? &pending_ : nullptr;
    }
 
    void pop() { has_pending_ = false; }
 
    bool done() const { return done_ && !has_pending_; }
    bool error() const { return error_; }
 
private:
    static constexpr uint8_t STATUS_BIT = 0x80;
    static constexpr uint8_t META = 0xFF;
    static constexpr uint8_t SYSEX = 0xF0;
    static constexpr uint8_t SYSEX_ESCAPE = 0xF7;
    static constexpr uint8_t SYSTEM_FIRST = 0xF0;
    static constexpr uint8_t META_TRACK_NAME = 0x03;
    static constexpr uint8_t META_END_OF_TRACK = 0x2F;
    static constexpr uint8_t META_TEMPO = 0x51;
    static constexpr uint8_t META_TIME_SIGNATURE = 0x58;
    static constexpr uint32_t TEMPO_LENGTH = 3;
    static constexpr uint32_t TIME_SIGNATURE_LENGTH = 2;   ///< nn dd; the clock bytes are not used
    static constexpr uint8_t VLQ_MAX_BYTES = 4;
    static constexpr uint8_t VLQ_MORE = 0x80;
    static constexpr uint8_t VLQ_BITS = 0x7F;
    static constexpr uint8_t VLQ_SHIFT = 7;
    static constexpr uint8_t STATUS_KIND_MASK = 0xF0;
    static constexpr uint8_t CHANNEL_MASK = 0x0F;
    static constexpr uint8_t PROGRAM_CHANGE = 0xC0;
    static constexpr uint8_t CHANNEL_PRESSURE = 0xD0;
 
    bool fail() {
        error_ = true;
        done_ = true;
        return false;
    }
 
    bool read_vlq(uint32_t& out) {
        out = 0;
        for (uint8_t i = 0; i < VLQ_MAX_BYTES; ++i) {
            if (pos_ >= length_) return false;
            const uint8_t b = data_[pos_++];
            out = (out << VLQ_SHIFT) | (b & VLQ_BITS);
            if ((b & VLQ_MORE) == 0) return true;
        }
        return false;   // longer than four bytes: not a valid delta or length
    }
 
    /// Decode the next event a player cares about; skip the rest.
    bool decode(SmfEvent& ev) {
        while (pos_ < length_) {
            uint32_t delta = 0;
            if (!read_vlq(delta)) return fail();
            tick_ += delta;
            if (pos_ >= length_) return fail();
            const uint8_t lead = data_[pos_];
 
            if (lead == META) {
                if (pos_ + 2 > length_) return fail();
                const uint8_t type = data_[pos_ + 1];
                pos_ += 2;
                uint32_t len = 0;
                if (!read_vlq(len) || pos_ + len > length_) return fail();
                const uint32_t body = pos_;
                pos_ += len;
                running_status_ = 0;   // meta events cancel running status
 
                ev = SmfEvent{};
                ev.tick = tick_;
                switch (type) {
                    case META_END_OF_TRACK:
                        ev.kind = SmfEvent::Kind::EndOfTrack;
                        done_ = true;
                        return true;
                    case META_TEMPO:
                        if (len < TEMPO_LENGTH) return fail();
                        ev.kind = SmfEvent::Kind::Tempo;
                        ev.tempo_us = (static_cast<uint32_t>(data_[body]) << 16) |
                                      (static_cast<uint32_t>(data_[body + 1]) << 8) |
                                      data_[body + 2];
                        return true;
                    case META_TIME_SIGNATURE:
                        if (len < TIME_SIGNATURE_LENGTH) return fail();
                        ev.kind = SmfEvent::Kind::TimeSignature;
                        ev.numerator = data_[body];
                        ev.denominator_power = data_[body + 1];
                        return true;
                    case META_TRACK_NAME:
                        ev.kind = SmfEvent::Kind::TrackName;
                        ev.text = data_ + body;
                        ev.text_length = len;
                        return true;
                    default:
                        continue;   // a meta event a player doesn't need
                }
            }
 
            if (lead == SYSEX || lead == SYSEX_ESCAPE) {
                ++pos_;
                uint32_t len = 0;
                if (!read_vlq(len) || pos_ + len > length_) return fail();
                pos_ += len;
                running_status_ = 0;   // SysEx cancels running status too
                continue;
            }
 
            uint8_t status = running_status_;
            if (lead & STATUS_BIT) {
                if (lead >= SYSTEM_FIRST) return fail();   // no other system messages in a track
                status = lead;
                running_status_ = lead;
                ++pos_;
            } else if (status == 0) {
                return fail();   // data with no status in effect
            }
 
            const uint8_t kind = status & STATUS_KIND_MASK;
            const uint8_t data_bytes = (kind == PROGRAM_CHANGE || kind == CHANNEL_PRESSURE) ? 1 : 2;
            if (pos_ + data_bytes > length_) return fail();
 
            ev = SmfEvent{};
            ev.kind = SmfEvent::Kind::Channel;
            ev.tick = tick_;
            ev.midi.type = static_cast<MessageType>(kind);
            ev.midi.channel = status & CHANNEL_MASK;
            ev.midi.data1 = data_[pos_];
            ev.midi.data2 = data_bytes == 2 ? data_[pos_ + 1] : 0;
            pos_ += data_bytes;
            return true;
        }
        done_ = true;   // ran out without End of Track: accept the end
        return false;
    }
 
    const uint8_t* data_ = nullptr;
    uint32_t length_ = 0;
    uint32_t pos_ = 0;
    uint32_t tick_ = 0;
    uint8_t running_status_ = 0;
    bool has_pending_ = false;
    bool done_ = true;
    bool error_ = false;
    SmfEvent pending_{};
};
 
class SmfReader {
public:
    static constexpr uint8_t MAX_TRACKS = 16;
 
    /// Check the header and find the tracks. The bytes must outlive the reader and its tracks.
    SmfError parse(const uint8_t* data, size_t size) {
        *this = SmfReader{};
        if (data == nullptr || size < CHUNK_HEADER || !id_is(data, "MThd")) return fail(SmfError::NotSmf);
        const uint32_t header_length = be32(data + ID_LENGTH);
        if (header_length < HEADER_BODY || size < CHUNK_HEADER + header_length) return fail(SmfError::BadHeader);
 
        const uint16_t format = be16(data + CHUNK_HEADER);
        const uint16_t tracks = be16(data + CHUNK_HEADER + 2);
        const uint16_t division = be16(data + CHUNK_HEADER + 4);
        if (division & SMPTE_DIVISION_BIT) return fail(SmfError::SmpteDivision);
        if (division == 0) return fail(SmfError::BadHeader);
        if (format > 1) return fail(SmfError::UnsupportedFormat);
        if (format == 0 && tracks != 1) return fail(SmfError::BadHeader);
        if (tracks > MAX_TRACKS) return fail(SmfError::TooManyTracks);
 
        size_t pos = CHUNK_HEADER + header_length;
        uint8_t found = 0;
        while (found < tracks) {
            if (pos + CHUNK_HEADER > size) return fail(SmfError::Truncated);
            const uint32_t length = be32(data + pos + ID_LENGTH);
            if (pos + CHUNK_HEADER + length > size) return fail(SmfError::Truncated);
            if (id_is(data + pos, "MTrk")) {
                track_data_[found] = data + pos + CHUNK_HEADER;
                track_length_[found] = length;
                ++found;
            }   // any other chunk: skipped, as the spec asks
            pos += CHUNK_HEADER + length;
        }
 
        format_ = format;
        track_count_ = found;
        ticks_per_quarter_ = division;
        return SmfError::None;
    }
 
    SmfError error() const { return error_; }
    uint16_t format() const { return format_; }
    uint8_t track_count() const { return track_count_; }
    uint16_t ticks_per_quarter() const { return ticks_per_quarter_; }
 
    /// A fresh cursor at the start of track `index`; an empty one if out of range.
    SmfTrack track(uint8_t index) const {
        if (index >= track_count_) return SmfTrack{};
        return SmfTrack{track_data_[index], track_length_[index]};
    }
 
private:
    static constexpr size_t ID_LENGTH = 4;
    static constexpr size_t CHUNK_HEADER = 8;      ///< id + 32-bit length
    static constexpr uint32_t HEADER_BODY = 6;     ///< format, ntrks, division
    static constexpr uint16_t SMPTE_DIVISION_BIT = 0x8000;
 
    static bool id_is(const uint8_t* p, const char* id) {
        for (size_t i = 0; i < ID_LENGTH; ++i) {
            if (p[i] != static_cast<uint8_t>(id[i])) return false;
        }
        return true;
    }
    static uint16_t be16(const uint8_t* p) { return static_cast<uint16_t>((p[0] << 8) | p[1]); }
    static uint32_t be32(const uint8_t* p) {
        return (static_cast<uint32_t>(p[0]) << 24) | (static_cast<uint32_t>(p[1]) << 16) |
               (static_cast<uint32_t>(p[2]) << 8) | p[3];
    }
 
    SmfError fail(SmfError e) {
        error_ = e;
        return e;
    }
 
    const uint8_t* track_data_[MAX_TRACKS] = {};
    uint32_t track_length_[MAX_TRACKS] = {};
    SmfError error_ = SmfError::None;
    uint16_t format_ = 0;
    uint8_t track_count_ = 0;
    uint16_t ticks_per_quarter_ = 0;
};
 
} // namespace sbl::midi
 
#endif // SBL_PROTOCOL_MIDI_SMF_READER_HPP_