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
Decoderkeeps running status across packets, because a sender may rely on it; theEncoderuses 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
F7has 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;Nonefor SysEx and stray bytes.
- class bledev.midi_codec.Splitter[source]
Bases:
objectA 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 asbyteswith its status byte. SysEx is kept whole,F0toF7. A data byte with no status to attach to is counted indesyncand dropped.
- class bledev.midi_codec.Decoder[source]
Bases:
objectBLE-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.
timestampis the sender’s 13-bit millisecond clock. Anything malformed is counted inerrorsand skipped rather than guessed at.
- 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 mostsizebytes (mtu - 3), orNonewhen 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. Withrunning_status(the default) a repeated channel status is left out inside a packet, and the timestamp too when it hasn’t changed.