Midirun

Overview

Midirun turns any MIDI controller into a macro pad on Linux. Press a pad or key on the controller and Midirun types a key or a key combination, which any application can bind to whatever it wants. It runs as a daemon, works under both Wayland and X11, and is published on the AUR along with its GUI companion, Midirun Config.

How it works

Midirun reads MIDI input through RtMidi and compares the first two bytes of each message with the mappings in its config. For a note-on message, those are the status byte and the note number. When a message matches, it sends the mapped key codes.

Keys are sent through /dev/uinput, the kernel's interface for virtual input devices, which is why it doesn't care which display server you run: to Wayland or X11 the controller looks like another keyboard. Midirun presses every key in a mapping in order and then releases them all, so one pad can send a shortcut like Ctrl+Shift+T. Writing to /dev/uinput needs permission, so the project ships a script that installs a udev rule giving the input group access.

Mappings live in a TOML file:

[config]
inputPort = 2 # The port of your input device

[[mapping]]
name = "Top Left Button"
byte0 = 144
byte1 = 38
key = [2, 3, 4] # Key codes can be found with showkey --keycode

It's meant to run as a systemd user service. Sending it SIGHUP (which systemctl --user reload does) reloads the config without restarting the daemon, and SIGINT or SIGTERM shut it down cleanly.

Midirun Config

Midirun Config is a GUI for building that file, written in C++ with gtkmm 4. It has a console that listens to a MIDI port and shows the incoming data, an editor for adding and removing mappings, and a keycode capture that reads the next key you press through libevdev, so you don't have to look codes up with showkey. It then generates the TOML file for the daemon. If it can't read /dev/input, it still works, and you enter key codes by hand.

Packaging

Both programs build with Meson and are packaged on the AUR, so on Arch installing is one yay command plus adding yourself to the input group. The daemon ships with its systemd user unit, and the READMEs cover building from source on Arch, Fedora and Debian. The daemon also has a CLI for setup: --list-io lists MIDI ports, and --listen prints raw messages from a port so you can find the bytes a pad sends.