MIDI Controller Mapping

MIDI Controller Mapping

AetherSDR supports class-compliant USB MIDI controllers for hands-on control of radio parameters. Any standard MIDI controller — Behringer X-Touch Mini, Korg nanoKONTROL, Akai MIDImix, or any device that sends standard MIDI CC/Note messages — can map its knobs, faders, and buttons to AetherSDR controls.

Requirements

• A class-compliant USB MIDI controller (no special drivers needed)
• AetherSDR built with RtMidi support (rtmidi package)
• Linux: sudo pacman -S rtmidi (Arch) or sudo apt install librtmidi-dev (Debian/Ubuntu)

RtMidi is an optional dependency. If not installed, the MIDI Mapping menu item will not appear.

Quick Start

1. Plug in your MIDI controller
2. Open Settings → MIDI Mapping
3. Click Refresh to see your controller in the port dropdown
4. Select it and click Connect — status turns green
5. Move a knob or fader — the activity indicator shows the MIDI message
6. Select a parameter from the dropdown (e.g., "AF Gain")
7. Click Learn, then move the knob you want to assign
8. The binding appears in the table — that knob now controls AF Gain

MIDI Learn

MIDI Learn is the fastest way to create bindings:

1. Choose a parameter from the dropdown (filter by category: RX, TX, Phone/CW, EQ, Global)
2. Click Learn — the button changes to "Cancel Learn"
3. Move a knob, push a button, or slide a fader on your controller
4. AetherSDR captures the MIDI message (CC number, channel) and creates the binding
5. The binding is saved automatically to ~/.config/AetherSDR/midi.settings

Supported MIDI Messages

Message Type	Use	Example
Control Change (CC)	Knobs, faders, sliders	CC #7 → AF Gain (0-127 maps to 0-200)
Note On/Off	Buttons, pads	Note C3 → Toggle MOX
Pitch Bend	High-resolution tuning	14-bit (0-16383) for smooth VFO control

Mappable Parameters (50+)

RX Controls

Parameter	Type	Range
AF Gain	Slider	0–200
Squelch Level	Slider	0–100
AGC Threshold	Slider	0–100
Audio Pan	Slider	0–100
Noise Blanker	Toggle	on/off
Noise Reduction	Toggle	on/off
Auto Notch	Toggle	on/off
Squelch Enable	Toggle	on/off
Audio Mute	Toggle	on/off
Tune Lock	Toggle	on/off
RIT Enable	Toggle	on/off
XIT Enable	Toggle	on/off
NR2 (Spectral)	Toggle	on/off
RN2 (RNNoise)	Toggle	on/off
Step Size Up/Down	Trigger	momentary
Tune Up/Down	Slider	relative (center=64)

TX Controls

Parameter	Type	Range
RF Power	Slider	0–100
Tune Power	Slider	0–100
MOX	Toggle	on/off
TUNE	Toggle	on/off
ATU Start	Trigger	momentary

Phone/CW Controls

Parameter	Type	Range
Mic Level	Slider	0–100
Monitor Volume	Slider	0–100
Speech Processor	Toggle	on/off
DAX	Toggle	on/off
Monitor	Toggle	on/off
VOX Enable	Toggle	on/off
VOX Level	Slider	0–100
AM Carrier	Slider	0–100
CW Speed	Slider	5–100 WPM

Equalizer

Parameter	Type	Range
TX/RX EQ Enable	Toggle	on/off
8 frequency bands	Slider	-10 to +10 dB each

Global

Parameter	Type	Range
Master Volume	Slider	0–100
Headphone Volume	Slider	0–100
Master Mute	Toggle	on/off
TX Button	Toggle	on/off
TNF Global	Toggle	on/off

Mapping Dialog

Open via Settings → MIDI Mapping. The dialog has:

• Device selector — dropdown of available MIDI ports with Connect/Disconnect
• Activity indicator — shows last received MIDI message (channel, type, CC#, value)
• Auto-connect — automatically reconnect to the last device on startup
• Binding table — all active bindings with parameter name, MIDI source, channel, invert toggle, and delete button
• Category filter — filter the parameter list by RX, TX, Phone/CW, EQ, or Global
• Learn button — start MIDI Learn for the selected parameter
• Profiles — save and load named binding sets for different controllers

Binding Options

Each binding in the table supports:

• Invert — reverse the value range (useful for faders that are physically upside-down)
• Delete — remove the binding (× button)
• Channel — displays the MIDI channel (1-16) the binding responds to

Profiles

Save your bindings as a named profile for easy switching between controllers:

1. Type a profile name in the profile field
2. Click Save — bindings are saved to ~/.config/AetherSDR/midi/<name>.xml
3. Switch controllers, click Load to recall a different profile

Value Mapping

MIDI values are scaled to each parameter's range:

• Sliders: CC value 0–127 maps linearly to the parameter's min–max range
• Toggles: CC > 63 = on, ≤ 63 = off. Note On toggles the current state.
• Triggers: Fire on Note On or CC > 63 (one-shot, no repeat on hold)
• Pitch Bend: 14-bit value (0–16383) for high-resolution control

Settings File

All MIDI configuration is stored in a dedicated file, separate from the main AetherSDR settings:

~/.config/AetherSDR/midi.settings     — device preferences and active bindings
~/.config/AetherSDR/midi/<name>.xml   — saved profiles

Troubleshooting

No MIDI ports shown

• Check that your controller is plugged in and recognized: amidi -l should list it
• Click Refresh to re-scan
• Ensure rtmidi is installed

MIDI Mapping menu not visible

AetherSDR was built without RtMidi. Install rtmidi and rebuild:

sudo pacman -S rtmidi  # Arch
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build -j$(nproc)

Knob moves but parameter doesn't change

• Verify the binding exists in the table
• Check the activity indicator — if it shows a different CC# than expected, re-learn the binding
• Make sure the radio is connected (parameters only work when connected)

Values jump or are reversed

• Use the Invert checkbox in the binding table to reverse the direction
• Some controllers send CC values 0-127 in reverse (fader up = 0)