Files
qlcplus/padeditor/preset.py
T
jimmyandClaude Opus 5.5 63b3129cca Add an SMC-PAD preset editor that saves pad colours the way MidiSuite does.
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>
2026-10-21 19:30:34 +13:00

312 lines
11 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""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)