Skip to main content

Control napari with a MIDI controller.

Project description


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

midi_app_controller-0.0.11.tar.gz (147.1 kB view hashes)

Uploaded Source

Built Distribution

midi_app_controller-0.0.11-py3-none-any.whl (157.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page