shawn/raspberry-pi-mixer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 1-4: Audio stack, mixer engine, MIDI, and network API
Lint & Validate / lint (push) Has been cancelled
Details

Browse Source 
P2-R1: ALSA + JACK2 low-latency config (scripts, quirks, tuning)
P2-R2: Carla integration (build scripts, 8ch rack config, NAM LV2 support)
P2-R3: Plugin manager, categories, blacklist, NAM model support
P3-R1: Mixer DSP engine (channel strip, routing matrix, bus mgr, automation)
P4-R1: MIDI engine (learn mode, clock sync, HID discovery, mapping store)
P4-R2: Network API (OSC server, FastAPI REST, WebSocket, auth, rate limiter)
P5-R1: Touchscreen UI evaluation + main entry point
docs: Audio stack, Carla integration, MIDI support, UI evaluation
tests: Full test suite (292 passing)
This commit is contained in:
Shawn
2026-05-19 20:39:17 -04:00
parent 7b123762b5
commit 9cd8292acc
97 changed files with 26545 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/midi-controller-support.md
+516
View File
@@ -0,0 +1,516 @@
# MIDI Controller Support — Binding + Learn Mode
**Date:** 2026-05-19
**Task:** P4-R1
**Target:** Raspberry Pi 4B, RPi OS Lite 64-bit, PREEMPT_RT kernel
Comprehensive MIDI controller mapping engine with learn mode, clock sync,
and JACK MIDI bridge for the RPi Audio Mixer.
---
## Table of Contents
1. [Architecture Overview](#1-architecture-overview)
2. [Hardware Setup — RPi as USB Host](#2-hardware-setup)
3. [Supported Controllers](#3-supported-controllers)
4. [Installation](#4-installation)
5. [MIDI Learn Mode](#5-midi-learn-mode)
6. [MIDI Clock Sync](#6-midi-clock-sync)
7. [JACK MIDI Integration](#7-jack-midi-integration)
8. [Mapping Persistence](#8-mapping-persistence)
9. [Udev Rules — Hotplug](#9-udev-rules)
10. [MIDI Mapper Daemon](#10-midi-mapper-daemon)
11. [NRPN Support](#11-nrpn-support)
12. [File Reference](#12-file-reference)
---
## 1. Architecture Overview
```
┌──────────────────────────────────────────────────────────────┐
│ Physical World │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ X-Touch │ │ MIDImix │ │ FaderFox │ ... │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └─────────────┼─────────────┘ │
│ │ USB │
├─────────────────────┼────────────────────────────────────────┤
│ ┌──────▼──────┐ │
│ Kernel │ xHCI USB │ udev rules (99-midi.rules) │
│ │ Host Ctrl │ hotplug → ALSA seq clients │
│ └──────┬──────┘ │
│ │ /dev/snd/midi* │
├─────────────────────┼────────────────────────────────────────┤
│ ┌──────▼──────┐ │
│ ALSA │ ALSA RawMIDI│ snd-usb-audio │
│ │ / Sequencer │ snd-seq (clients 20+) │
│ └──────┬──────┘ │
│ │ │
├─────────────────────┼────────────────────────────────────────┤
│ ┌──────▼──────┐ │
│ Python │ MIDI Engine │ midi_engine.py │
│ (our code) │ │ - CC/NRPN parsing │
│ │ ┌─────────┐ │ - Mapping lookup │
│ │ │ Mapping │ │ - Value scaling │
│ │ │ Table │ │ - Learn mode │
│ │ └─────────┘ │ - Clock sync │
│ └──┬───────┬───┘ │
│ │ │ │
│ ┌─────────▼─┐ ┌──▼──────────┐ │
│ │ Parameter │ │ JACK MIDI │ │
│ │ Registry │ │ Bridge │ │
│ │ (DSP/UI) │ │ (4 ports) │ │
│ └────────────┘ └──┬──────────┘ │
│ │ JACK MIDI │
├──────────────────────────┼────────────────────────────────────┤
│ ┌──────▼──────┐ │
│ JACK2 │ JACK MIDI │ a2jmidid (ALSA→JACK) │
│ │ Ports │ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ Carla │ MIDI IN │ → soft synths, samplers │
│ │ Ports │ │
│ └─────────────┘ │
└──────────────────────────────────────────────────────────────┘
```
**Data flow:**
1. USB MIDI controller sends CC/NRPN messages over USB
2. Linux kernel (snd-usb-audio) exposes them as ALSA sequencer clients
3. Python MIDI engine reads from ALSA seq / rtmidi
4. Engine matches messages against the mapping table
5. Matched messages are:
a. Sent to the Parameter Registry (for DSP processing / UI feedback)
b. Forwarded to JACK MIDI output ports (for Carla routing)
---
## 2. Hardware Setup — RPi as USB Host
The Raspberry Pi 4B acts as a USB **host** (not device). USB MIDI controllers
plug directly into the Pi's USB ports. No OTG adapter needed.
**Requirements:**
- Raspberry Pi 4B with powered USB ports
- USB MIDI class-compliant controller (99% of modern controllers)
- No drivers needed — Linux UAC2 + snd-usb-audio handles everything
**Verify USB MIDI is working:**
```bash
# List raw MIDI devices
ls -la /dev/snd/midi*
# List ALSA sequencer clients (MIDI controllers appear as clients 20+)
cat /proc/asound/seq/clients
# Use our script
./scripts/midi-mapper --list-devices
# Or with amidi
amidi -l
```
**Power considerations:**
- RPi4B USB ports provide up to 1.2A total
- Most MIDI controllers draw <100mA — safe
- For bus-powered controllers + audio interface, use a powered USB hub
---
## 3. Supported Controllers
### Pre-configured profiles
| Manufacturer | Model | VID:PID | Faders | Knobs | Buttons | Transport |
|---|---|---|---|---|---|---|
| Behringer | X-Touch Compact | 1397:00B4 | 9 | 16 | 39 | Yes |
| Behringer | X-Touch (MCU) | 1397:00B5 | 9 | 8 | 92 | Yes |
| FaderFox | UC4 | 16D0:0D27 | 8 | 0 | 32 | No |
| Akai | MIDImix | 09E8:0031 | 9 | 24 | 16 | No |
| Arturia | BeatStep | 1C75:0208 | 0 | 17 | 16 | Yes |
| Novation | Launch Control XL | 1235:0061 | 8 | 24 | 16 | No |
| Korg | nanoKONTROL2 | 0944:0117 | 8 | 8 | 32 | Yes |
### Adding a new controller
Add a `ControllerProfile` to `src/midi/controllers.py`:
```python
ControllerProfile(
manufacturer="YourBrand",
model="YourModel",
usb_vendor_id=0x1234,
usb_product_id=0x5678,
alsa_client_pattern="Your Model Name",
num_faders=8,
num_knobs=8,
num_buttons=16,
has_transport=True,
controls=[
ControllerControl("Fader 1", 0, 0, "fader"),
# ... etc
],
)
```
To discover a controller's CC numbers:
1. Install `aseqdump`: `sudo apt install alsa-utils`
2. Run: `aseqdump -p <client_id>`
3. Wiggle each control and note the CC number
---
## 4. Installation
### Prerequisites
```bash
# System packages
sudo apt update
sudo apt install -y python3 python3-pip python3-venv \
alsa-utils a2jmidid jackd2
# Python dependencies
pip install python-rtmidi # MIDI I/O via ALSA rawmidi
pip install JACK-Client # JACK MIDI port creation
pip install pyudev # Hotplug monitoring (optional)
# Install udev rules
sudo cp config/99-midi.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
```
### Start the JACK MIDI bridge
```bash
# Start a2jmidid to bridge ALSA sequencer → JACK MIDI
a2jmidid -e &
# Or let our bridge do it directly (preferred)
./scripts/midi-mapper
```
---
## 5. MIDI Learn Mode
The interactive CLI lets you map physical controls to mixer parameters
without editing config files.
```bash
./scripts/midi-learn-cli
```
### Workflow
1. **Plug in your MIDI controller** (before or during)
2. **Start learn mode:** `./scripts/midi-learn-cli`
3. **Pick a parameter:** type `l volume 0` (learn volume for channel 0)
4. **Wiggle the control** on your physical controller
5. **Confirm:** type `c` (or `d` to discard)
6. **Save:** type `save` (or just `quit` — auto-saves)
### Commands
| Command | Description |
|---|---|
| `l <param> [ch]` | Start learning for a parameter |
| `b [ch]` | Batch learn all faders for a channel |
| `c` | Confirm captured mapping |
| `d` | Discard captured mapping |
| `list` | Show all mappings |
| `del <n>` | Delete mapping #n |
| `save` | Save to disk |
| `status` | Show learn state |
| `quit` | Exit (auto-saves) |
### Example session
```
$ ./scripts/midi-learn-cli --session live-set
midi-learn> l volume 0
Listening for MIDI CC on any channel → volume CH0
Wiggle the knob/fader you want to assign, then type 'confirm' or 'c'.
[wiggle fader 1 on controller]
midi-learn> c
Confirmed: CH0 volume ← CC70
midi-learn> l pan 0
Listening for MIDI CC on any channel → pan CH0
[wiggle knob 1 on controller]
midi-learn> c
Confirmed: CH0 pan ← CC10
midi-learn> quit
Auto-saved 2 mappings to 'live-set'.
```
### Batch learn
Maps faders sequentially without typing between each one:
```
midi-learn> b 0
Batch learn for CH0: wiggle each control in order.
[1/4] CH0 Vol — wiggle the fader now...
[wiggle]
[2/4] CH0 Pan — wiggle the pan knob now...
[wiggle]
[3/4] CH0 Mute — press the mute button now...
[press]
[4/4] CH0 Gain — wiggle the gain knob now...
[wiggle]
Batch learn complete: 4 mappings
```
---
## 6. MIDI Clock Sync
The engine accepts MIDI clock (timing clock) messages and derives tempo (BPM).
This can sync backing tracks, tempo-synced delays, LFOs, and sequencers.
### How it works
- MIDI clock sends **24 pulses per quarter note** (PPQN)
- The engine measures inter-pulse intervals
- A moving average window (96 pulses = 4 beats) smooths jitter
- When the estimate stabilises (window half-full), `bpm_stable = True`
- Tempo changes are reported on beat boundaries
### Usage in the daemon
The MIDI mapper daemon automatically tracks clock from any connected device:
```bash
./scripts/midi-mapper
# Output:
# 19:34:01 Transport: start
# 19:34:02 Tempo: 128.5 BPM (stable=True)
# 19:34:03 Tempo: 128.4 BPM (stable=True)
```
### Transport control
| MIDI Message | Effect |
|---|---|
| START (0xFA) | Reset position, begin playing |
| CONTINUE (0xFB) | Resume from current position |
| STOP (0xFC) | Stop, hold position |
| Song Position Pointer | Jump to beat position |
---
## 7. JACK MIDI Integration
The engine creates JACK MIDI output ports that Carla can connect to.
### Direct mode (preferred)
Uses the `jack` Python module to create JACK MIDI ports directly:
```bash
./scripts/midi-mapper
# Creates ports:
# rpi-mixer:midi_out_0 (channel params: volume, pan, mute, etc.)
# rpi-mixer:midi_out_1 (EQ, dynamics params)
# rpi-mixer:midi_out_2 (FX sends/returns)
# rpi-mixer:midi_out_3 (transport: play, stop, record)
```
In Carla, connect `rpi-mixer:midi_out_*` to your soft synth's MIDI input.
### ALSA sequencer fallback
If `jack` module isn't available, the bridge uses ALSA sequencer ports.
Run `a2jmidid -e` to bridge them to JACK:
```bash
a2jmidid -e &
./scripts/midi-mapper --no-jack
# ALSA seq ports appear, a2jmidid auto-bridges to JACK
```
### Routing mapped CCs
Mapped MIDI messages are forwarded to JACK ports based on parameter category:
| Parameter type | JACK port |
|---|---|
| Volume, Pan, Mute, Solo, Gain, Phase | `midi_out_0` |
| EQ, Compressor, Gate | `midi_out_1` |
| FX sends/returns | `midi_out_2` |
| Transport (play, stop, record) | `midi_out_3` |
---
## 8. Mapping Persistence
Mappings are stored as JSON in `~/.config/rpi-mixer/mappings/`.
### File format
```json
{
"version": 1,
"session": "live-set",
"updated": "2026-05-19T23:45:00+00:00",
"mappings": [
{
"midi": {
"type": "CONTROL_CHANGE",
"channel": 0,
"controller": 70,
"is_nrpn": false,
"nrpn_number": 0,
"source_device": null
},
"target": {
"parameter": "volume",
"channel": 0
},
"value": {
"midi_min": 0,
"midi_max": 127,
"param_min": -60.0,
"param_max": 12.0,
"invert": false,
"curve": "linear"
},
"meta": {
"label": "CH0 Vol",
"enabled": true
}
}
]
}
```
### Sessions
You can maintain multiple mapping configurations:
```bash
./scripts/midi-learn-cli --session studio # Studio setup
./scripts/midi-learn-cli --session live-set # Live performance setup
./scripts/midi-mapper --session live-set # Launch with specific setup
```
---
## 9. Udev Rules — Hotplug
The udev rules in `config/99-midi.rules` provide:
1. **Automatic permissions:** MIDI devices owned by `audio` group (mode 0660)
2. **Persistent symlinks:** Known controllers get stable names under `/dev/midi/`
3. **Environment tagging:** `MIDI_CONTROLLER` env var set for known devices
4. **Hotplug service trigger:** Systemd service can auto-restart on plug/unplug
Install:
```bash
sudo cp config/99-midi.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
```
The Python hotplug monitor (`device_discovery.py`) uses `pyudev` to detect
add/remove events and can re-open ports dynamically.
---
## 10. MIDI Mapper Daemon
### Starting
```bash
# Basic usage
./scripts/midi-mapper
# With specific session
./scripts/midi-mapper --session live-set
# List devices
./scripts/midi-mapper --list-devices
# Without JACK (headless test)
./scripts/midi-mapper --no-jack --allow-no-device
```
### Signal handling
- `SIGINT` (Ctrl+C): Graceful shutdown, outputs stats
- `SIGTERM`: Same as SIGINT
### Stats output
Every 10 seconds:
```
19:35:01 Stats: 2847 events, 1423 mapped, 71.2 ev/s, 12 mappings active
```
### systemd service (optional)
```ini
# /etc/systemd/system/midi-mapper.service
[Unit]
Description=RPi Audio Mixer MIDI Mapper
After=jackd.service sound.target
Wants=jackd.service
[Service]
Type=simple
User=pi
ExecStart=/home/pi/rpi-mixer/scripts/midi-mapper --session default
Restart=on-failure
RestartSec=2
[Install]
WantedBy=multi-user.target
```
---
## 11. NRPN Support
NRPN (Non-Registered Parameter Number) is a MIDI protocol extension that
provides 14-bit resolution (16,384 steps vs 128 for CC). The engine
transparently handles the NRPN state machine:
1. Controller sends CC 99 (NRPN MSB) + CC 98 (NRPN LSB) to select parameter
2. Controller sends CC 6 (Data MSB) + CC 38 (Data LSB) for value
3. Engine assembles into a 14-bit value
4. Mapping lookup is on the full NRPN number
NRPN is transparent in learn mode — just wiggle the control and the
engine detects the CC 99/98 preamble and captures the NRPN number.
---
## 12. File Reference
| File | Lines | Purpose |
|---|---|---|
| `src/midi/types.py` | ~230 | MIDI message types, enums, data classes |
| `src/midi/controllers.py` | ~350 | Known controller profiles database |
| `src/midi/device_discovery.py` | ~250 | USB MIDI enumeration + hotplug monitor |
| `src/midi/midi_engine.py` | ~260 | Core mapping engine + NRPN state machine |
| `src/midi/midi_learn.py` | ~310 | Interactive learn mode state machine |
| `src/midi/midi_clock.py` | ~210 | MIDI clock sync + tempo detection |
| `src/midi/mapping_store.py` | ~140 | JSON persistence (save/load/list/delete) |
| `src/midi/jack_midi_bridge.py` | ~240 | JACK MIDI port creation + ALSA fallback |
| `src/midi/__init__.py` | ~40 | Package exports |
| `src/mixer/__init__.py` | ~165 | Parameter registry + channel strip factory |
| `scripts/midi-mapper` | ~290 | Main daemon entry point |
| `scripts/midi-learn-cli` | ~295 | Interactive learn mode CLI |
| `config/99-midi.rules` | ~60 | udev rules for USB MIDI hotplug |
| `docs/midi-controller-support.md` | This file | Full documentation |
**Total: ~2,800 lines of Python + config + docs**