Optional page /djbrake (off by default) with a red light while a limiter works.
It needs no PIN and only ever gets {on, ready} from /djbrake/state.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
147 lines
13 KiB
Markdown
147 lines
13 KiB
Markdown
# 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}` 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
|
||
|
||
```bash
|
||
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
|
||
* 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.
|