Colours and link group names now belong to the preset (by name, the DSP has no IDs) and travel in preset files. DJ Brake: limiters are left out instead of chosen; a slowly falling peak mark, an average bar, a warning before the limit, and it learns from real hits where the limiter sits on the meter. Pinch and double tap zoom are off. On touchscreens the dashboard only offers widget settings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
14 KiB
CLAUDE.md – guide for AI coding assistants
BetterDSPControl controls t.racks DSP 204 / DSP 408 loudspeaker processors. Read README.md (features, usage) and
PROTOCOL.md (wire protocol) first. This file explains how the code is built and what to watch out for.
Architecture
browser / phone ──HTTP + SSE──► server.py (asyncio, stdlib only) ──► dsp/device.py ──TCP 9761 or USB HID──► DSP
▲
desktop.py (pywebview window, logs in with a one-time token, no PIN)
pi_writer.py → pi_image.py (cloud-init SD card, installs server.py as a systemd service on a Raspberry Pi)
server.py– own HTTP server onasyncio.start_server(no framework). JSON API under/api/…, live updates as server-sent events on/api/events(App.broadcast).Appholds devices, auth, limiter data, remote access, backups. Config is one JSON file (config.json, gitignored) –load()/apply_config()/save().- Auth – 4-digit PIN, PBKDF2 hash in
config.json, session cookiedspsess(30 days), lockout after 5 failures. The desktop app logs in via/app-login?t=<one-time token>; app sessions live in memory only, skip the PIN and may toggle remote access (/api/remote) and the lock (/api/lock, server answers 423 while locked; withlock_dashthe window shows only the dashboard). Remote clients always need the PIN. dsp/device.py– oneDeviceper DSP: connect (TCP orusbhid.open_stream), handshake, config dump (50-byte chunks), command queue (one request in flight), meter polling (also keepalive), auto-reconnect. Mirrors changes within link groups locally and re-reads the config ~1.5 s after the last change (resync).dsp/protocol.py– frames, checksum, value scales, model layouts (MODELS["204"|"408"]), memory image ↔ state dict (parse_state/build_state_buffer), parameter → command (param_command), link masks, meter/limiter decoding. State values are raw device values; conversion to dB/Hz/ms happens in the UI (SPECinapp.js). Channels also carrypeq_bypass(master bypass,0x3C) and inputsgeq_bypass(0x49), stored as bit masks at the end of the memory image.- EQ curve (
app.js,drawCurve) – complex response per section: PEQ bands as RBJ biquads at 96 kHz, crossover filters from analog prototypes (Butterworth poles, Bessel polynomial normalised to −3 dB, Linkwitz-Riley = Butterworth²). Mag/Phase view (dsp.curvein localStorage), overlays of other channels (dsp.overlay.<device>). How exactly the DSP realises the Bessel and crossover filters is not verified – the curves are the textbook ones. - Audio test –
App.audio_test/set_test_level/check_audio_testinserver.py: entering saves the output gains (Device.test_saved, persisted inconfig.jsonso an interrupted test is undone on the next connect), lowers every output to −50 dB, flushes the queue and only then starts the generator (0x39); leaving switches the generator off first, then restores the gains. WhileDevice.test_activethe server only accepts the test controls (generator, test fader, output mutes) and the UI stays locked in the audio test tab. The state field isstate["test"] = {source, freq}. - SoundField (
static/soundfield.js, plan stored by the server assoundfieldinconfig.json, API/api/soundfield) – room plan in metres (x across, y from the stage wall, aim 0° = into the room). Free-field model: −6 dB per distance doubling, directivity from the coverage angle (−6 dB at its edges), tops summed by energy, subs with phase at the chosen frequency. Delays: mains/subs aligned at the reference point, delay/fill speakers at their target point plus the precedence offset. The canvas is only redrawn while dragging (never rebuilt), the side panels are rebuilt after a change; the local plan object stays the one being edited (a save does not replace it). - Max level –
Device.maxgain(raw gain per channel, app-side) andDevice.gain_cap: every gain the server sets (API, test fader, copy) is capped at max(limit, current value), so a DSP turned up on the device can only go down until it is below the limit again. The client mirrors this ingainCap(faders, sliders,setParam). - Link group names –
Device.linknames(app-side, like the colours), keyed by kind and members ("out:0,1"), so a changed group starts without a name. The mixer draws them as brackets in row 1 of the.stripsgrid (linkBands). - FIR tab (
viewFir, onlyd.fir) – outputs:0x4Btype/window/cut-offs/taps index, the DSP calculates the filter; the curve is the app's own windowed sinc. Files:Device.upload_fir(0x5Bname,0x4Epackets of 12 floats). The DSP can't send coefficients back, so the curve of a file only exists in the session (S.firCoef). - Dashboard (
static/dashboard.js, stored asdashboardinconfig.json, API/api/dashboard,clean_dashboard) – grid of 12 columns and rows of 40 px, modules inDASH_MODULESwithbody(m, d)andmin/max[columns, rows]. Must stay read-only: nosetParamor POST to a device there, browsing (channel, band) is session state (dashBrowse). A new module type also goes intoDASH_TYPESinserver.py. - Read-only switch (
S.guard,viewOnly()inapp.js) – web UI on phones and touch devices starts read-only, reusing the swallowing of the app lock. A safety catch per browser tab only: not stored, the server doesn't know it. Mute all stays. - Sound Lab / REW (
static/rew.js, handbooks instatic/docs.js,rew_callinserver.py) – the server talks to REW's API on127.0.0.1:4735, which only answers on REW's own computer; so Sound Lab is only in the desktop apps (S.isApp, the server refuses/api/rew/otherwise). Only checked against a fake server built from its OpenAPI spec. Pictures of the handbooks:static/docimg/<name>.<lang>.jpg, one per language, only ever from this app itself. - DJ Brake (
static/djbrake.html,App.dj_stream) – the only page without a login, off by default. It may only ever learn{on, ready, room, avg, hint}from/djbrake/state: never add device data or controls there.dj_marginmoves its limit down on purpose, so the page must never reveal it. On its own on purpose, withoutapp.js. Its settings sit in the access section; in the apps it needs remote access, since the app itself only listens on 127.0.0.1. - Preset looks –
Device.lookskeepscolors/linknamesper preset name;sync_lookswaps them whenever a read of the DSP shows another name (the DSP has no preset IDs: same name = same look). Preset files carry them aslook. - Network search –
App.scan_networkprobes the local /24 networks on TCP 9761 (handshake + device info), skipping DSPs this app is connected to. - Copy settings / mute all –
App.copy_settings(POST /api/copy, groups level/filters/eq/dynamics/routing) andApp.set_mute_all(POST /api/muteall; remembers per device which channels were open, persisted inconfig.jsonasmute_all, released devices that were offline are unmuted when they reconnect; allowed while the app is locked). dsp/preset.py– preset files (dsp-control-presetJSON with state + raw image), validation, and the minimal command sequence for an import. Undo backups go tobackups/next toconfig.json(last 20 per device).dsp/usbhid.py– HID via ctypes only: Windowshid.dll/SetupAPI, macOS IOKit, Linux/dev/hidraw*.HidStreamadapts a blocking reader thread to the asyncio stream interfacedevice.pyexpects.static/– single-page app in vanilla JS.h()builds DOM,Sis the global state,render()redraws the current view (mixer,channel,routing,link,limiter,settings). Live widgets register inliveand are updated without a full redraw. All UI text goes throught("English text", {vars}); German lives instatic/i18n.js(DE, plusDE_PATTERNSfor server messages with variables, applied bytrMsg()).sim.py– simulated DSP 204/408 speaking the same protocol (meters, limiter flags, links, lock code via--lock). Use it for all tests. The server also imports it for the demo mode (App.start_demo: real devices are stopped, aSimDSPruns on a random localhost port, aDevicewithdemo = Trueconnects to it; demo devices are never saved, exported or editable).sim.pytherefore ships with the Pi image and the EXEs.- Device lock (hardware, unrelated to the app lock) –
Device._wait_for_unlockholds the init after0x2Creports a lock, tries the remembered code (lock_code+auto_unlockinconfig.json, clients only see a boolean) or sets statuslockedand waits forPOST /api/devices/<id>/unlock {code, remember}.POST …/lockcode {code}sets a new code. desktop.py– startsserver.Appon 127.0.0.1 with a random port in a thread and opens a pywebview window.Apiexposes native file dialogs to the page (window.pywebview.api.save_file/open_file). Single instance via a named mutex (Windows) or lock file (macOS). Data in%APPDATA%\DSP Control/~/Library/Application Support/DSP Control.pi_writer.py/pi_image.py/win_disk.py– Windows-only tkinter tool that downloads Raspberry Pi OS Lite (official image list), writes it raw to an SD card (\\.\PhysicalDriveN, verify by SHA-256) and adds cloud-init files (user-data,network-config,meta-data) plus aninstall.shthat installs the app on first boot.
Conventions
- Server and
dsp/use the Python standard library only. pywebview/PyInstaller/Pillow are only for the desktop builds. No build step for the web UI. - Source texts are English. Every new
t("…")string needs a German entry instatic/i18n.js; server error messages that reach the UI need one too (exact text inDE, or a regex inDE_PATTERNS). Technical terms (Gain, Threshold, Mixer, Routing, Link, Limiter) stay English in German too. - Native/desktop apps never ask for the PIN; the web UI and remote access always do.
- Channel names: max 8 printable ASCII characters (umlauts are transliterated), and they must fit the mixer strip.
- Keep comments sparse and factual, match the surrounding style.
README.mdandPROTOCOL.mdare English. The Pi Writer UI is still German.
Testing
python tests/test_protocol.py
python sim.py --model 204 --port 9761
python sim.py --model 408 --port 9762
python server.py --port 8080 --config <some temp file>.json
Log in with PIN 1234, add devices 127.0.0.1:9761 / :9762. Check both languages after UI changes (⚙ →
Language / Sprache). For the desktop app run python desktop.py (needs pywebview).
Never change values on a real DSP permanently while testing. Export a preset file first (File… → Export) and restore it afterwards; prefer the simulator. The DSP accepts only one connection – close other control software.
Verified vs. unverified
Verified on a real DSP 204 (firmware V0104P, USB on macOS): connect/dump/meters, set commands, link command 0x3B
and the DSP's own mirroring inside groups, limiter-active bit mask, preset import writing only differences.
Not verified yet – ask for a log (python server.py -v) from real hardware before changing protocol code here:
- Beta models
206and408fir– never seen on real hardware. Never auto-detected (detect_model, a FIR device must not pass as a 408); the only hint is the note in the add-device form, afterwards they work like the others.206: same protocol and layout as the 204/408 are only assumed (no control software looked at), also the USB ID.408fir: own layout and commands derived from its control software (Model.fir,_parse_fir,_fir_command), simulator only. Not done: dynamic EQs (kept untouched), saving coefficients into a preset slot of the DSP (0x5A, format not worked out), where it keeps the test signal (the app remembers it). Ask testers for a preset export and a log. - DSP 408 on real hardware (layout and frames match published captures, limiter bits for Out 5–8 assumed)
- USB on Windows and Linux against a real DSP (only tested against a fake HID device)
- Where the PEQ bypass flag lives in the memory image; format of the set-command acknowledgement; where the number
of preset slots comes from (20 is assumed when the
0x2Canswer carries the lock state) - Master bypass commands
0x3C/0x49and their bit masks – from the control software, simulator only - Test signal command
0x39and its position in the memory image – derived from the control software, simulator only; whether the generator is pre or post input gain is unknown (the app therefore only lowers the outputs) - Device lock (
0x2Cbyte 5,0x2D,0x2F,0x11) – implemented from the control software's behaviour and tested against the simulator only; no command to remove a lock is known - DJ Brake distance to the limiter: output meter dB minus threshold dB, corrected by what real limiter hits show (
dj_cal); only the light, from the limiter-active bits, is certain - Limiter calculator reference level (assumes limiter 0 dB = 0 dBu at the output; adjustable per device)
- Pi Writer: raw write to a real SD card and first boot on a real Pi (only tested with an image file)
Legal notes for contributors
Do not add code, binaries, firmware, screenshots, manuals or internal symbol names/addresses from the manufacturer's software. Document protocol facts only as observed behaviour. Use "t.racks"/"Thomann" only to name the supported devices and keep the "not affiliated" notice in the README.