Skip to content
Control your Linux system with MIDI devices
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
midiscriptor - affiche.pdf
midiscriptor - présentation.pdf
midiscriptor - présentation.pptx



Control your Linux system with MIDI-USB controllers


  • A Linux system (may work on other systems if you do the necessary)
  • A MIDI-USB device (works also with a (second) USB keboard)
  • Python 3
  • libusb or OpenUSB (Normally already present in Linux distributions)
  • PyUSB: sudo pip3 install pyusb

Only if you want to use the keyboard mode:

Only if you want to run the and examples:

  • pyGame: sudo pip3 install pygame


First you will have to create a configuration file to let your OS connect to your USB device. For that run the configuration script :

sudo python3

This will create a JSON formatted configuration file. You can use it as a parameter of the configuration script to customize it : sudo python3 config.json or you can edit it as text.

Then you can use your configuration to run midiscriptor :

sudo python3 config.json

3 modes:

  • output: midiscriptor produces standard outputs, which can be used using pipes.
  • command: midiscriptor subprocesses user defined command.
  • keyboard: midiscriptor acts like a computer keyboard: user defined text is written where the focus is.

In command and keyboard mode, you will need to configure actions in your configuration file. Actions are commands to run in command mode and texts to paste in keyboard mode.

In command mode, you can use the syntax {{a:b}} anywhere in the action to let know midiscriptor that this needs to be replaced by a value between a and b. The value is the velocity of the key touched or the rotation of the knob turned.

No actions required in output mode, this mode will just outputs the data from your device formatted as a;b;c:d, where :

  • a represents the type of input, for example: 9 for "key pressed", 8 for "key release", 11 for "knob turned"
  • c represents the ID of the input touched
  • d is the value of the input (velocity of key or rotation of knob)

Developers can use this formatted data in a custom program using pipes, like :

sudo python3 output_config.json | python3

Examples of program interpreting this data are available in the examples/output_mode directory.

You can’t perform that action at this time.