270 lines
15 KiB
Markdown
270 lines
15 KiB
Markdown
# BetterDSPControl
|
||
|
||
> [!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
|
||
> 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
|
||
> 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.
|
||
> 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).
|
||
|
||
* 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** – 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
|
||
* **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
|
||
* **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
|
||
|
||
## 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 |
|
||
|
||
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
|
||
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.
|
||
|
||
## 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
|
||
|
||
The quickest way is the **demo mode** (⚙ → Demo mode). For development, a stand-alone simulator emulates both
|
||
models (`--lock A1BA` makes it ask for a lock code):
|
||
|
||
```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`), dashboard in `static/dashboard.js`, SoundField in `static/soundfield.js`, 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.
|