Skip to content
BlueSialiaPublic

About

Desktop app to map any MIDI controller to PipeWire audio controls and shell commands

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

MIDI Does logo

MIDI Does

Hippocratic License HL3-BOD-CL-ECO-FFD-LAW-MEDIA-MIL-MY-SV-TAL-USTA-XUAR


Map any MIDI controller to PipeWire audio controls and shell commands. Use knobs, faders, and buttons on your MIDI hardware to manage system audio — volume, mute, routing, default devices — or run arbitrary commands with MIDI value substitution.

For more details on the project structure and design, see the ADR document.

Feature Coverage

Feature checklist

Test functions are tagged with #feature <ID>.

[x] tested   [ ] supported, no test yet   [-] not supported

MIDI

  • MIDI-CC — CC message input
  • MIDI-NOTE — Note On message input (Note Off ignored — actions fire once)
  • MIDI-PB — Pitch bend input
  • MIDI-SX — SysEx message input
  • MIDI-LEARN — MIDI learn mode (auto-detect CC/Note/PitchBend)
  • MIDI-MON — MIDI event monitor panel
  • MIDI-HOT — Hotplug auto-reconnect for known devices
  • MIDI-PORTS — MIDI port discovery and enumeration
  • MIDI-OUT — MIDI output (Note, CC, SysEx)
  • [-] MIDI-AT — Channel / polyphonic aftertouch
  • [-] MIDI-THRU — MIDI pass-through
  • [-] MIDI-CLOCK — MIDI Clock sync (send or receive)
  • [-] MIDI-VCURVE — Velocity curve adjustment

Actions

  • ACT-VOL — Volume control: sink, source, stream (absolute & relative)
  • ACT-MUTE — Mute toggle: sink, source
  • ACT-ROUTE — Stream routing
  • [-] ACT-DEF — Set default sink / source
  • ACT-CMD — Run shell command with $RAW_VALUE, $NORM_VALUE, $BANK_OFFSET
  • [-] ACT-LED — LED on / off / toggle / blink
  • ACT-MIDI — MIDI send action (Note, CC)
  • ACT-LAYER — Software layer selection
  • ACT-BANK — Bank offset / increment / decrement
  • ACT-MULTI — Multiple actions per control
  • ACT-ENC — Encoder modes: Sign-Magnitude, Two's Complement, Binary Offset
  • [-] ACT-TOGGLE — Toggle vs momentary button mode
  • [-] ACT-COND — Conditional actions (e.g. if volume > X)
  • [-] ACT-MACRO — Macro chains with delays

MCU Protocol

  • MCU-FADER — MCU fader input (pitch bend with bank offset)
  • MCU-SCRIB — Scribble strip output (7-char × 2 line SysEx)
  • MCU-RING — LED ring output via MCU SysEx (Single mode; Pan/Fan/Spread not implemented)
  • MCU-BANK — Fader bank offset (+8 / -8 / set)
  • [-] MCU-VPOT — V-Pot assignment modes
  • [-] MCU-JOG — Jog wheel support
  • [-] MCU-TC — Timecode display

Faceplate

  • FACE-GRID — Configurable icon grid (rows × columns)
  • FACE-ICON — Icon types: Button, Knob, Fader, Encoder
  • FACE-SPAN — Icon span (multi-cell, e.g. 1×4 fader)
  • FACE-EDIT — Icon editor modal with inline control editing
  • FACE-MULTI — Multiple controls per icon
  • FACE-VIS — Visual state on icons
  • [-] FACE-COLOR — Custom icon / grid colors
  • [-] FACE-REORDER — Drag-and-drop icon reordering
  • [-] FACE-TEMPLATE — Icon templates for known controllers

Reactive Feedback

  • FB-MUTE — Mute state → button LED mirroring (via feedback source)
  • FB-RING — Volume level → LED ring segments via feedback source (MCU SysEx led_ring or standard CC led_ring_cc outputs)
  • FB-SCRIB — PipeWire object name → scribble strip auto-population (via feedback source)
  • [-] FB-RATE — Feedback rate limiting / debouncing (80 ms)
  • FB-CUSTOM — User-defined feedback sources (Source::Custom commands)

PipeWire

  • PW-OBJ — Object listing (sinks, sources, streams)
  • PW-VOL — Volume state monitoring
  • PW-MUTE — Mute state monitoring
  • PW-CONN — PipeWire connection monitoring
  • PW-META — Stream metadata enrichment
  • [-] PW-METER — Audio level meters in the UI
  • [-] PW-MATRIX — Audio routing matrix view
  • [-] PW-EQ — EQ / audio effect controls

Configuration

  • CFG-DEV — Device configuration persistence (TOML)
  • CFG-CTRL — Control mapping persistence (TOML)
  • CFG-LOAD — Config load with graceful defaults
  • CFG-SAVE — Config save with directory creation
  • [-] CFG-IMPORT — Import / export individual device configs
  • [-] CFG-PRESET — Presets for known controller models

