Files
BetterDSPControl/CLAUDE.md
T
GivouandClaude Opus 5.5 8919f0016c DJ Brake: choose which limiters count, horizontal distance to the limiter
Outputs can be left out per device, muted outputs never count. The page also
shows how far the closest watched output is from its limiter threshold.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 18:42:56 +01:00

13 KiB
Raw Blame History

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 on asyncio.start_server (no framework). JSON API under /api/…, live updates as server-sent events on /api/events (App.broadcast). App holds 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 cookie dspsess (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; with lock_dash the window shows only the dashboard). Remote clients always need the PIN.
  • dsp/device.py – one Device per DSP: connect (TCP or usbhid.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 (SPEC in app.js). Channels also carry peq_bypass (master bypass, 0x3C) and inputs geq_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.curve in 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_test in server.py: entering saves the output gains (Device.test_saved, persisted in config.json so 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. While Device.test_active the server only accepts the test controls (generator, test fader, output mutes) and the UI stays locked in the audio test tab. The state field is state["test"] = {source, freq}.
  • SoundField (static/soundfield.js, plan stored by the server as soundfield in config.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) and Device.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 in gainCap (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 .strips grid (linkBands).
  • FIR tab (viewFir, only d.fir) – outputs: 0x4B type/window/cut-offs/taps index, the DSP calculates the filter; the curve is the app's own windowed sinc. Files: Device.upload_fir (0x5B name, 0x4E packets 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 as dashboard in config.json, API /api/dashboard, clean_dashboard) – grid of 12 columns and rows of 40 px, modules in DASH_MODULES with body(m, d) and min/max [columns, rows]. Must stay read-only: no setParam or POST to a device there, browsing (channel, band) is session state (dashBrowse). A new module type also goes into DASH_TYPES in server.py.
  • Read-only switch (S.guard, viewOnly() in app.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 in static/docs.js, rew_call in server.py) – the server talks to REW's API on 127.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.
  • 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} from /djbrake/state: never add device data or controls there. On its own on purpose, without app.js.
  • Network search – App.scan_network probes 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) and App.set_mute_all (POST /api/muteall; remembers per device which channels were open, persisted in config.json as mute_all, released devices that were offline are unmuted when they reconnect; allowed while the app is locked).
  • dsp/preset.py – preset files (dsp-control-preset JSON with state + raw image), validation, and the minimal command sequence for an import. Undo backups go to backups/ next to config.json (last 20 per device).
  • dsp/usbhid.py – HID via ctypes only: Windows hid.dll/SetupAPI, macOS IOKit, Linux /dev/hidraw*. HidStream adapts a blocking reader thread to the asyncio stream interface device.py expects.
  • static/ – single-page app in vanilla JS. h() builds DOM, S is the global state, render() redraws the current view (mixer, channel, routing, link, limiter, settings). Live widgets register in live and are updated without a full redraw. All UI text goes through t("English text", {vars}); German lives in static/i18n.js (DE, plus DE_PATTERNS for server messages with variables, applied by trMsg()).
  • 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, a SimDSP runs on a random localhost port, a Device with demo = True connects to it; demo devices are never saved, exported or editable). sim.py therefore ships with the Pi image and the EXEs.
  • Device lock (hardware, unrelated to the app lock) – Device._wait_for_unlock holds the init after 0x2C reports a lock, tries the remembered code (lock_code + auto_unlock in config.json, clients only see a boolean) or sets status locked and waits for POST /api/devices/<id>/unlock {code, remember}. POST …/lockcode {code} sets a new code.
  • desktop.py – starts server.App on 127.0.0.1 with a random port in a thread and opens a pywebview window. Api exposes 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 an install.sh that 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 in static/i18n.js; server error messages that reach the UI need one too (exact text in DE, or a regex in DE_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.md and PROTOCOL.md are 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 206 and 408fir – 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 0x2C answer carries the lock state)
  • Master bypass commands 0x3C / 0x49 and their bit masks – from the control software, simulator only
  • Test signal command 0x39 and 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 (0x2C byte 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, assumes both share one reference (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)

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.