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

# 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

3.6 KiB Raw Blame History