UI / System

  • UI-TRAY — System tray integration (icon click/Show restores, Quit exits; close button hides to tray)
  • UI-THEME — System theme detection (dark / light)
  • UI-KEYS — Keyboard shortcuts (Escape, Ctrl+S)
  • UI-MODAL — Modal dialogs (add device, icon editor)
  • UI-STATUS — Status bar (status message, active layer)
  • [-] UI-HEADLESS — CLI / headless mode (no GUI)
  • [-] UI-MULTIWIN — Multiple device windows
  • UI-MINIMIZE — Minimize to tray on close

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See Install for notes on how to install the project on a live system.

Prerequisites

  • Rust 1.99.1 (rustup or mise)
  • Nix with flakes enabled (optional, for the reproducible development shell)
  • System libraries: pipewire, alsa-lib, udev, vulkan-loader, libxkbcommon, libx11, libxcb, libxcursor, libxrandr, libxi, libxext, libxinerama, libxxf86vm, wayland, dbus, libclang, plus pkg-config
  • A running PipeWire session
  • A MIDI controller connected to your system (ALSA MIDI)

The exact package names vary by distribution; most systems ship these split into development packages (-dev on Debian/Ubuntu, -devel on Fedora/openSUSE). On NixOS none of this needs to be installed by hand. The development shell provides it (see Setup).

Setup

Clone the repository, enable the local Git hooks, and build:

git clone git@github.com:BlueSialia/midi-does.git
cd midi-does
./setup-hooks.sh
cargo build --release

The binary will be at target/release/midi-does.

In the repository settings, enable Settings → Actions → General → Workflow permissions → “Allow GitHub Actions to create and approve pull requests” so the release workflow can open its automated pull request.

With Nix and direnv:

direnv allow

Otherwise, enter the development shell with nix develop. The shell provides the Rust toolchain and the system libraries listed above, so on NixOS this is the most automatic way to get started. Then run the usual cargo commands inside the shell, or prefix them with nix develop --command, e.g. nix develop --command cargo build --release.

Running

cargo run

Or run the built binary directly:

./target/release/midi-does

Running the Tests

Unit Tests

You can run the unit tests with:

cargo test --workspace --lib --bins

Unit tests are located in each source file (inline #[cfg(test)] modules).

Integration Tests

You can run the integration tests with:

cargo test --workspace --test integration

Integration tests live in the tests/ directory.

Linting

On top of it you should also periodically run the linter with:

cargo clippy --all-targets --all-features -- -D warnings

And verify that the documentation builds without warnings:

RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps

Coding Style

In order to maintain a similar style over the codebase we use:

cargo fmt --all -- --check

Install

Each GitHub release includes a .deb, a .rpm, and the raw binary, along with a Nix recipe for Nix users.

If you want to build and install from source then:

Build the release binary and place it anywhere in $PATH:

cargo build --release
install -m 755 target/release/midi-does ~/.local/bin/

To install the desktop entry and icons (for launching from your application menu):

install -Dm 644 data/midi-does.desktop ~/.local/share/applications/midi-does.desktop
for size in 16 22 24 32 48 64 128 256 512; do
    install -Dm 644 "assets/midi-does-$size.png" \
        "$HOME/.local/share/icons/hicolor/${size}x${size}/apps/midi-does.png"
done
install -Dm 644 assets/midi-does.svg \
    ~/.local/share/icons/hicolor/scalable/apps/midi-does.svg

The desktop entry launches midi-does from $PATH and uses the midi-does icon name, so both the binary and the icons must be installed as shown above.

The app reads its configuration from $XDG_CONFIG_HOME/midi-does/config.toml (typically ~/.config/midi-does/config.toml). No other files are created at runtime.

configs/x-touch mini.toml is a complete example device configuration (an X-TOUCH MINI mapping). Copy it to your config path as a starting point, e.g. cp "configs/x-touch mini.toml" ~/.config/midi-does/config.toml.

Built With

Dependency Purpose
Rust Application language
Cargo The Rust package manager
iced GUI framework
midir MIDI input discovery and message parsing
pipewire (v0.10) PipeWire bindings (object discovery, volume/mute, routing)
ksni KDE StatusNotifierItem system tray
toml + serde Configuration file parsing
dirs XDG base directory paths
dark-light System theme detection (dark / light)
thiserror Error type derivation
log + env_logger Logging
MCU Protocol Mackie Control Universal protocol (SysEx, pitch bend, scribble strips, LED rings)

Automations

Local Git hooks enforce Conventional Commits. CI runs formatting, Clippy, tests, documentation, unused-dependency, and security checks. Binary size reporting and release publishing are also automated.

Release publishing produces .deb and .rpm packages plus a Nix recipe alongside the raw binary.

See AUTOMATIONS.md for more information and details.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the Hippocratic License 3.0 - see the LICENSE.md file for details.

Acknowledgments

  • The midir and pipewire-rs maintainers
  • The Iced project for a pure-Rust GUI toolkit
  • PipeWire and WirePlumber for the modern Linux audio stack

About

Desktop app to map any MIDI controller to PipeWire audio controls and shell commands

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Used by

Contributors

Languages