107 lines
3.6 KiB
Markdown
107 lines
3.6 KiB
Markdown
# Raspberry Pi Mixer — Agent Guide
|
|
|
|
Professional 16-channel real-time audio mixer on Raspberry Pi 4B. Sub-10ms latency with USB audio, MIDI controllers, touchscreen UI, multi-track recording, live streaming, and web control surface.
|
|
|
|
## Stack
|
|
|
|
- **Python** 3.11+, **JACK2** (PREEMPT_RT kernel)
|
|
- **Carla** — LV2/VST/NAM plugin host
|
|
- **FastAPI** + **uvicorn** — REST API + WebSocket
|
|
- **Kivy** — touchscreen UI
|
|
- **GStreamer** — live streaming
|
|
- **numpy**, **python-jack-client**
|
|
- **pytest** — 735 tests
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
mixer/ # DSP engine, channel strips, bus manager, routing matrix
|
|
midi/ # MIDI engine, learn mode, clock sync, device discovery
|
|
session/ # Session manager, setlists, snapshots
|
|
recording/ # Multi-track WAV recorder, bounce, disk monitor
|
|
backing/ # Backing track player, metronome, transport
|
|
streaming/ # GStreamer pipeline, platform presets, camera
|
|
network/ # FastAPI REST API + WebSocket + OSC server
|
|
plugin/ # Plugin manager, LV2/VST/NAM support, scanner
|
|
ui/ # Kivy touchscreen UI
|
|
|
|
main_touch.py # Touchscreen UI entry point
|
|
|
|
config/
|
|
99-audio.conf # ALSA USB audio config
|
|
99-midi.rules # udev rules for MIDI
|
|
jackdrc # JACK2 configuration
|
|
carla-8ch-default.carxp # Carla patchbay preset
|
|
usb-audio-quirks.conf # USB audio quirks
|
|
|
|
build/
|
|
build.sh # SD card image builder
|
|
configure-system.sh # System configuration
|
|
first-boot/ # First-boot setup wizard
|
|
|
|
docs/
|
|
build-guide.md # Hardware assembly + OS setup
|
|
user-manual.md # End-user documentation
|
|
developer-guide.md # Architecture + extending
|
|
troubleshooting.md # Common issues
|
|
hardware-compatibility.md
|
|
midi-controller-support.md
|
|
audio-stack-config.md
|
|
carla-integration.md
|
|
touchscreen-ui-evaluation.md
|
|
decisions/ # Architecture Decision Records
|
|
research/ # Research reports
|
|
|
|
tests/ # pytest suite (735 tests)
|
|
```
|
|
|
|
## How to Run
|
|
|
|
```bash
|
|
# On the Pi itself:
|
|
|
|
# Audio API server
|
|
python -m src.network.run
|
|
|
|
# Touchscreen UI
|
|
python main_touch.py
|
|
|
|
# Or via systemd (production):
|
|
sudo systemctl start mixer-api
|
|
sudo systemctl start mixer-ui
|
|
```
|
|
|
|
## Systemd Services
|
|
|
|
| Service | Purpose | Port | User |
|
|
|---------|---------|------|------|
|
|
| `cpu-performance.service` | CPU governor → performance | — | root |
|
|
| `jackd.service` | JACK2 audio server (SCHED_FIFO prio 70) | — | root |
|
|
| `mixer-api.service` | FastAPI REST/WebSocket API | 8080 | pi:audio |
|
|
| `mixer-ui.service` | Kivy touchscreen UI | — | pi:audio |
|
|
| `mixer-firstboot.service` | First-boot setup | — | root |
|
|
|
|
## Production
|
|
|
|
- **URL:** `http://pi-mixer.local:8080`
|
|
- **Audio:** JACK2 at 48kHz/128 frames, ALSA hw:USB interface
|
|
- **OS:** PREEMPT_RT kernel 6.12.y on Raspberry Pi 4B
|
|
- **Plugins:** Carla hosts LV2, VST3, and NAM (Neural Amp Modeler)
|
|
- **License:** MIT
|
|
|
|
## Environment & Config
|
|
|
|
Key config files under `/opt/rpi-mixer/config/`:
|
|
- `jackdrc` — JACK2 server parameters (sample rate, buffer size, ALSA device)
|
|
- `99-midi.rules` — USB MIDI device permissions
|
|
- `99-audio.conf` — ALSA audio limits for `pi` user
|
|
|
|
## Pitfalls
|
|
|
|
- **Real-time audio** — all DSP code must avoid blocking calls, file I/O in audio thread
|
|
- **PREEMPT_RT kernel** required for sub-10ms latency — building from source via `build/build.sh`
|
|
- JACK2 config varies by USB audio interface — `config/jackdrc` may need per-device tuning
|
|
- Plugin blacklist in `src/plugin/` prevents known-crash plugins at scan time
|
|
- SD card image builder in `build/` — modifications to base image need careful tracking
|