# 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