Files
BetterDSPControl/README.md
T
GivouandClaude Opus 5.5 fe13f261f7 Add BetterDSPControl: web UI, desktop app and Pi writer for t.racks DSP 204/408
- Python stdlib server with SSE live updates, PIN login, remote access
- Vanilla JS web UI (English/German): mixer, channel, routing, links, limiter calculator
- Preset file export/import with undo, settings backup, lock for the desktop app
- Network (TCP 9761) and USB HID transport (Windows, macOS, Linux)
- Desktop app via pywebview, Raspberry Pi SD card writer, simulator and protocol tests
- README with import guide for Claude Code, CLAUDE.md, protocol documentation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 20:24:33 +01:00

217 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# BetterDSPControl
**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).
* 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
* English and German user interface
## Features
* **Several devices at once** – switch with the tabs at the top; the model is detected automatically
* **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
* **Inputs** – noise gate, 31-band GEQ · **Outputs** – compressor, limiter, input routing with mix levels
* **Routing matrix**, recall and store presets
* **Channel links** – link channels into groups; the DSP mirrors changes within the group, the app shows them live
* **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)
* **Settings backup** – devices, amplifier data, PIN and remote access in one file
* **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
## 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 |
The DSPs accept only **one** connection at a time – close any other control software first.
## Quick start (web UI)
```bash
git clone https://git.thiemoo.at/Givou/BetterDSPControl.git
```
```bash
cd BetterDSPControl
```
```bash
python server.py
```
Open `http://<IP-of-this-computer>:8080` in a browser (from a phone: same Wi-Fi/LAN).
1. Log in with the default PIN **`1234`**.
2. Open ⚙ (settings), enter the IP addresses of your DSPs (or choose *USB cable*) and press *Connect*.
3. **Change the PIN** under ⚙ → Security.
4. Switch the language under ⚙ → *Language / Sprache* (English is the default).
`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`
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.
## Desktop apps (Windows, macOS)
The desktop app runs the server and the UI in its own window – **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.
Build it yourself (pre-built binaries are not part of the repository):
```bash
python -m pip install pyinstaller pywebview pillow
```
```bash
python packaging/build.py
```
* **Windows** → `dist/DSP Control.exe` and `dist/DSP Control Pi Writer.exe`. Data: `%APPDATA%\DSP Control`.
* **macOS** → `dist/DSP Control.app` and `dist/DSP Control.dmg` (use a venv with Python 3.10+, e.g. from Homebrew).
The app is not signed: on the first start right-click → *Open*. Data: `~/Library/Application Support/DSP Control`.
## Raspberry Pi (always-on web UI)
`DSP Control Pi Writer.exe` (Windows, user interface currently German only) prepares an SD card for a Raspberry Pi
(Pi 1/2/3/4/5, Zero, Zero 2 W) that serves the web UI permanently:
* downloads the current Raspberry Pi OS Lite from the official Raspberry Pi servers (with checksum, cached)
* writes and verifies the card, then configures it via cloud-init: hostname, Wi-Fi, user/SSH, web UI PIN, DSP IPs
* installs BetterDSPControl from the card (the Pi needs no internet), as a systemd service on port 80
After 2–5 minutes open `http://<hostname>.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**.
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.
## Testing without hardware
A simulator emulates both models:
```bash
python sim.py --model 204 --port 9761
```
```bash
python sim.py --model 408 --port 9762
```
```bash
python server.py
```
Then add devices with IP `127.0.0.1` and ports 9761 / 9762 in the web UI. Protocol self-test:
```bash
python tests/test_protocol.py
```
## Project layout
| Path | Contents |
|------|----------|
| `server.py` | Web server (HTTP + server-sent events), device management, auth, backups |
| `dsp/protocol.py` | Frame format, commands, value scales, memory-image parser |
| `dsp/device.py` | Client per DSP (TCP or USB): connect, command queue, meters, auto-reconnect, links |
| `dsp/preset.py` | Preset files: export/import, validation, import command sequence |
| `dsp/usbhid.py` | USB HID without extra packages (Windows hid.dll, macOS IOKit, Linux hidraw) |
| `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`), translations in `static/i18n.js` |
| `packaging/` | Build script and icons |
| `tests/` | Protocol tests |
| `PROTOCOL.md` | Protocol documentation |
| `CLAUDE.md` | Guide for AI coding assistants (architecture, conventions, open points) |
## How to import into your Claude
This project was built with [Claude Code](https://claude.com/claude-code) and is documented so you can continue
working on it in your own Claude session. `CLAUDE.md` is read automatically by Claude Code and explains the
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
terminal:
```bash
cd BetterDSPControl && claude
```
3. Paste this prompt as your first message:
```text
This is BetterDSPControl, a control app for the t.racks DSP 204 / DSP 408 (Python stdlib server + vanilla JS web UI,
desktop app via pywebview, Raspberry Pi SD card writer).
Please get familiar with the project first:
1. Read CLAUDE.md, README.md and PROTOCOL.md completely.
2. Look at server.py, dsp/protocol.py, dsp/device.py and static/app.js to understand the structure.
3. Run the tests (python tests/test_protocol.py) and start the simulator test from the README
(sim.py for both models + server.py) to see the app working.
4. Summarise briefly how it is built and which points are still unverified on real hardware.
Rules: never change values on a real DSP permanently while testing (export a preset file first, use the simulator
whenever possible), keep the server free of third-party packages, and keep English and German texts in sync
(static/i18n.js). Ask me before pushing anything.
My devices: <e.g. DSP 408 over network, IP 192.168.1.50 / DSP 204 over USB>.
What I want to do: <describe your goal>.
```
## 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`.
## 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
warranty of any kind, see [LICENSE](LICENSE).
The protocol was documented for interoperability purposes only, by observing the communication of the devices and
testing on real hardware. This repository contains no code, binaries, firmware, images or documentation from the
manufacturer. Frame examples in the tests also match the DSP 408 captures published by
[dsp-408-ui](https://github.com/Aeternitaas/dsp-408-ui); no code from that project is used.
## License
[MIT](LICENSE) © 2026 Givou
The desktop builds bundle third-party components under their own licenses (Python – PSF License, pywebview – BSD,
pythonnet – MIT, PyInstaller bootloader – GPL with exception allowing distribution). If you distribute built
binaries, include their license notices.