# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""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``.
"""
#: 13-bit millisecond timestamps.
TIMESTAMP_MASK = 0x1FFF
# Data bytes after the status, by high nibble (channel voice) or by status
# (system common). F0 (SysEx) and F7 are handled on their own.
_VOICE_LEN = (2, 2, 2, 2, 1, 1, 2) # 0x8_ .. 0xE_
_COMMON_LEN = {0xF1: 1, 0xF2: 2, 0xF3: 1, 0xF4: 0, 0xF5: 0, 0xF6: 0}
[docs]
def data_length(status):
"""How many data bytes follow ``status``; ``None`` for SysEx and stray bytes."""
if status < 0x80:
return None
if status < 0xF0:
return _VOICE_LEN[(status >> 4) - 8]
if status >= 0xF8:
return 0
return _COMMON_LEN.get(status)
def is_realtime(message):
return len(message) == 1 and message[0] >= 0xF8
[docs]
class Splitter:
"""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.
"""
def __init__(self):
self.desync = 0
self._running = 0
self._msg = None
self._want = 0
self._sysex = None
def feed(self, data):
out = []
for b in data:
if b >= 0xF8:
out.append(bytes((b,)))
continue
if self._sysex is not None:
if b < 0x80:
self._sysex.append(b)
continue
if b == 0xF7:
self._sysex.append(b)
out.append(bytes(self._sysex))
self._sysex = None
continue
self._sysex = None # any other status ends it unfinished
self.desync += 1
if b >= 0x80:
self._msg = None
if b == 0xF0:
self._sysex = bytearray((b,))
self._running = 0
continue
want = data_length(b)
if want is None: # a stray F7
self.desync += 1
continue
self._running = b if b < 0xF0 else 0
if want == 0:
out.append(bytes((b,)))
continue
self._msg = bytearray((b,))
self._want = want + 1
continue
if self._msg is None:
if not self._running:
self.desync += 1
continue
self._msg = bytearray((self._running,))
self._want = data_length(self._running) + 1
self._msg.append(b)
if len(self._msg) == self._want:
out.append(bytes(self._msg))
self._msg = None
return out
[docs]
class Decoder:
"""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.
"""
def __init__(self):
self.errors = 0
self._running = 0
self._sysex = None
self._ts = 0
[docs]
def reset(self):
"""Forget running status and any SysEx in progress (a new link)."""
self._running = 0
self._sysex = None
def decode(self, packet):
out = []
n = len(packet)
if n < 2 or (packet[0] & 0xC0) != 0x80:
self.errors += 1
return out
high = packet[0] & 0x3F
low = None
# Until a timestamp arrives, a data byte can only continue a SysEx
# (or, from a lax sender, run on from the last packet's status).
ts = (high << 7) | (self._ts & 0x7F)
after_ts = False
msg = None
msg_ts = ts
want = 0
i = 1
while i < n:
b = packet[i]
i += 1
if b & 0x80 and not after_ts:
l = b & 0x7F
if low is not None and l < low:
high = (high + 1) & 0x3F
low = l
ts = (high << 7) | l
after_ts = True
continue
if b & 0x80:
after_ts = False
if b >= 0xF8:
out.append((ts, bytes((b,))))
continue
if msg is not None: # a status before the last message finished
self.errors += 1
msg = None
if self._sysex is not None:
if b == 0xF7:
self._sysex.append(b)
out.append((ts, bytes(self._sysex)))
self._sysex = None
continue
self.errors += 1
self._sysex = None
if b == 0xF0:
self._sysex = bytearray((b,))
self._running = 0
continue
want = data_length(b)
if want is None:
self.errors += 1
continue
self._running = b if b < 0xF0 else 0
if want == 0:
out.append((ts, bytes((b,))))
continue
msg = bytearray((b,))
msg_ts = ts
want += 1
continue
# A data byte.
after_ts = False
if self._sysex is not None:
self._sysex.append(b)
continue
if msg is None:
if not self._running:
self.errors += 1
continue
msg = bytearray((self._running,))
msg_ts = ts
want = data_length(self._running) + 1
msg.append(b)
if len(msg) == want:
out.append((msg_ts, bytes(msg)))
msg = None
if msg is not None: # only SysEx may continue into the next packet
self.errors += 1
self._ts = ts
return out
[docs]
class Encoder:
"""``(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.
"""
def __init__(self, running_status=True):
self.running_status = running_status
self._queue = []
self._sysex = None # [timestamp, message, next index] while one spans packets
def put(self, timestamp, message):
message = bytes(message)
_check_message(message)
self._queue.append((timestamp & TIMESTAMP_MASK, message))
def pending(self):
return bool(self._queue or self._sysex)
def packet(self, size):
if size < 5:
raise ValueError("a BLE-MIDI packet needs at least 5 bytes")
if not self.pending():
return None
p = _Packet(size)
sysex = self._sysex
if sysex is not None:
# Real-time messages queued behind the SysEx go in first; the
# SysEx's data bytes then run on after them.
i = 0
while i < len(self._queue):
ts, message = self._queue[i]
if message[0] >= 0xF8:
if not p.stamp(ts, 1):
break
p.put(message)
self._queue.pop(i)
else:
i += 1
if not self._sysex_body(p, sysex):
return p.finish(sysex[0])
self._sysex = None
while self._queue:
ts, message = self._queue[0]
status = message[0]
if status == 0xF0:
if not p.stamp(ts, 2):
break
self._queue.pop(0)
p.put(message[:1])
p.running = 0
sysex = [ts, message, 1]
if not self._sysex_body(p, sysex):
self._sysex = sysex
break
continue
if self.running_status and status == p.running:
if p.have_ts and ts == p.ts and p.last_was_voice:
if not p.fits(len(message) - 1):
break
elif not p.stamp(ts, len(message) - 1):
break
p.put(message[1:])
else:
if not p.stamp(ts, len(message)):
break
p.put(message)
if status < 0xF8:
p.running = status if status < 0xF0 else 0
p.last_was_voice = status < 0xF0
self._queue.pop(0)
return p.finish(self._queue[0][0] if self._queue else 0)
def _sysex_body(self, p, sysex):
"""Put as much of a SysEx as fits; ``True`` once its F7 is in."""
ts, message, index = sysex
last = len(message) - 1 # the F7
take = min(last - index, p.room())
if take > 0:
p.put(message[index : index + take])
index += take
p.last_was_voice = False
sysex[2] = index
if index < last:
return False
if p.have_ts:
ts = sysex[0] = p.ts
if not p.stamp(ts, 1):
return False
p.put(message[last:])
p.last_was_voice = False
return True
def _check_message(message):
if not message or message[0] < 0x80:
raise ValueError("a MIDI message starts with its status byte")
status = message[0]
if status == 0xF0:
if message[-1] != 0xF7 or len(message) < 2:
raise ValueError("a SysEx message ends with F7")
body = message[1:-1]
else:
want = data_length(status)
if want is None or len(message) != want + 1:
raise ValueError("not one complete MIDI message: {}".format(message))
body = message[1:]
for b in body:
if b & 0x80:
raise ValueError("a status byte inside a message: {}".format(message))
class _Packet:
"""One packet being built: the header, then stamped messages."""
def __init__(self, size):
self.size = size
self.buf = bytearray(1) # the header, filled in by finish()
self.have_ts = False
self.ts = 0
self.high = 0
self.low = 0
self.running = 0
self.first_high = 0
self.last_was_voice = False
def room(self):
return self.size - len(self.buf)
def fits(self, n):
return len(self.buf) + n <= self.size
def stamp(self, ts, n):
"""Add a timestamp byte followed by ``n`` more bytes, if both fit and
the timestamp is expressible here (it may only move forward, by at
most one rollover of the low seven bits)."""
if not self.fits(n + 1):
return False
high = ts >> 7
low = ts & 0x7F
if self.have_ts:
if high == self.high and low >= self.low:
pass
elif high == (self.high + 1) & 0x3F and low < self.low:
self.high = high
else:
return False
else:
self.high = high
self.first_high = high
self.low = low
self.ts = ts
self.have_ts = True
self.buf.append(0x80 | low)
return True
def put(self, data):
self.buf.extend(data)
def finish(self, fallback_ts):
high = self.first_high if self.have_ts else (fallback_ts >> 7) & 0x3F
self.buf[0] = 0x80 | high
return bytes(self.buf)
[docs]
def encode(messages, size, running_status=True):
"""Every packet for ``messages``, a list of ``(timestamp, message)``."""
e = Encoder(running_status)
for ts, message in messages:
e.put(ts, message)
packets = []
while True:
p = e.packet(size)
if p is None:
return packets
packets.append(p)
[docs]
def decode(packets):
"""Every ``(timestamp, message)`` in ``packets``, with a fresh decoder."""
d = Decoder()
out = []
for p in packets:
out.extend(d.decode(p))
return out