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. + +![Dashboard with levels, EQ curve and faders](docs/screenshots/dashboard.jpg) + > [!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. + +![Mixer with named link groups](docs/screenshots/mixer.jpg) + +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. + +![Parametric EQ with draggable bands](docs/screenshots/eq.jpg) + +* 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. + +![Routing matrix with levels](docs/screenshots/routing.jpg) + +### 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. + +![Link groups](docs/screenshots/groups.jpg) + +* **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. + +![Limiter tab](docs/screenshots/limiter.jpg) + +### 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. + +![SoundField room plan](docs/screenshots/soundfield.jpg) + +### 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. + +DJ Brake showing the limiter light + +### 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. + +The app on a phone + +### 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