bledev.midi_codec

The BLE-MIDI packet codec: MIDI 1.0 messages in and out of GATT packets.

Pure Python with no imports, so it runs anywhere bledev does, and a board, a laptop and a browser share one implementation. The radio side is bledev.midi; this module only turns bytes into bytes.

The format is the MMA/Apple “MIDI over Bluetooth Low Energy” (BLE-MIDI 1.0) one. Each packet is one characteristic write or notification:

header  timestamp  status data...  [timestamp] [status] data...  ...
10hhhhhh 1lllllll

A timestamp is 13 bits of milliseconds: six high bits in the header, seven low bits in the byte before each message. A low part smaller than the one before it in the same packet means the high part rolled over. Beyond that:

  • Running status. A message with the same channel status as the one before may leave the status out, and also the timestamp when it is the same. The Decoder keeps running status across packets, because a sender may rely on it; the Encoder uses it only inside a packet, so a receiver that lost the previous packet still decodes this one.

  • System exclusive can span packets. A continuation packet is the header followed straight by data bytes; the closing F7 has its own timestamp.

  • Real-time messages (F8-FF) may sit anywhere, including in the middle of a SysEx or between a status and its data, each with its own timestamp. The encoder slips them into a SysEx that spans packets, so a clock tick doesn’t wait for a long dump to finish.

  • Any other message fits in one packet; the encoder never splits one, and the decoder drops one that a sender did split.

A message’s timestamp is the one before its status byte (or before its data, under running status). A SysEx carries the timestamp before its F7.

Messages are plain MIDI bytes, complete with their status byte, the same bytes a midiports port carries. A SysEx is one message, F0 ... F7.

bledev.midi_codec.TIMESTAMP_MASK = 8191

13-bit millisecond timestamps.

bledev.midi_codec.data_length(status)[source]

How many data bytes follow status; None for SysEx and stray bytes.

class bledev.midi_codec.Splitter[source]

Bases: object

A MIDI 1.0 byte stream in, complete messages out, SysEx included.

What a port’s write() hands over is a stream: it may use running status, split a message across calls, or drop a real-time byte into the middle of another message. feed() returns the messages it completes, each as bytes with its status byte. SysEx is kept whole, F0 to F7. A data byte with no status to attach to is counted in desync and dropped.

class bledev.midi_codec.Decoder[source]

Bases: object

BLE-MIDI packets in, (timestamp, message) pairs out.

One decoder per link and direction, because running status and a SysEx in progress carry from one packet to the next. timestamp is the sender’s 13-bit millisecond clock. Anything malformed is counted in errors and skipped rather than guessed at.

reset()[source]

Forget running status and any SysEx in progress (a new link).

class bledev.midi_codec.Encoder(running_status=True)[source]

Bases: object

(timestamp, message) pairs in, BLE-MIDI packets out.

put() queues a complete message; packet(size) returns the next packet of at most size bytes (mtu - 3), or None when nothing is queued. Messages go out in the order they were put, with one exception MIDI 1.0 also makes: while a SysEx is spread over several packets, real-time messages queued behind it are slipped into it, so a clock tick doesn’t wait for a long dump to finish. With running_status (the default) a repeated channel status is left out inside a packet, and the timestamp too when it hasn’t changed.

bledev.midi_codec.encode(messages, size, running_status=True)[source]

Every packet for messages, a list of (timestamp, message).

bledev.midi_codec.decode(packets)[source]

Every (timestamp, message) in packets, with a fresh decoder.