# Raspberry Pi Real-Time Audio Mixer

[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/platform-Raspberry%20Pi%204B-red.svg)](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-735%20passing-brightgreen.svg)](tests/)
[![Build](https://img.shields.io/badge/build-PREEMPT__RT-orange.svg)](build/)

A professional multi-channel real-time audio mixer running on a Raspberry Pi 4B.
Sub-10ms round-trip latency with 16-channel USB audio, MIDI controller support,
touchscreen UI, multi-track recording, live streaming, and a web control surface.

## Features

- **16-channel mixer** with 3-band EQ, compressor, gate, gain, pan, mute, solo per channel
- **4 aux sends**, 2 subgroups, 2 VCA groups, master bus with dim and monitor
- **MIDI controller support** — CC, NRPN, learn mode, clock sync, JACK MIDI bridge
- **Multi-track recording** — per-channel WAV capture with write-ahead buffering, punch in/out
- **Backing track player** — sync'd playback with metronome, loop/one-shot/segue modes
- **Live streaming** — GStreamer H.264 to YouTube, Twitch, Facebook, or custom RTMP
- **Session manager** — save/load mixer states, setlists with transitions, auto-save
- **Touchscreen UI** — Kivy-based multi-touch interface for 5"/7" displays
- **Web control surface** — FastAPI REST API + WebSocket real-time updates
- **OSC server** — Open Sound Control for DAW integration (Ableton, Reaper, etc.)
- **Plugin host** — LV2, VST2, NAM neural amp models via Carla rack
- **Fader automation** — record, playback, scenes with interpolation
- **SD card image builder** — automated build script produces ready-to-flash images

## Architecture

```
┌──────────────────────────────────────────────────────────────┐
│                     User Interfaces                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐  │
│  │ Touch UI    │  │ Web UI       │  │ MIDI Controllers   │  │
│  │ (Kivy/HDMI) │  │ (FastAPI)    │  │ (USB/ALSA seq)     │  │
│  └──────┬──────┘  └──────┬───────┘  └────────┬───────────┘  │
│         │                │                    │              │
├─────────┼────────────────┼────────────────────┼──────────────┤
│         │       REST/WS  │        OSC         │ MIDI/CC/NRPN │
│  ┌──────▼────────────────▼────────────────────▼──────────┐   │
│  │              Mixer Engine (Python)                     │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │   │
│  │  │DSP Engine│ │Recording │ │ Streaming│ │ Session  │  │   │
│  │  │+ Carla   │ │(WAV)     │ │(GStream) │ │ Manager  │  │   │
│  │  └────┬─────┘ └──────────┘ └──────────┘ └──────────┘  │   │
│  │       │ OSC                                             │   │
│  │  ┌────▼─────────────────────────────────────────────┐  │   │
│  │  │              Carla Rack (LV2/VST/NAM)            │  │   │
│  │  └────────────────────┬─────────────────────────────┘  │   │
│  └───────────────────────┼────────────────────────────────┘   │
│                          │ JACK                               │
│                    ┌─────▼──────┐                              │
│                    │  JACK2 RT  │  SCHED_FIFO prio 70         │
│                    └─────┬──────┘                              │
│                          │ ALSA hw:USB                        │
├──────────────────────────┼────────────────────────────────────┤
│  Kernel                  │                                    │
│  ┌───────────────────────▼──────────────────────────────┐     │
│  │  PREEMPT_RT 6.12.y  │  snd-usb-audio  │  xHCI USB   │     │
│  └──────────────────────────────────────────────────────┘     │
└──────────────────────────────────────────────────────────────┘
```

## Quick Start

### Option 1: Download SD Card Image (Recommended)

1. Download the latest `rpi-audio-mixer-*.img.xz` from [Releases](https://github.com/your-org/rpi-audio-mixer/releases)
2. Flash to a 16GB+ SD card:
   ```bash
   xz -d rpi-audio-mixer-*.img.xz
   sudo dd if=rpi-audio-mixer-*.img of=/dev/sdX bs=4M status=progress conv=fsync
   ```
3. Insert SD card into RPi 4B, connect USB audio interface, power on
4. Follow the first-boot setup wizard on HDMI display
5. Open `http://pi-mixer.local:8080` in your browser

### Option 2: Build from Source

```bash
# Install build dependencies
sudo apt install wget xz-utils dosfstools e2fsprogs qemu-user-static

# Quick build (stock kernel, 10-15 min)
./build/build.sh --skip-kernel

# Full build with PREEMPT_RT kernel (30-45 min)
./build/build.sh
```

See [docs/build-guide.md](docs/build-guide.md) for detailed instructions.

### Option 3: Development Setup

```bash
# Install dependencies
sudo apt install jackd2 carla python3-pip
pip install fastapi uvicorn python-jack-client numpy

# Run tests
python -m pytest tests/ -v

# Start the API server (without full hardware)
python -m src.network.run
```

## Project Structure

```
├── src/
│   ├── mixer/          DSP engine, channel strips, routing, OSC, automation
│   ├── midi/           MIDI engine, learn mode, clock sync, device discovery
│   ├── session/        Session manager, setlists, snapshots
│   ├── recording/      Multi-track WAV recorder with punch in/out
│   ├── backing/        Backing track player, metronome, transport
│   ├── streaming/      GStreamer pipeline, platform presets, camera
│   ├── network/        REST API, WebSocket, OSC server, auth
│   ├── plugin/         Plugin manager, LV2/VST/NAM support, scanner
│   └── ui/             Kivy touchscreen UI, widgets, screens
├── tests/              735 tests (pytest)
├── build/              SD card image builder + first-boot scripts
├── scripts/            Utility scripts (Carla presets, LV2 lint, NAM build)
└── docs/               User and developer documentation
```

## Documentation

| Document | Description |
|----------|-------------|
| [docs/build-guide.md](docs/build-guide.md) | Step-by-step SD card image build instructions |
| [docs/user-manual.md](docs/user-manual.md) | Comprehensive mixer operation guide |
| [docs/hardware-compatibility.md](docs/hardware-compatibility.md) | Tested USB interfaces, MIDI controllers, displays |
| [docs/developer-guide.md](docs/developer-guide.md) | Architecture, contributing, source build |
| [docs/troubleshooting.md](docs/troubleshooting.md) | Common issues and solutions |
| [build/README.md](build/README.md) | Image builder reference |

## System Requirements

- **Computer:** Raspberry Pi 4 Model B (4GB+ RAM recommended)
- **SD Card:** 16GB+ Class A2 (32GB+ recommended for recordings)
- **Display:** HDMI touchscreen (official 7" or Waveshare 5") or headless via web UI
- **Audio:** USB audio interface (class-compliant UAC2)
- **Network:** Ethernet recommended; WiFi supported
- **Power:** 5V/3A USB-C power supply

## Performance

| Metric | Value |
|--------|-------|
| Round-trip latency | <10ms (128 frames @ 48kHz) |
| Channels | 16 mono / 8 stereo |
| Sample rate | 48 kHz (44.1k and 96k supported) |
| Bit depth | 32-bit float (internal), 16/24-bit WAV |
| CPU usage (idle) | ~5% (all 16 channels driven) |
| Recording tracks | Up to 16 simultaneous WAV |
| Streaming | 1080p30 H.264 @ 4-8 Mbps |

## Status

All planned phases complete:

- [x] P1: System Research & OS Selection — RPiOS Lite + PREEMPT_RT
- [x] P2: ALSA + JACK2 Low-Latency Configuration
- [x] P3: Core Mixer Engine, Backing Tracks, Multi-Track Recording
- [x] P4: MIDI Controller Support with Learn Mode
- [x] P5: Web App + Touchscreen UI (Kivy)
- [x] P6: Streaming Pipeline + Session Manager
- [x] P7: SD Card Image Builder + Documentation

## License

MIT