Skip to content


codecov Documentation Status PyPI version

midi-app-controller is an app, that allows user to control all applications using 'pyapp-kit/app-model' with a USB MIDI controller.


Documentation at

Usage (napari)#

MIDI App Controller is a package designed to integrate MIDI controllers with Python Qt apps using app-model. As of now, it is used most commonly with napari, a viewer for multi-dimensional images. We will show how to use MIDI App Controller with napari but getting started with other applications should look very similar.


To install MIDI App Controller in your environment (where Python and napari are already installed), use this command:

pip install midi-app-controller

napari will automatically detect the package and install the plugin next time it starts.

To install the newest development version, clone the GitHub repo and install it as a local package.


Launch the plugin from the Plugins menu.

A panel will open to the side.


If your MIDI controller is supported out of the box, you can simply select the appropriate model. If not, you will need to tell MIDI App Controller how to interact with this model of controller by creating a controller schema.

Once you have selected the controller schema, you can select binds schema.

MIDI ports#

If they haven't been selected automatically, select MIDI input and output ports that correspond to your physical controller.

Start handling#

After a controller and bindings are selected, you can click "Start handling". This will start a thread that listens to all input from the controller and invokes appropriate commands. You can close the panel with the settings, the thread will work in the background until you click "Stop handling".

Edit binds#

Click "Edit binds" to open dialog where you can configure bindings by choosing which physical buttons and knobs on your controller correspond to which commands in the application. Think of it like configuring keyboard shortcuts.

All configurations are simple YAML files which you can copy, share, or edit manually. You can click "Reveal in explorer" to see the exact location of the currently chosen config file. You shouldn't edit built-in presets stored in the package directory; when you edit a built-in preset in the graphical user interface, a copy will automatically be created.

After you save changes, if you have already started handling, you need to click "Restart handling" to start a new server with the changes applied.

Usage without GUI#

The library can be also controlled using the singleton of StateManager class:

from midi_app_controller.state.state_manager import get_state_manager

state = get_state_manager()
# Now the library can be controlled using `state`.



python3 -m pip install -e .


python3 -m pip install -e .[testing]
python3 -m pytest --cov .

Testing docs#

mkdocs serve -a localhost:8080

Using pre-commit#

python3 -m pip install -e .[dev]
pre-commit install