The record layout and writes come from usbmon captures of MidiSuite: a pad colour is one three-byte write to its preset address, which lights the lamp straight away, and Save is the empty write that keeps it after a power cycle. Pad records are channel, note, min and max velocity, RGB, then Led. Tempo, swing, pad curve, and transpose come from the global block, memory type 4. The factory image from MidiSuite's Reset is kept as a test fixture, and scripts/decode_usbmon.py prints the SysEx in a capture. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
312 lines
11 KiB
Python
312 lines
11 KiB
Python
"""SMC-PAD preset image: 8 × 3539 bytes, the map MidiSuite edits."""
|
||
|
||
from __future__ import annotations
|
||
|
||
IMAGE_LEN = 28312
|
||
PRESET_LEN = 3539
|
||
PRESET_COUNT = 8
|
||
|
||
BUTTON_COUNT = 5
|
||
BUTTON_LEN = 23
|
||
BUTTON_NAMES = ("Left", "Right", "Play", "Stop", "Record")
|
||
|
||
KNOB_AT = 115
|
||
KNOB_COUNT = 16
|
||
KNOB_LEN = 6
|
||
KNOB_BANK = 8
|
||
|
||
GAP_AT = 211
|
||
|
||
PAD_AT = 212
|
||
PAD_LEN = 26
|
||
PAD_COUNT = 128
|
||
PAGE_LEN = 16
|
||
PAGE_COUNT = 8
|
||
RGB_AT = 4
|
||
|
||
# Global settings, memory type 4. Offsets are the fields MidiSuite's Glob
|
||
# panel showed against the factory block 78 00 32 04 00 00 02 00 01 01 00 00.
|
||
GLOBAL_LEN = 12
|
||
GLOBAL_TEMPO = 0 # two bytes, little-endian
|
||
GLOBAL_SWING = 2
|
||
GLOBAL_CURVE = 6
|
||
GLOBAL_TRANSPOSE = 7 # signed
|
||
|
||
# File bytes. Names are only values MidiSuite has shown for this pad's
|
||
# factory image, or a RAM probe on this pad has heard.
|
||
KNOB_TYPES = {0x00: "CC"}
|
||
BUTTON_TYPES = {0x02: "CC Push"}
|
||
|
||
# Set after a RAM-only probe hears a relative step from type 0x03.
|
||
RELATIVE_TYPE = 0x03
|
||
RELATIVE_CONFIRMED = False
|
||
|
||
FULL = 0xF0
|
||
SYSEX_ROOM = 16 # button bytes 6..21; byte 22 is the flag
|
||
|
||
|
||
def scale(value: int) -> int:
|
||
"""Map 0–255 onto the pad's 0–240 colour range."""
|
||
return (value * FULL + 127) // 255
|
||
|
||
|
||
def knob_type_names() -> dict[int, str]:
|
||
names = dict(KNOB_TYPES)
|
||
if RELATIVE_CONFIRMED:
|
||
names[RELATIVE_TYPE] = "Relative"
|
||
return names
|
||
|
||
|
||
def type_catalog() -> dict[str, list[dict[str, int | str]]]:
|
||
def rows(names: dict[int, str]) -> list[dict[str, int | str]]:
|
||
return [{"value": value, "name": name} for value, name in sorted(names.items())]
|
||
|
||
return {
|
||
"knob": rows(knob_type_names()),
|
||
"button": rows(BUTTON_TYPES),
|
||
}
|
||
|
||
|
||
class PresetError(ValueError):
|
||
pass
|
||
|
||
|
||
def _byte(value: object, label: str) -> int:
|
||
if isinstance(value, bool) or not isinstance(value, int) or not 0 <= value <= 255:
|
||
raise PresetError(f"{label} must be a byte")
|
||
return value
|
||
|
||
|
||
def _channel(value: object, label: str) -> int:
|
||
"""MIDI channel 1–16 as stored, which is 0–15."""
|
||
if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= 16:
|
||
raise PresetError(f"{label} must be MIDI channel 1–16")
|
||
return value - 1
|
||
|
||
|
||
def _hex(value: object, label: str) -> bytes:
|
||
if not isinstance(value, str) or len(value) % 2:
|
||
raise PresetError(f"{label} must be even-length hex")
|
||
try:
|
||
return bytes.fromhex(value)
|
||
except ValueError as exc:
|
||
raise PresetError(f"{label} is not hex") from exc
|
||
|
||
|
||
def unpack(image: bytes) -> dict:
|
||
if len(image) != IMAGE_LEN:
|
||
raise PresetError(f"preset image is {len(image)} bytes, expected {IMAGE_LEN}")
|
||
presets = []
|
||
for index in range(PRESET_COUNT):
|
||
block = image[index * PRESET_LEN:(index + 1) * PRESET_LEN]
|
||
presets.append(_unpack_preset(block))
|
||
return {"presets": presets, "types": type_catalog(), "relative": RELATIVE_CONFIRMED}
|
||
|
||
|
||
def pack(document: dict) -> bytes:
|
||
presets = document.get("presets")
|
||
if not isinstance(presets, list) or len(presets) != PRESET_COUNT:
|
||
raise PresetError(f"expected {PRESET_COUNT} presets")
|
||
out = bytearray()
|
||
for index, preset in enumerate(presets):
|
||
out += _pack_preset(preset, index)
|
||
if len(out) != IMAGE_LEN:
|
||
raise PresetError(f"packed {len(out)} bytes, expected {IMAGE_LEN}")
|
||
return bytes(out)
|
||
|
||
|
||
def colour_offset(preset: int, index: int) -> int:
|
||
"""Where one pad's colour sits. MidiSuite writes only this address."""
|
||
if not 0 <= preset < PRESET_COUNT:
|
||
raise PresetError(f"preset {preset + 1} is not on this controller")
|
||
if not 0 <= index < PAD_COUNT:
|
||
raise PresetError(f"pad {index + 1} is not on this controller")
|
||
return preset * PRESET_LEN + PAD_AT + index * PAD_LEN + RGB_AT
|
||
|
||
|
||
def unpack_global(raw: bytes) -> dict:
|
||
if len(raw) != GLOBAL_LEN:
|
||
raise PresetError(f"global block is {len(raw)} bytes, expected {GLOBAL_LEN}")
|
||
return {
|
||
"tempo": int.from_bytes(raw[GLOBAL_TEMPO:GLOBAL_TEMPO + 2], "little"),
|
||
"swing": raw[GLOBAL_SWING],
|
||
"curve": raw[GLOBAL_CURVE],
|
||
"transpose": int.from_bytes(raw[GLOBAL_TRANSPOSE:GLOBAL_TRANSPOSE + 1], "little", signed=True),
|
||
"raw": raw.hex(),
|
||
}
|
||
|
||
|
||
def pack_global(block: dict) -> bytes:
|
||
"""The named fields over the bytes that were read, so unknown ones stay put."""
|
||
out = bytearray(_hex(block.get("raw", ""), "global block"))
|
||
if len(out) != GLOBAL_LEN:
|
||
raise PresetError(f"global block is {len(out)} bytes, expected {GLOBAL_LEN}")
|
||
tempo = block.get("tempo")
|
||
if isinstance(tempo, bool) or not isinstance(tempo, int) or not 1 <= tempo <= 0xFFFF:
|
||
raise PresetError("tempo must be a whole number of BPM")
|
||
out[GLOBAL_TEMPO:GLOBAL_TEMPO + 2] = tempo.to_bytes(2, "little")
|
||
out[GLOBAL_SWING] = _byte(block.get("swing"), "swing")
|
||
out[GLOBAL_CURVE] = _byte(block.get("curve"), "pad curve")
|
||
transpose = block.get("transpose")
|
||
if isinstance(transpose, bool) or not isinstance(transpose, int) or not -128 <= transpose <= 127:
|
||
raise PresetError("transpose must be -128 to 127")
|
||
out[GLOBAL_TRANSPOSE] = transpose & 0xFF
|
||
return bytes(out)
|
||
|
||
|
||
def changed_ranges(before: bytes, after: bytes, limit: int = 64) -> list[tuple[int, bytes]]:
|
||
"""Coalesce differing bytes, then split each run into write-sized pieces."""
|
||
if len(before) != len(after):
|
||
raise PresetError(f"cannot compare {len(before)} bytes with {len(after)}")
|
||
runs: list[tuple[int, int]] = []
|
||
start = None
|
||
for index, (old, new) in enumerate(zip(before, after)):
|
||
if old != new:
|
||
if start is None:
|
||
start = index
|
||
elif start is not None:
|
||
runs.append((start, index))
|
||
start = None
|
||
if start is not None:
|
||
runs.append((start, len(after)))
|
||
pieces: list[tuple[int, bytes]] = []
|
||
for run_at, run_end in runs:
|
||
at = run_at
|
||
while at < run_end:
|
||
stop = min(run_end, at + limit)
|
||
pieces.append((at, after[at:stop]))
|
||
at = stop
|
||
return pieces
|
||
|
||
|
||
def _unpack_preset(block: bytes) -> dict:
|
||
buttons = []
|
||
for index in range(BUTTON_COUNT):
|
||
rec = block[index * BUTTON_LEN:(index + 1) * BUTTON_LEN]
|
||
length = rec[5]
|
||
if length > SYSEX_ROOM:
|
||
sysex, padding = rec[6:22], b""
|
||
else:
|
||
sysex, padding = rec[6:6 + length], rec[6 + length:22]
|
||
buttons.append({
|
||
"name": BUTTON_NAMES[index],
|
||
"type": rec[0],
|
||
"channel": rec[1] + 1,
|
||
"number": rec[2],
|
||
"min": rec[3],
|
||
"max": rec[4],
|
||
"sysex": sysex.hex(),
|
||
"padding": padding.hex(),
|
||
"led": rec[22],
|
||
})
|
||
knobs = []
|
||
for index in range(KNOB_COUNT):
|
||
at = KNOB_AT + index * KNOB_LEN
|
||
rec = block[at:at + KNOB_LEN]
|
||
knobs.append({
|
||
"type": rec[0],
|
||
"speed": rec[1],
|
||
"channel": rec[2] + 1,
|
||
"number": rec[3],
|
||
"left": rec[4],
|
||
"right": rec[5],
|
||
})
|
||
pads = []
|
||
for index in range(PAD_COUNT):
|
||
at = PAD_AT + index * PAD_LEN
|
||
rec = block[at:at + PAD_LEN]
|
||
pads.append({
|
||
"channel": rec[0] + 1,
|
||
"note": rec[1],
|
||
"min": rec[2],
|
||
"max": rec[3],
|
||
"rgb": [rec[4], rec[5], rec[6]],
|
||
"led": rec[7],
|
||
"tail": rec[8:].hex(),
|
||
})
|
||
return {"gap": block[GAP_AT], "buttons": buttons, "knobs": knobs, "pads": pads}
|
||
|
||
|
||
def _pack_preset(preset: dict, index: int) -> bytes:
|
||
out = bytearray(PRESET_LEN)
|
||
buttons = preset.get("buttons")
|
||
knobs = preset.get("knobs")
|
||
pads = preset.get("pads")
|
||
if not isinstance(buttons, list) or len(buttons) != BUTTON_COUNT:
|
||
raise PresetError(f"preset {index + 1} needs {BUTTON_COUNT} buttons")
|
||
if not isinstance(knobs, list) or len(knobs) != KNOB_COUNT:
|
||
raise PresetError(f"preset {index + 1} needs {KNOB_COUNT} knobs")
|
||
if not isinstance(pads, list) or len(pads) != PAD_COUNT:
|
||
raise PresetError(f"preset {index + 1} needs {PAD_COUNT} pads")
|
||
for number, button in enumerate(buttons):
|
||
out[number * BUTTON_LEN:(number + 1) * BUTTON_LEN] = _pack_button(button, index, number)
|
||
for number, knob in enumerate(knobs):
|
||
at = KNOB_AT + number * KNOB_LEN
|
||
out[at:at + KNOB_LEN] = _pack_knob(knob, index, number)
|
||
out[GAP_AT] = _byte(preset.get("gap", 0), f"preset {index + 1} gap")
|
||
for number, pad in enumerate(pads):
|
||
at = PAD_AT + number * PAD_LEN
|
||
rec = _pack_pad(pad, index, number)
|
||
room = PRESET_LEN - at
|
||
if len(rec) > room:
|
||
raise PresetError(f"preset {index + 1} pad {number + 1} does not fit")
|
||
out[at:at + len(rec)] = rec
|
||
return bytes(out)
|
||
|
||
|
||
def _pack_button(button: dict, preset: int, index: int) -> bytes:
|
||
label = f"preset {preset + 1} {BUTTON_NAMES[index]}"
|
||
sysex = _hex(button.get("sysex", ""), f"{label} sysex")
|
||
if len(sysex) > SYSEX_ROOM:
|
||
raise PresetError(f"{label} sysex is longer than {SYSEX_ROOM} bytes")
|
||
padding = _hex(button.get("padding", ""), f"{label} padding")
|
||
room = SYSEX_ROOM - len(sysex)
|
||
padding = padding[:room]
|
||
rec = bytearray(BUTTON_LEN)
|
||
rec[0] = _byte(button.get("type"), f"{label} type")
|
||
rec[1] = _channel(button.get("channel"), f"{label} channel")
|
||
rec[2] = _byte(button.get("number"), f"{label} number")
|
||
rec[3] = _byte(button.get("min"), f"{label} min")
|
||
rec[4] = _byte(button.get("max"), f"{label} max")
|
||
rec[5] = len(sysex)
|
||
rec[6:6 + len(sysex)] = sysex
|
||
rec[6 + len(sysex):22] = padding + bytes(room - len(padding))
|
||
rec[22] = _byte(button.get("led"), f"{label} led")
|
||
return bytes(rec)
|
||
|
||
|
||
def _pack_knob(knob: dict, preset: int, index: int) -> bytes:
|
||
label = f"preset {preset + 1} knob {index + 1}"
|
||
# Any stored type byte round-trips. The editor only offers names it has seen.
|
||
return bytes((
|
||
_byte(knob.get("type"), f"{label} type"),
|
||
_byte(knob.get("speed"), f"{label} speed"),
|
||
_channel(knob.get("channel"), f"{label} channel"),
|
||
_byte(knob.get("number"), f"{label} number"),
|
||
_byte(knob.get("left"), f"{label} left"),
|
||
_byte(knob.get("right"), f"{label} right"),
|
||
))
|
||
|
||
|
||
def _pack_pad(pad: dict, preset: int, index: int) -> bytes:
|
||
label = f"preset {preset + 1} pad {index + 1}"
|
||
rgb = pad.get("rgb")
|
||
if not isinstance(rgb, list) or len(rgb) != 3:
|
||
raise PresetError(f"{label} colour needs three bytes")
|
||
tail = _hex(pad.get("tail", ""), f"{label} tail")
|
||
stored = PAD_LEN if index < PAD_COUNT - 1 else PRESET_LEN - (PAD_AT + (PAD_COUNT - 1) * PAD_LEN)
|
||
tail_room = stored - 8
|
||
if len(tail) > tail_room:
|
||
raise PresetError(f"{label} tail is longer than {tail_room} bytes")
|
||
rec = bytearray(stored)
|
||
rec[0] = _channel(pad.get("channel"), f"{label} channel")
|
||
rec[1] = _byte(pad.get("note"), f"{label} note")
|
||
rec[2] = _byte(pad.get("min"), f"{label} min velocity")
|
||
rec[3] = _byte(pad.get("max"), f"{label} max velocity")
|
||
rec[4] = _byte(rgb[0], f"{label} red")
|
||
rec[5] = _byte(rgb[1], f"{label} green")
|
||
rec[6] = _byte(rgb[2], f"{label} blue")
|
||
rec[7] = _byte(pad.get("led"), f"{label} led")
|
||
rec[8:8 + len(tail)] = tail
|
||
return bytes(rec)
|