Skip to content

MIDI configuration


Open Stage Control comes bundled with built-in MIDI support if you're using the official package for Linux, OSX or Windows.

Enabling MIDI support on other systems or when building Open Stage Control from sources requires additional softwares to be installed on the server's system:


Install python3-rtmidi from your distribution's package repository, or if it's not available:

  • Install python3 and python3-pip from your distribution's package repository
  • Run this command in a terminal
    python3 -m pip install python-rtmidi --upgrade
  • Download and install Python 3 for Mac OS
  • Open a terminal
  • Install pip (package installer for python) by executing these commands
    curl -o
  • Install python-rtmidi by executing this command
    python -m pip install python-rtmidi --upgrade
  • Download and install Python 3 for Windows
  • make sure to check the option "Add Python 3.x to PATH"
  • Open a terminal (Win+R)
  • Install pip (package installer for python) by executing these commands
    curl -o
  • Install python-rtmidi by executing this command
    python -m pip install python-rtmidi --upgrade


The server's midi option accepts the following parameters, separated by spaces.

If an option contains space characters, it must be quoted.


Print the available MIDI ports to the console when the server starts. This action is also available in the launcher's menu.


Create a virtual MIDI device that will translate OSC messages to MIDI messages

  • device_name is an arbitrary identifier that can be used as a target by widgets (see Widget setup). It doesn't have to match any device's real name.
  • input / output can be port numbers or strings (as reported by the list action). If a string is specified, the first port whose name contains the string will be used (comparison is case-insensitive).


Enable parsing of system exclusive messages (disabled by default).


Enable parsing of midi time code messages (disabled by default).


Enable sending and receiving RPN/NRPN controls on as single /rpn / /nrpn messages instead of 3 or 4 control changes that constitute them.


Enable parsing of midi active sensing messages (disabled by default). Active sensing messages will be received as sysex.


Send program changes with a -1 offset to match some software/hardware implementations


Enable receiving noteOff messages with a velocity and on a different address than noteOn messages.

device_name:virtual (Linux / Mac only): creates a virtual midi device with one input port and one output port

jack (Linux only): use JACK MIDI instead of ALSA. python-rtmidi must be compiled with jack support for this to work.


Only use this if you know what you are doing. This option should not be set when using the official Linux / Windows / OSX packages.

Indicates where to find python binary in case open stage control doesn't (Error: spawn python3 ENOENT).

Widget setup#

In order to send MIDI messages, a widget must have at least one target formatted as follows:

midi:device_name (where device_name is one of the declared midi devices)

Its address and preArgs properties must be set according to Open Stage Control's midi messages specification.


Messages received from a MIDI port only affect widgets that send to this port.


Enabling the server's debug options will print some extra information (sent/received midi messages, midi setup information, etc)

Example configuration#

Setting the server's midi option as follows:

sysex synth:1,2 daw:3,3
  • enables sysex support (sysex messages will not be ignored)
  • creates a midi device "synth" connected with input 1 and output 2
  • creates a midi device "daw" connected with input 3 and output 3

If a widget has its target set to midi:synth, it will receive MIDI from port 1 and send MIDI to port 2.