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
2. First Boot & Setup Wizard
3. Web Control Surface
4. Touchscreen UI
5. MIDI Controller Operation
6. Multi-Track Recording
7. Backing Tracks
8. Live Streaming
9. Session Management
10. OSC / DAW Integration
11. Plugins & Effects
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

---

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:

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

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:

# 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:

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

# 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:

# 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 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:

   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:

   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:

# 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:

   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/:

   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:

   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 →
Skip	←
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

# 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:

   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:

# 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:

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

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:

   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:

# 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

# 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:

   curl -X POST http://pi-mixer.local:8080/scenes/Chorus/save \
        -H "X-API-Key: your-key"
   

2. Load a scene (instant recall):

   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:

# 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