P7-R2: Wiki documentation — Obsidian + Gitea wiki pages
Lint & Validate / lint (push) Has been cancelled
Lint & Validate / lint (push) Has been cancelled
This commit is contained in:
@@ -1,58 +1,173 @@
|
||||
# Raspberry Pi Real-Time Audio Mixer
|
||||
|
||||
RPi4B-based multi-channel real-time audio mixer with custom PREEMPT_RT kernel.
|
||||
[](https://www.python.org/)
|
||||
[](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/)
|
||||
[](LICENSE)
|
||||
[](tests/)
|
||||
[](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
|
||||
|
||||
- **Platform:** Raspberry Pi 4 Model B (8GB RAM)
|
||||
- **OS:** Raspberry Pi OS Lite (64-bit, Bookworm) + custom PREEMPT_RT kernel
|
||||
- **Audio:** USB audio interface with multi-channel I/O
|
||||
- **Goal:** Low-latency (<10ms round-trip) multi-channel audio mixing
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 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
|
||||
|
||||
```
|
||||
├── docs/ Research, architecture decisions, manuals
|
||||
│ ├── research/ Technical research reports
|
||||
│ ├── decisions/ Architecture Decision Records (ADRs)
|
||||
│ └── manuals/ Hardware/software manuals and references
|
||||
├── src/ Source code (audio engine, DSP, UI)
|
||||
├── build/ Build scripts and cross-compilation tooling
|
||||
├── recipes/ Buildroot/Yocto recipes (if applicable)
|
||||
├── scripts/ Utility and deployment scripts
|
||||
└── wiki/ Local wiki pages
|
||||
├── 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
|
||||
|
||||
**Phase 1-7: Complete audio mixer stack with SD card image builder**
|
||||
All planned phases complete:
|
||||
|
||||
- [x] P1-R1: System Research — USB audio, PREEMPT_RT kernel analysis
|
||||
- [x] P1-R2: Base OS Selection — RPiOS Lite 64-bit + custom PREEMPT_RT
|
||||
- [x] P2-R1: ALSA + JACK2 Low-Latency Config
|
||||
- [x] P3-R1: Core Mixer Engine — DSP pipeline, channel strips, routing
|
||||
- [x] P3-R2: Backing Track Player — sync'd audio playback
|
||||
- [x] P3-R3: Multi-Track Recording — WAV capture + session
|
||||
- [x] P4-R1: MIDI Controller Support — Binding + Learn Mode
|
||||
- [x] P5-R3: Web App Frontend — touch-optimized mixer UI
|
||||
- [x] P6-R1: Streaming Pipeline — GStreamer H.264 to YouTube/Twitch
|
||||
- [x] P6-R2: Session Manager — save/load mixer states + setlists
|
||||
- [x] P7-R1: Build Script — automated SD card image creation
|
||||
|
||||
## SD Card Image Builder
|
||||
|
||||
```bash
|
||||
# Build a ready-to-flash SD card image
|
||||
./build/build.sh --skip-kernel # Quick build (10-15 min)
|
||||
./build/build.sh # Full build with RT kernel (30-45 min)
|
||||
```
|
||||
|
||||
See [build/README.md](build/README.md) for flashing instructions and full documentation.
|
||||
|
||||
## Getting Started
|
||||
|
||||
*Documentation coming in Phase 2+*
|
||||
- [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
|
||||
|
||||
TBD
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user