11 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). 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). - 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, same protocol and memory layout are only assumed (also the USB ID). 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. The FIR filters are deliberately not implemented; ask testers for a preset export (it holds the raw image) and a log first. - 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 - 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.