diff --git a/.claude/launch.json b/.claude/launch.json
deleted file mode 100644
index 2af2843..0000000
--- a/.claude/launch.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
- "version": "0.0.1",
- "configurations": [
- {"name": "sim-204", "runtimeExecutable": "python", "runtimeArgs": ["sim.py", "--model", "204", "--port", "9761"], "port": 9761},
- {"name": "sim-408", "runtimeExecutable": "python", "runtimeArgs": ["sim.py", "--model", "408", "--port", "9762"], "port": 9762},
- {"name": "webui", "runtimeExecutable": "python", "runtimeArgs": ["server.py", "--port", "8080"], "port": 8080}
- ]
-}
diff --git a/.gitignore b/.gitignore
index ea596dc..1806317 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,4 +12,4 @@ __pycache__/
.DS_Store
# personal Claude Code settings
-.claude/settings.local.json
+.claude/
diff --git a/README.md b/README.md
index 1d55ba4..df4aee1 100644
--- a/README.md
+++ b/README.md
@@ -1,94 +1,140 @@
# BetterDSPControl
+**A modern, phone-friendly control app for the t.racks DSP 204 and DSP 408 loudspeaker processors.**
+Control all your DSPs at the same time from a phone, tablet or computer, over the network or USB.
+
+
+
> [!WARNING]
-> **Vibe-coded – read this first.** I'm a hobbyist and wrote this app almost entirely with an AI coding assistant,
-> for my own two DSPs. It works for me, but large parts have only been tested against a simulator, and some protocol
+> **Vibe-coded, read this first.** I'm a hobbyist and wrote this app almost entirely with an AI coding assistant,
+> for my own DSPs. It works for me, but large parts have only been tested against a simulator, and some protocol
> details are educated guesses (see [Verified vs. unverified](CLAUDE.md#verified-vs-unverified)).
-> It talks directly to your loudspeaker processor and can change gains, limiters and crossovers – a wrong value can
+> It talks directly to your loudspeaker processor and can change gains, limiters and crossovers: a wrong value can
> be loud and can damage speakers. **Export a preset before you start, keep the volume down while trying things out,
> and don't use it on a show you can't afford to lose.**
> You use it entirely at your own risk. I'm not responsible for anything that happens to your DSP, your speakers,
-> your ears, your gig or your neighbours – nor for anything else, should the sky fall on you while you use it.
+> your ears, your gig or your neighbours, nor for anything else, should the sky fall on you while you use it.
> No warranty of any kind (see [LICENSE](LICENSE)).
-**A modern, phone-friendly control app for the t.racks DSP 204 and DSP 408 loudspeaker processors.**
-Control both devices at the same time from your phone, tablet or computer – over the network or USB.
-
> **Unofficial project.** BetterDSPControl is an independent open-source project. It is not affiliated with,
> endorsed by or supported by Musikhaus Thomann or the t.racks brand. "Thomann" and "t.racks" are trademarks of
> their respective owner and are used here only to name the devices this software works with.
-> Use at your own risk – see [Disclaimer](#disclaimer).
+> See [Disclaimer](#disclaimer).
-* Pure Python 3.10+ standard library on the server side – no packages to install
-* Vanilla HTML/CSS/JavaScript web UI – no build tools
-* Runs on Windows, macOS, Linux and a Raspberry Pi
+* Runs on Windows, macOS, Linux and a Raspberry Pi, and in any browser
+* No packages to install for the server (Python 3.10+ standard library), no build tools for the web UI
* English and German user interface
+* **Want to look around first?** ⚙ → *Demo mode* starts a simulated DSP inside the app. Nothing is sent to real devices
-## Features
+All screenshots show the built-in simulator with made-up settings.
-* **Several devices at once** – pick the DSP from the drop-down at the top (small dots show the status of the others);
- the model is detected automatically
-* **Dashboard** – your own overview page: drag modules onto it (DSP overview, levels, faders, frequency response with
- clickable EQ bands and overlays, channel, limiter, routing, delay, FIR, notes), move them by the title, resize them by
- the arrows, choose their DSP. It only looks and never changes a DSP; the layout is stored in the config
-* **Read-only switch** – on phones and tablets the web UI starts read-only; a small switch at the top allows changes
-* **Sound Lab** (Windows and macOS apps) – together with REW (Room EQ Wizard): take the filters of a measurement or a REW filter file onto a channel,
- compare before applying, send a channel's curve or filters back to REW. Handbook with real cases here and in SoundField
-* **DJ Brake** – optional page `/djbrake` for a tablet at the DJ booth: a big red light when a limiter acts, on for one more second
- afterwards. You can leave out limiters (a monitor, say). Needs no PIN and shows nothing else
-* **Preset looks** – colours and link group names belong to the preset (by its name) and also travel in preset files
-* **Mixer** – faders, mute and live meters for all inputs and outputs, limiter LED on every output (status read
- from the DSP)
-* **Channel** – name, gain, delay, polarity, high/low pass, 8/9-band PEQ with a draggable curve; the curve shows
- magnitude or phase (crossover filters, all-pass filters) and can overlay any other channel, e.g. to line up a
- sub/top crossover; **EQ Bypass** switches all PEQ bands off at once
-* **Inputs** – noise gate, 31-band GEQ with **GEQ Bypass** · **Outputs** – compressor, limiter, input routing with mix levels
-* **Routing matrix**, recall and store presets
-* **Channel settings** tab – link channels into groups (the DSP mirrors changes within the group) edit existing groups (add or
- remove channels), give each group a name – the mixer shows it as a bracket in the group's colour above its strips –, set a **max level**
- per channel (software lock: the fader can't go higher; if the DSP itself is turned up, it can only be pulled down until
- it snaps into the limit again) and pick channel colours
-* **Preset files** – export the current DSP state to a file and import it again. An import only changes the active
- state (stored presets stay untouched), writes only what actually differs and makes an automatic backup first
- ("Undo import")
-* **Limiter calculator** – enter your amplifiers' datasheet values (power at 8/4/2 Ω, sensitivity or gain), assign
- outputs, and see the resulting power when the limiter engages, the clipping headroom and the speaker load.
- "Limit to … W" calculates the threshold. Attack/release presets per band (infra, sub, kick, mid, high)
-* **SoundField** – top view of the room: place mains, subs, delays and fills by dragging (tops can stand on a sub with a
- distance pole – drop the top onto the sub), see a level map, a sub
- map at a chosen frequency (phase-correct, shows cancellation lanes) and a timing map for delay speakers. It
- suggests aiming, height, delay lines, sub placement and front fills (one click to apply), calculates the delays
- from the speed of sound and writes them to the assigned DSP outputs
-* **Copy channel settings** – level/delay/polarity, filters, EQ, dynamics and routing from one channel to any number
- of channels on all connected DSPs
-* **Channel colours** – line and lightly tinted name in the mixer, channel view, routing and curve overlays; linked
- channels share one colour, every colour is used once per DSP
-* **Network search** – finds DSPs in the local network and adds them with one click; the device ID (address byte,
- default 1) is under the device's advanced settings
-* **Custom logo** – your own logo top left and as the browser icon (settings → Logo; PNG/JPG/WebP/SVG, ideally square, ≥ 64×64 px)
-* **Fits every screen** – menu in the top bar on wide screens, a sidebar when the window gets narrow, a bottom bar on phones
-* **Mute all** – one button mutes every channel of every connected DSP; releasing it unmutes only what was open before
-* **Reset app settings** – desktop apps only: back to a fresh app (⚙ → Backup); DSPs are disconnected first and nothing on them changes
-* **Settings backup** – devices, amplifier data, SoundField plan, PIN and remote access in one file
-* **Device lock** – DSPs locked with their 4-character code (e.g. `A1BA`) are detected on connect and the app asks
- for the code; optionally it remembers the code and unlocks automatically. A new code can be set under ⚙
-* **Audio test** – switch the DSP's test generator (pink noise, white noise, sine 20 Hz–20 kHz) on and off. All
- outputs drop to −50 dB first and a single test fader raises them together; mute buttons for every output.
- Presets can't be saved or recalled meanwhile, and stopping the test switches the noise off before every fader
- returns to its previous value. A DSP found playing a test signal on connect goes straight into this mode
-* **Demo mode** – one switch under ⚙ starts a simulated DSP 204 or 408 inside the app to try everything; the real
- DSPs are disconnected meanwhile and nothing is sent to them
-* **Many phones at once** – every change is pushed live to all connected clients
-* Tap a value to type it in (`-3.5`, `1.2k`, delay in metres `2.5m`); faders snap at 0 dB, double-tap = 0 dB
+## What it can do
+
+### Mixer
+
+Faders, mute and live meters for every input and output, on all screens. **LIM** lights up when an output's limiter
+acts, as reported by the DSP. Linked channels are grouped under a named bracket in their colour.
+
+
+
+Tap a value to type it (`-3.5`, `1.2k`, a delay in metres like `2.5m`). Faders snap at 0 dB and a double tap returns
+to 0 dB. **Mute all** silences every channel of every connected DSP, and releasing it unmutes only what was open before.
+
+### Channel and EQ
+
+Drag the bands directly on the curve. The 8- or 9-band parametric EQ shows magnitude or phase, including crossover
+filters, and can overlay any other channel, for example to line up a sub with a top.
+
+
+
+* Name, gain, delay, polarity, high and low pass, *EQ Bypass*
+* Inputs: noise gate, 31-band graphic EQ
+* Outputs: compressor, limiter, input routing with mix levels
+* **Copy settings** from one channel to any number of channels, on all connected DSPs
+
+### Routing
+
+Connect inputs and outputs in a matrix. Each connection shows its level inside the crosspoint and follows the
+slider as you move it.
+
+
+
+### Link groups, colours and presets
+
+Link channels into groups, so the DSP mirrors changes within a group. Give each group a name and a colour.
+
+
+
+* **Colours and group names belong to the preset.** The DSP has no preset IDs, so they are kept by preset name: same
+ name, same look. A preset without its own look starts empty
+* **Max level** per channel: a software lock, the fader can't go higher
+* **Preset files:** export the current DSP state and import it again, colours and group names included. An import
+ only changes the active state, writes only what actually differs and makes a backup first (*Undo import*)
+
+### Limiter calculator
+
+Enter your amplifiers' datasheet values (power at 8/4/2 Ω, sensitivity or gain), assign outputs and see the resulting
+power when the limiter engages, the clipping headroom and the speaker load. *Limit to … W* calculates the threshold.
+Attack and release presets per band (infra, sub, kick, mid, high). It is a planning aid based on an assumed reference
+level, so verify it with a measurement.
+
+
+
+### SoundField
+
+A top view of the room for planning. Place mains, subs, delays and fills by dragging, and see a level map, a sub map at
+a chosen frequency with its cancellation lanes, and a timing map for delay speakers. It suggests aiming, height, delay
+lines and sub placement, calculates the delays and writes them to the assigned DSP outputs. It is a free-field model
+without reflections, so a planning aid and not a measurement. A handbook with real cases is built in.
+
+
+
+### Dashboard
+
+Your own overview page: DSP overview, levels, faders, frequency response, channel, limiter, routing, delay, notes. Drag
+modules on with a mouse, then move and resize them. It only looks and never changes a DSP. On touchscreens only the
+settings of each module can be changed. The dashboard starts empty.
+
+### DJ Brake
+
+An optional page at `/djbrake` for a tablet at the DJ booth: a big red light when a limiter acts, on for one more second
+afterwards. Limiters that don't matter, a monitor for example, can be left out. It needs no PIN, shows nothing else
+and changes nothing. Turn it on under ⚙ → *Remote access* in the desktop apps, or ⚙ → *Security* on the web. In the
+desktop apps it needs remote access to be on. The limiter signal comes from the DSP, and on a real DSP 204 it was seen
+staying on for up to 4 seconds in some cases, so the light can stay on longer than that one second.
+
+
+
+### On your phone
+
+The whole app adapts to phones and tablets. The web UI starts **read-only** on touch devices, and a small switch at the
+top allows changes, so nothing moves by accident. Zooming is turned off so it can't get in the way of the faders. Every
+change is pushed live to all connected devices.
+
+
+
+### And also
+
+* **Several DSPs at once:** pick one at the top, the model is detected automatically
+* **Network search** finds DSPs in the local network and adds them with one click
+* **Sound Lab** (desktop apps only): works with [REW](https://www.roomeqwizard.com/). Take the filters of a measurement or
+ a REW filter file onto a channel, compare before applying, send a channel's curve back. So far only tested against a
+ stand-in built from REW's API description, not against REW itself
+* **Audio test:** the DSP's generator (pink noise, white noise, sine). All outputs drop to −50 dB first and one test
+ fader raises them together
+* **Device lock:** DSPs locked with their 4-character code are detected and the app asks for the code
+* **Settings backup** in one file, and in the desktop apps **Reset app settings**. The DSPs are disconnected first and
+ nothing on them changes
+* **Your own logo** at the top left and as the browser icon
## Supported hardware
| Device | Network | USB | Tested on real hardware |
|--------|---------|-----|-------------------------|
| t.racks DSP 204 | ✓ | ✓ | yes (firmware V0104P, USB on macOS) |
-| t.racks DSP 408 | ✓ | ✓ | not yet – frames match published captures |
-| t.racks DSP 206 (beta) | ✓ | ? | no – assumed to work like the others, testers wanted |
-| t.racks FIR DSP 408 (beta) | ✓ | ? | no – memory layout and FIR commands derived from the control software, simulator only |
+| t.racks DSP 408 | ✓ | ✓ | not yet, frames match published captures |
+| t.racks DSP 206 (beta) | ✓ | ? | no, assumed to work like the others, testers wanted |
+| t.racks FIR DSP 408 (beta) | ✓ | ? | no, simulator only |
The FIR DSP 408 gets its own **FIR** tab: low-, high- and band-pass with window and taps on the outputs, coefficients
from a txt/csv file on inputs (up to 2048) and outputs (up to 1024), a curve and the shared budget of 4096 taps. Its
@@ -97,7 +143,7 @@ dynamic EQs are not supported.
Beta models are not detected automatically: choose them by hand when adding the device (amplifiers off for the first
test). If the shown values don't match the DSP, please send the file from File… → Export.
-The DSPs accept only **one** connection at a time – close any other control software first.
+The DSPs accept only **one** connection at a time, so close any other control software first.
## Quick start (web UI)
@@ -123,18 +169,18 @@ Open `http://:8080` in a browser (from a phone: same Wi-Fi/
`config.json` is created on the first start. Options: `--port 8080`, `--host 0.0.0.0`, `--config path/to/config.json`,
`-v` (debug log). On Windows you can also double-click `start.bat`.
-**Forgot the PIN?** Stop the server, delete the `auth` entry from `config.json` and start again – the PIN is `1234`
+**Forgot the PIN?** Stop the server, delete the `auth` entry from `config.json` and start again. The PIN is `1234`
again.
### Security
The PIN protects against accidental access in your own network, nothing more: it has 4 digits, a logged-in device
stays logged in for 30 days, and after 5 wrong attempts the login is blocked (30 s, growing up to 15 min). The server speaks
-plain HTTP. **Do not expose it to the internet** (no port forwarding) – use a VPN if you need remote access.
+plain HTTP. **Do not expose it to the internet** (no port forwarding); use a VPN if you need remote access.
## Desktop apps (Windows, macOS)
-The desktop app runs the server and the UI in its own window – **no PIN needed** in the app window.
+The desktop app runs the server and the UI in its own window, with **no PIN needed** in the app window.
Under ⚙ → *Remote access* you can turn on a web server for phones and tablets (port selectable); other devices
then log in with the PIN. The lock icon (top right) locks the app window (view only); unlock with the PIN.
@@ -162,16 +208,17 @@ python packaging/build.py
* installs BetterDSPControl from the card (the Pi needs no internet), as a systemd service on port 80
After 2–5 minutes open `http://.local`. Needs administrator rights; only USB/SD drives that are not the
-system or boot disk are offered. If Windows then asks to format the Linux partition, click **Cancel**.
+system or boot disk are offered. If Windows then asks to format the Linux partition, click **Cancel**. Writing to a real
+SD card and the first boot on a real Pi have not been tested yet.
On any other Linux machine: `python3 server.py --port 8080`. For USB access as a normal user add a udev rule for
`hidraw` devices with VID `0168` / PID `0821` (see `INSTALL_SH` in `pi_image.py`).
## USB
-Choose *USB cable* for a device under ⚙. The DSPs are USB HID devices (VID 0168 / PID 0821) – no driver needed – and
-speak the same frames as over the network. Works on Windows (hid.dll), macOS (IOKit) and Linux (hidraw). With two
-DSPs on USB, pick the right one in the drop-down.
+Choose *USB cable* for a device under ⚙. The DSPs are USB HID devices (VID 0168 / PID 0821), so no driver is needed, and
+they speak the same frames as over the network. Written for Windows (hid.dll), macOS (IOKit) and Linux (hidraw); tested
+on a real DSP on macOS. With two DSPs on USB, pick the right one in the drop-down.
## Testing without hardware
@@ -190,7 +237,7 @@ python sim.py --model 408 --port 9762
python server.py
```
-Then add devices with IP `127.0.0.1` and ports 9761 / 9762 in the web UI. Protocol self-test:
+Then add devices with IP `127.0.0.1` and ports 9761 / 9762 in the web UI. Self-test:
```bash
python tests/test_protocol.py
@@ -208,9 +255,11 @@ python tests/test_protocol.py
| `sim.py` | Simulated DSP 204/408 |
| `desktop.py` | Desktop app (Windows/macOS): server + own window (pywebview) |
| `pi_writer.py`, `pi_image.py`, `win_disk.py` | Raspberry Pi SD card writer: GUI, OS image + cloud-init, raw disk writes |
-| `static/` | Web UI (`app.js`, `style.css`, `index.html`), dashboard in `static/dashboard.js`, SoundField in `static/soundfield.js`, translations in `static/i18n.js` |
+| `static/` | Web UI: `app.js`, `dashboard.js`, `soundfield.js`, `rew.js`, handbooks in `docs.js`, translations in `i18n.js` |
| `packaging/` | Build script and icons |
-| `tests/` | Protocol tests |
+| `tests/` | Self-tests |
+| `tools/dsp_measure.py` | Measures on a real DSP how meter, gain, threshold and limiter relate |
+| `docs/screenshots/` | The pictures in this file |
| `PROTOCOL.md` | Protocol documentation |
| `CLAUDE.md` | Guide for AI coding assistants (architecture, conventions, open points) |
@@ -221,7 +270,7 @@ working on it in your own Claude session. `CLAUDE.md` is read automatically by C
architecture, conventions and what is still unverified.
1. Clone the repository (see [Quick start](#quick-start-web-ui)).
-2. Open the folder in Claude Code – either the **Claude desktop app** (tab *Code* → choose the folder) or in a
+2. Open the folder in Claude Code: either the **Claude desktop app** (tab *Code* → choose the folder) or in a
terminal:
```bash
@@ -251,14 +300,15 @@ What I want to do: .
## Contributing
-Issues and pull requests are welcome – especially captures and test results from a real **DSP 408** and anything
-listed as unverified in `CLAUDE.md`. Please test with the simulator first and run `python tests/test_protocol.py`.
+Issues and pull requests are welcome, especially test results from a real **DSP 408** and anything listed as unverified
+in `CLAUDE.md`. Please test with the simulator first and run `python tests/test_protocol.py`. Owners of another model
+can help a lot with `tools/dsp_measure.py`: it only lowers values, puts them back and writes a small result file.
## Disclaimer
This software talks to your audio hardware. Wrong settings (e.g. limiter thresholds, gain, crossover filters) can
damage loudspeakers or amplifiers. The limiter calculator is a planning aid based on datasheet values and an assumed
-reference level – verify with a measurement before relying on it. The software is provided "as is", without
+reference level, so verify with a measurement before relying on it. The software is provided "as is", without
warranty of any kind, see [LICENSE](LICENSE).
The protocol was documented for interoperability purposes only, by observing the communication of the devices and
diff --git a/docs/screenshots/dashboard.jpg b/docs/screenshots/dashboard.jpg
new file mode 100644
index 0000000..846d522
Binary files /dev/null and b/docs/screenshots/dashboard.jpg differ
diff --git a/docs/screenshots/djbrake.jpg b/docs/screenshots/djbrake.jpg
new file mode 100644
index 0000000..281c4e8
Binary files /dev/null and b/docs/screenshots/djbrake.jpg differ
diff --git a/docs/screenshots/eq.jpg b/docs/screenshots/eq.jpg
new file mode 100644
index 0000000..2b4f9d7
Binary files /dev/null and b/docs/screenshots/eq.jpg differ
diff --git a/docs/screenshots/groups.jpg b/docs/screenshots/groups.jpg
new file mode 100644
index 0000000..c608564
Binary files /dev/null and b/docs/screenshots/groups.jpg differ
diff --git a/docs/screenshots/limiter.jpg b/docs/screenshots/limiter.jpg
new file mode 100644
index 0000000..8699e6d
Binary files /dev/null and b/docs/screenshots/limiter.jpg differ
diff --git a/docs/screenshots/mixer.jpg b/docs/screenshots/mixer.jpg
new file mode 100644
index 0000000..64a7b50
Binary files /dev/null and b/docs/screenshots/mixer.jpg differ
diff --git a/docs/screenshots/phone.jpg b/docs/screenshots/phone.jpg
new file mode 100644
index 0000000..14abb7c
Binary files /dev/null and b/docs/screenshots/phone.jpg differ
diff --git a/docs/screenshots/routing.jpg b/docs/screenshots/routing.jpg
new file mode 100644
index 0000000..ef0253a
Binary files /dev/null and b/docs/screenshots/routing.jpg differ
diff --git a/docs/screenshots/soundfield.jpg b/docs/screenshots/soundfield.jpg
new file mode 100644
index 0000000..dea90bd
Binary files /dev/null and b/docs/screenshots/soundfield.jpg differ