raspberry-pi-mixer/docs/user-manual.md

# User Manual — Raspberry Pi Real-Time Audio Mixer

Comprehensive guide to operating the RPi Audio Mixer — from hardware setup to
live streaming.

## Table of Contents

1. [Hardware Setup](#1-hardware-setup)
2. [First Boot & Setup Wizard](#2-first-boot--setup-wizard)
3. [Web Control Surface](#3-web-control-surface)
4. [Touchscreen UI](#4-touchscreen-ui)
5. [MIDI Controller Operation](#5-midi-controller-operation)
6. [Multi-Track Recording](#6-multi-track-recording)
7. [Backing Tracks](#7-backing-tracks)
8. [Live Streaming](#8-live-streaming)
9. [Session Management](#9-session-management)
10. [OSC / DAW Integration](#10-osc--daw-integration)
11. [Plugins & Effects](#11-plugins--effects)
12. [Fader Automation & Scenes](#12-fader-automation--scenes)

---

## 1. Hardware Setup

### Required Equipment

- Raspberry Pi 4 Model B (4GB+ RAM)
- USB audio interface (class-compliant UAC2)
- Boot media (choose one):
  - **SD card** (16GB+, Class A2) — good for dev/testing
  - **USB SSD** via USB 3.0 — more reliable, but shares USB bus with audio
  - **NVMe SSD + HAT** (PCIe) — **recommended for live use** — no bus contention
- 5V/3A USB-C power supply
- **Optional:** HDMI touchscreen, USB MIDI controller, Ethernet cable, USB camera

> 💡 **Storage recommendation:** For live performances and recording, use an NVMe
> HAT (official RPi, Pimoroni, or Geekworm) with a 128GB+ NVMe SSD. It uses
> dedicated PCIe lanes and won't compete with your USB audio interface for bandwidth.

### Connections

```
                    ┌──────────────────────┐
    USB Audio  ←──→ │                      │
    Interface       │   Raspberry Pi 4B    │──→ HDMI Touchscreen
                    │                      │
  MIDI Controller ──│                      │──→ Ethernet (router)
                    │                      │
     USB Camera  ───│                      │
                    └──────────────────────┘
                           │
                     5V/3A Power
```

1. Connect the USB audio interface to a **USB 3.0 (blue) port** — these have
   dedicated bandwidth and lower latency than USB 2.0 ports
2. Connect MIDI controllers to any remaining USB port
3. Connect the HDMI touchscreen (if using)
4. Connect Ethernet for reliable networking (WiFi works but can cause audio dropouts)
5. Insert the SD card and power on

### USB Audio Interface Setup

The system auto-detects class-compliant USB audio interfaces. For interfaces
with multiple modes (e.g., Behringer UMC1820), ensure the device is in the
correct mode before powering on the Pi.

Verified interfaces: see [docs/hardware-compatibility.md](hardware-compatibility.md)

---

## 2. First Boot & Setup Wizard

### Booting for the First Time

1. Insert your boot media (SD, USB SSD, or NVMe) into the Pi
2. Connect audio interface, MIDI controllers, and network
3. Power on

> ⚡ If booting from USB SSD or NVMe, the Pi's EEPROM must be configured to try
> your boot device first. The setup wizard includes an EEPROM configuration step,
> or you can configure it manually beforehand:
> ```bash
> sudo rpi-eeprom-config --edit
> # USB boot:  BOOT_ORDER=0xf41
> # NVMe boot: BOOT_ORDER=0xf614
> ```

On first boot, the **setup wizard** runs automatically on the HDMI display (or
serial console). It walks through:
### Wizard Steps

1. **Welcome screen** — language selection
2. **Audio interface detection** — the wizard scans USB for audio devices and
   presents a list. Select your interface.
3. **WiFi configuration** — scan for networks, enter password. Skip for Ethernet.
4. **Hostname** — set a custom hostname (default: `pi-mixer`)
5. **API key** — auto-generated and displayed. **Write this down** — you need it
   for web UI access. Can be changed later.
6. **JACK settings** — buffer size and sample rate:
   - **Low latency** (128 frames @ 48kHz, ~2.7ms) — for live monitoring
   - **Stable** (256 frames @ 48kHz, ~5.3ms) — for plugin-heavy sessions
   - **Maximum stability** (512 frames @ 48kHz, ~10.7ms) — for recording
7. **Reboot** — system restarts into normal operation

### Re-running the Wizard

```bash
sudo touch /force-firstboot && sudo reboot
```

---

## 3. Web Control Surface

Access the mixer from any device on the same network via the web UI.

### Access

```
http://pi-mixer.local:8080
```

Or use the IP address:
```bash
# Find the Pi's IP
ssh pi@pi-mixer.local "ip addr show | grep 'inet '"
# Open http://<ip-address>:8080
```

### Authentication

Enter the API key from the setup wizard. The key is also stored in:
```bash
grep API_KEY /etc/systemd/system/mixer-api.service
```

### Mixer View

The main mixer screen shows:

```
┌─────────┬─────────┬─────────┬─────────┬─────────┐
│ CH 1    │ CH 2    │ CH 3    │ ...     │ Master  │
│ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │         │ ┌─────┐ │
│ │█████│ │ │███░░│ │ │█░░░░│ │         │ │████░│ │
│ │█████│ │ │███░░│ │ │█░░░░│ │         │ │████░│ │
│ │█████│ │ │███░░│ │ │█░░░░│ │         │ │████░│ │
│ │█████│ │ │███░░│ │ │█░░░░│ │         │ │████░│ │
│ └─────┘ │ └─────┘ │ └─────┘ │         │ └─────┘ │
│  -3 dB  │   0 dB  │  -∞ dB  │         │  -6 dB  │
│ [M][S]  │ [M][S]  │ [M][S]  │         │ [M][D]  │
└─────────┴─────────┴─────────┴─────────┴─────────┘
```

- **Fader** — drag up/down to adjust volume (-60 dB to +12 dB)
- **M** button — mute the channel (red when active)
- **S** button — solo the channel (yellow when active)
- **Channel label** — tap to open channel detail panel

### Channel Detail Panel

Tap a channel label to open:

- **3-band EQ** — Low (20-500 Hz), Mid (200-8000 Hz), High (2000-20000 Hz)
  with frequency, gain (±15 dB), and Q controls
- **Compressor** — threshold, ratio, attack, release, makeup gain
- **Gate** — threshold, range
- **Gain** — preamp gain (-20 to +60 dB)
- **Pan** — stereo position
- **FX Sends** — send level to Aux A and Aux B
- **Phase invert** — toggle

### Master Section

- **Master Volume** — main output level
- **Mute** — silence all outputs
- **Dim** — reduce output by -20 dB (for talkback)
- **Monitor Volume** — control room monitor level
- **Phones Volume** — headphone output level

### Navigation Tabs

- **Mixer** — channel strips and master
- **Routing** — JACK routing matrix (drag connections between ports)
- **Plugins** — plugin browser and chain editor
- **Session** — save/load sessions, setlists
- **Record** — multi-track recording controls
- **Stream** — live streaming controls
- **Settings** — API key, network, display, audio config

### Keyboard Shortcuts (Web UI)

| Key | Action |
|-----|--------|
| `1-8` | Select channel 1-8 |
| `↑/↓` | Adjust fader ±1 dB |
| `Shift+↑/↓` | Adjust fader ±0.1 dB |
| `M` | Toggle mute on selected channel |
| `S` | Toggle solo on selected channel |
| `Space` | Transport play/stop |
| `R` | Start/stop recording |
| `Esc` | Deselect channel |

---

## 4. Touchscreen UI

The Kivy-based touch UI runs directly on the HDMI display — no browser needed.

### Screen Layout

The UI has four screens, cycled by swiping or pressing ESC:

1. **Mixer Surface** — faders, meters, mute/solo for all 16 channels + master
2. **Routing Matrix** — drag to connect JACK audio ports
3. **Plugin Chain** — per-channel plugin slots with drag-and-drop
4. **Settings** — brightness, display timeout, DPI override

### Touch Gestures

| Gesture | Action |
|---------|--------|
| Swipe up/down on fader | Adjust volume |
| Tap fader cap | Select channel |
| Double-tap fader | Set to 0 dB (unity) |
| Swipe left/right | Navigate between screens |
| Long-press mute/solo | Latch mode (stays until pressed again) |
| Pinch (routing screen) | Zoom routing matrix |

### Launch Options

```bash
# Local mixer
python3 main_touch.py

# Remote mixer
python3 main_touch.py --host 192.168.1.10 --api-key my-key

# Force DPI (for non-standard displays)
KIVY_DPI=220 python3 main_touch.py
```

### Hardware Buttons (if available)

Some touchscreens include physical buttons that can be mapped:

```bash
# Example udev rule for Waveshare 5" buttons
# Maps KEY_UP/DOWN to channel select
```

---

## 5. MIDI Controller Operation

Connect any class-compliant USB MIDI controller to control mixer parameters.

### Supported Controllers

The MIDI engine auto-detects controllers. Pre-configured mappings exist for:

- **Behringer X-Touch** — 8 motorized faders, transport, scribble strips
- **Akai MIDImix** — 8 faders, 24 knobs, 16 buttons
- **Korg nanoKONTROL 2** — 8 faders, 8 knobs, transport
- **Novation Launch Control XL** — 8 faders, 24 knobs, 16 buttons

See [docs/hardware-compatibility.md](hardware-compatibility.md) for the full list
and custom mapping instructions.

### MIDI Learn Mode

Map any MIDI controller to any mixer parameter without editing config files:

1. **Enter learn mode:**
   ```bash
   curl -X POST http://pi-mixer.local:8080/midi/learn/start \
        -H "X-API-Key: your-key"
   ```
   Or press the "Learn" button in the web UI or touch UI.

2. **Click the parameter** you want to map (e.g., Channel 3 Volume)

3. **Move the physical control** on your MIDI controller (fader, knob, or button)

4. The mapping is saved automatically. Exit learn mode:
   ```bash
   curl -X POST http://pi-mixer.local:8080/midi/learn/stop \
        -H "X-API-Key: your-key"
   ```

### MIDI Clock Sync

The mixer can act as MIDI clock master or slave:

- **Master mode:** mixer transport controls tempo; connected devices sync to it
- **Slave mode:** mixer follows external MIDI clock from a drum machine or DAW

Configure via the web UI → Settings → MIDI or via API:
```bash
# Set as slave
curl -X PUT http://pi-mixer.local:8080/midi/clock/mode \
     -H "X-API-Key: your-key" \
     -H "Content-Type: application/json" \
     -d '{"mode": "slave"}'
```

### NRPN Support

High-resolution 14-bit NRPN messages are supported for parameters that benefit
from fine control (filter frequency, Q, etc.). The MIDI engine auto-detects
NRPN vs. CC messages from your controller.

---

## 6. Multi-Track Recording

Record up to 16 channels simultaneously to individual WAV files.

### Recording Setup

1. **Arm tracks** — in the web UI, click the **R** (record arm) button on each
   channel you want to record. Armed channels show a red indicator.

2. **Set recording directory:**
   The default is `/data/recordings/session_NNN/`. Change via:
   ```bash
   curl -X PUT http://pi-mixer.local:8080/recording/path \
        -H "X-API-Key: your-key" \
        -H "Content-Type: application/json" \
        -d '{"path": "/data/recordings/live-set-2026"}'
   ```

3. **Configure recording format:**
   - Bit depth: 16-bit, 24-bit, or 32-bit float
   - Sample rate: inherits from JACK (48 kHz default)
   - Punch in/out: set in/out points for selective recording

### Recording Controls

| Action | Web UI | API |
|--------|--------|-----|
| Start recording | Press **⏺ Record** | `POST /transport/command {"command": "record"}` |
| Stop recording | Press **⏹ Stop** | `POST /transport/command {"command": "stop"}` |
| Punch in | Automatic at marker | `POST /recording/punch/in {"channel": 3}` |
| Punch out | Automatic at marker | `POST /recording/punch/out {"channel": 3}` |
| New take | Creates new take file | `POST /recording/take/new` |

### Recording Tips

- **Use a fast SD card** — Class A2 minimum for 16-track recording.
  Class A1 works for 8 tracks or fewer.
- **Monitor disk space** with `df -h /data`. The web UI shows a disk meter.
- **Punch in/out** is seamless — no clicks or gaps at edit points.
- **Auto-save** backs up session state every 30 seconds during recording.
- Each recording session creates a timestamped directory:
  `/data/recordings/session_001/` containing `channel_01.wav` through
  `channel_16.wav` plus `session_metadata.json`.

---

## 7. Backing Tracks

Play synchronized backing tracks alongside live inputs.

### Setup

1. **Upload tracks** to `/data/backing/`:
   ```bash
   scp my-backing.wav pi@pi-mixer.local:/data/backing/
   ```

2. **Supported formats:** WAV (16/24/32-bit), FLAC, MP3, AIFF, OGG

3. **Create a playlist** via the web UI → Backing Tracks → New Playlist, or:
   ```bash
   curl -X POST http://pi-mixer.local:8080/backing/playlist \
        -H "X-API-Key: your-key" \
        -H "Content-Type: application/json" \
        -d '{"name": "Set 1", "tracks": ["intro.wav", "song1.wav", "song2.flac"]}'
   ```

### Playback Modes

- **One-shot** — play once and stop
- **Loop** — repeat indefinitely
- **Segue** — auto-advance to next track with configurable crossfade (0.5-10s)
- **Playlist** — sequential playback with optional transitions

### Transport Controls

| Control | Description |
|---------|-------------|
| Play | Start playback from current position |
| Stop | Stop and return to start |
| Pause | Pause at current position |
| Skip →| | Next track |
| Skip |← | Previous track |
| Loop | Toggle loop mode |
| Count-in | Play 1-2 bar count-in before playback |

### Metronome / Click Track

The built-in metronome provides a click track routed to a dedicated output:

- **Tempo:** 20-300 BPM (tap tempo supported)
- **Time signature:** 1/4 through 13/8
- **Sounds:** click, beep, sidestick, custom samples
- **Output routing:** typically phones or a dedicated aux output

```bash
# Set tempo and enable click
curl -X PUT http://pi-mixer.local:8080/transport/tempo \
     -H "X-API-Key: your-key" \
     -H "Content-Type: application/json" \
     -d '{"bpm": 128}'
curl -X POST http://pi-mixer.local:8080/transport/metronome/on \
     -H "X-API-Key: your-key"
```

---

## 8. Live Streaming

Stream audio and video to YouTube, Twitch, Facebook Live, or any RTMP server.

### Quick Start — Stream to YouTube

1. **Get your stream key** from YouTube Studio → Go Live → Stream Settings

2. **Connect a USB camera** (or use Raspberry Pi Camera Module)

3. **Start streaming** via the web UI → Stream, or:
   ```bash
   curl -X POST http://pi-mixer.local:8080/stream/start \
        -H "X-API-Key: your-key" \
        -H "Content-Type: application/json" \
        -d '{
          "platform": "youtube",
          "stream_key": "your-youtube-stream-key",
          "video_source": "usb",
          "audio_source": "mixer_master",
          "bitrate_video": 4500,
          "bitrate_audio": 192
        }'
   ```

### Platform Presets

| Platform | Video Bitrate | Audio Bitrate | Resolution | Notes |
|----------|--------------|---------------|------------|-------|
| YouTube | 4500-9000 Kbps | 192 Kbps | 1080p30/720p60 | H.264 recommended |
| Twitch | 4500-6000 Kbps | 160 Kbps | 1080p30/720p60 | Max 6000 Kbps |
| Facebook | 4000 Kbps | 128 Kbps | 720p30 | Max 720p |
| Custom RTMP | User-defined | User-defined | User-defined | Any RTMP server |

### Scenes

Create named scenes with different camera angles and overlays:

```bash
# Save current camera/layout as scene
curl -X POST http://pi-mixer.local:8080/stream/scenes/wide-shot/save \
     -H "X-API-Key: your-key"

# Switch scenes
curl -X POST http://pi-mixer.local:8080/stream/scenes/close-up/load \
     -H "X-API-Key: your-key"
```

### Streaming Tips

- **Use Ethernet** — WiFi can cause dropped frames. If using WiFi, reduce
  bitrate to 2500 Kbps.
- **Monitor bitrate** — the web UI shows a real-time bitrate meter. If it
  drops, reduce video bitrate.
- **Dedicated audio bus** — route the stream audio to a subgroup for
  independent level control vs. live PA.
- **CPU headroom** — 16 channels + streaming uses ~60% CPU on RPi 4.
  Reduce channel count or buffer size if you hit limits.

---

## 9. Session Management

Save and recall complete mixer states — all fader positions, EQ settings,
plugin states, routing, and transport.

### Save a Session

Via web UI → Session → Save, or:
```bash
curl -X POST http://pi-mixer.local:8080/sessions/save \
     -H "X-API-Key: your-key" \
     -H "Content-Type: application/json" \
     -d '{"name": "Live at The Garage", "notes": "Soundcheck levels"}'
```

### Load a Session

```bash
curl -X POST "http://pi-mixer.local:8080/sessions/Live%20at%20The%20Garage/load" \
     -H "X-API-Key: your-key"
```

### Setlists

Group sessions into setlists with configurable transitions:

1. Create a setlist:
   ```bash
   curl -X POST http://pi-mixer.local:8080/setlists \
        -H "X-API-Key: your-key" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Summer Tour Set",
          "items": [
            {"session": "Soundcheck", "transition": "cut"},
            {"session": "Opener", "transition": "crossfade", "duration": 3.0},
            {"session": "Main Set", "transition": "crossfade", "duration": 5.0},
            {"session": "Encore", "transition": "wait"}
          ]
        }'
   ```

2. Transition types:
   - **Cut** — instant switch
   - **Crossfade** — smooth transition over N seconds
   - **Wait** — manual advance (press "Next")

### Auto-Save

The mixer auto-saves state every 30 seconds (configurable) to
`~/.config/rpi-mixer/sessions/_autosave_YYYY-MM-DD.json`. The last 10
auto-saves are kept (older ones are rotated out).

### Snapshots

Capture instantaneous snapshots without creating a full session:

```bash
# MIDI-mappable: assign a button to snapshot save/load
# Save snapshot 3 (0-127 snapshots available)
curl -X POST http://pi-mixer.local:8080/snapshots/3/save \
     -H "X-API-Key: your-key"

# Load snapshot 3
curl -X POST http://pi-mixer.local:8080/snapshots/3/load \
     -H "X-API-Key: your-key"
```

---

## 10. OSC / DAW Integration

The mixer exposes all parameters via Open Sound Control, enabling integration
with DAWs (Ableton Live, Reaper, Bitwig, Ardour) and custom controllers.

### OSC Server

- **Address:** `pi-mixer.local:9001` (UDP)
- **Endpoint format:** `/mixer/channel/<n>/<parameter>`
- **Value range:** 0.0 to 1.0 (normalized)

### Common OSC Commands

```
/mixer/channel/1/volume    0.75          # Set channel 1 volume to 0 dB
/mixer/channel/1/mute      1             # Mute channel 1
/mixer/channel/1/pan       -0.5          # Pan channel 1 left
/mixer/channel/1/eq_low_gain  0.5        # Boost channel 1 low EQ by 7.5 dB
/mixer/master/volume       0.8           # Set master volume
/mixer/transport/play      1             # Start transport
/mixer/transport/stop      1             # Stop transport
/mixer/transport/tempo     128.0         # Set tempo to 128 BPM
```

### OSC Query

The server responds to OSC queries:
```
/mixer/channel/1/volume    →  returns current value
/mixer/channel/*/volume    →  returns all 16 channel volumes
```

### Ableton Live Setup

1. Add a new MIDI/OSC controller in Ableton preferences
2. Configure output to `pi-mixer.local:9001` (UDP)
3. Map Live's faders to `/mixer/channel/N/volume`
4. Map Live's transport to `/mixer/transport/play`, `/mixer/transport/stop`

---

## 11. Plugins & Effects

The mixer uses **Carla** as its plugin host, supporting LV2, VST2, and NAM
(Neural Amp Modeler) formats.

### Plugin Browser

Access via web UI → Plugins. Browse by category:

- **Dynamics** — compressors, gates, limiters, expanders
- **EQ** — parametric, graphic, shelving
- **Reverb** — plate, hall, room, spring
- **Delay** — digital, tape, ping-pong
- **Modulation** — chorus, flanger, phaser, tremolo
- **Distortion** — overdrive, fuzz, amp sims, NAM captures
- **Utility** — meters, analyzers, routing tools

### Per-Channel Plugin Chain

Each channel supports up to 8 plugin slots in series:

```
Input → [Gate] → [EQ] → [Comp] → [Amp] → [FX Slot 1] → [FX Slot 2] → Fader → Output
```

Plugins can be reordered by dragging in the UI.

### Aux Sends & Returns

Four aux buses (FX A through D) provide shared effects:

1. Route a channel to an aux via its **FX Send** knob
2. Insert effects on the aux return (e.g., reverb on Aux A, delay on Aux B)
3. Blend the wet signal with the channel strip's dry signal
4. Control the overall aux level via **FX Return** faders in the master section

### NAM (Neural Amp Modeler)

Load guitar/bass amp captures for realistic amp simulation:

1. Place `.nam` files in `/data/presets/nam/`
2. Insert a NAM plugin on a channel
3. Select the capture from the dropdown
4. Adjust input gain and output level

```bash
# Scan for new NAM models
curl -X POST http://pi-mixer.local:8080/plugins/scan \
     -H "X-API-Key: your-key"
```

---

## 12. Fader Automation & Scenes

### Fader Automation

Record and playback fader movements:

1. **Arm automation** for a channel (click **A** button)
2. **Press Play** — fader movements are recorded
3. **Press Stop** — automation lane is saved
4. **Playback** — faders move automatically according to recorded automation
5. **Overwrite** — re-record by arming again

Automation modes:
- **Read** — playback recorded automation (fader is read-only)
- **Write** — record new automation (overwrites existing)
- **Touch** — record only while touching the fader
- **Latch** — record from first touch until stop

### Scenes

Scenes are snapshots of all fader positions that can be recalled instantly:

1. **Save a scene:**
   ```bash
   curl -X POST http://pi-mixer.local:8080/scenes/Chorus/save \
        -H "X-API-Key: your-key"
   ```

2. **Load a scene** (instant recall):
   ```bash
   curl -X POST http://pi-mixer.local:8080/scenes/Chorus/load \
        -H "X-API-Key: your-key"
   ```

3. **Next/Previous scene** (MIDI-mappable for footswitch control)

Modifier scenes only affect specific channels:

```bash
# Save a modifier scene that only changes channels 1-4
curl -X POST http://pi-mixer.local:8080/scenes/Vocals-Up/save \
     -H "X-API-Key: your-key" \
     -d '{"mode": "modifier", "channels": [1, 2, 3, 4]}'
```

---

## Appendix: REST API Quick Reference

All endpoints require `X-API-Key` header.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/channels` | List all channel states |
| GET | `/channels/{n}` | Get channel n state |
| PUT | `/channels/{n}/parameter` | Set channel parameter |
| GET | `/mixes` | Master bus + aux + subgroups |
| PUT | `/mixes/parameter` | Set master parameter |
| GET | `/transport` | Transport state |
| PUT | `/transport/command` | Play/stop/record/loop |
| GET | `/routing` | JACK routing matrix |
| GET | `/plugins` | Plugin list |
| GET | `/scenes` | Scene list |
| POST | `/scenes/{name}/save` | Save current state as scene |
| POST | `/scenes/{name}/load` | Load a scene |
| GET | `/sessions` | Session list |
| POST | `/sessions/{name}/save` | Save session |
| POST | `/sessions/{name}/load` | Load session |
| POST | `/setlists` | Create setlist |
| GET | `/stream/status` | Streaming status |
| POST | `/stream/start` | Start streaming |
| POST | `/stream/stop` | Stop streaming |
| POST | `/recording/start` | Start recording |
| POST | `/recording/stop` | Stop recording |
| POST | `/midi/learn/start` | Enter MIDI learn mode |
| POST | `/midi/learn/stop` | Exit MIDI learn mode |
| GET | `/stats` | Server statistics |
| GET | `/ws` | WebSocket for real-time updates |