Classes¶

class rtmidi.MidiIn¶

Midi input client interface.

You can specify the low-level MIDI backend API to use via the rtapi keyword or the first positional argument, passing one of the module-level API_* constants. You can get a list of compiled-in APIs with the module-level get_compiled_api function. If you pass API_UNSPECIFIED (the default), the first compiled-in API, which has any input ports available, will be used.

You can optionally pass a name for the MIDI client with the name keyword or the second positional argument. Names with non-ASCII characters in them have to be passed as unicode or utf-8 encoded strings in Python 2. The default name is "RtMidiIn Client".

Note

With some backend APIs (e.g. ALSA), the client name is set by the first MidiIn or MidiOut created by your program and does not change until all MidiIn and MidiOut instances are deleted and then a new one is created.

The queue_size_limit argument specifies the size of the internal ring buffer in which incoming MIDI events are placed until retrieved via the get_message method (i.e. when no callback function is registered). The default value is 1024 (overriding the default value 100 of the underlying C++ RtMidi library).

cancel_callback(self)¶

Remove the registered callback function for MIDI input.

This can be safely called even when no callback function has been registered.

cancel_error_callback(self)¶

Remove the registered callback function for errors.

This can be safely called even when no callback function has been registered.

close_port(self)¶

get_current_api(self)¶

Return the low-level MIDI backend API used by this instance.

Use this by comparing the returned value to the module-level API_* constants, e.g.:

midiin = rtmidi.MidiIn()

if midiin.get_current_api() == rtmidi.API_UNIX_JACK:
    print("Using JACK API for MIDI input.")

get_message(self)¶

Poll for MIDI input.

Checks whether a MIDI event is available in the input buffer and returns a two-element tuple with the MIDI message and a delta time. The MIDI message is a list of integers representing the data bytes of the message, the delta time is a float representing the time in seconds elapsed since the reception of the previous MIDI event.

The function does not block. When no MIDI message is available, it returns None.

get_port_count(self)¶: Return the number of available MIDI input or output ports.

get_port_name(self, unsigned int port, encoding='auto')¶

Return the name of the MIDI input or output port with given number.

Ports are numbered from zero, separately for input and output ports. The number of available ports is returned by the get_port_count method.

The port name is decoded to a (unicode) string with the encoding given by encoding. If encoding is "auto" (the default), then an appropriate encoding is chosen based on the system and the used backend API. If encoding is None, the name is returned un-decoded, i.e. as type str in Python 2 or bytes in Python 3.

get_ports(self, encoding='auto')¶

Return a list of names of available MIDI input or output ports.

The list index of each port name corresponds to its port number.

The port names are decoded to (unicode) strings with the encoding given by encoding. If encoding is "auto" (the default), then an appropriate encoding is chosen based on the system and the used backend API. If encoding is None, the names are returned un-decoded, i.e. as type str in Python 2 or bytes in Python 3.

ignore_types(self, sysex=True, timing=True, active_sense=True)¶

Enable/Disable input filtering of certain types of MIDI events.

By default System Exclusive (aka sysex), MIDI Clock and Active Sensing messages are filtered from the MIDI input and never reach your code, because they can fill up input buffers very quickly.

To receive them, you can selectively disable the filtering of these event types.

To enable reception - i.e. turn off the default filtering - of sysex messages, pass sysex = False.

To enable reception of MIDI Clock, pass timing = False.

To enable reception of Active Sensing, pass active_sensing = False.

These arguments can of course be combined in one call, and they all default to True.

If you enable reception of any of these event types, be sure to either use an input callback function, which returns quickly or poll for MIDI input often. Otherwise you might lose MIDI input because the input buffer overflows.

Windows note: the Windows Multi Media API uses fixed size buffers for the reception of sysex messages, whose number and size is set at compile time. Sysex messages longer than the buffer size can not be received properly when using the Windows Multi Media API.

The default distribution of python-rtmidi sets the number of sysex buffers to four and the size of each to 8192 bytes. To change these values, edit the RT_SYSEX_BUFFER_COUNT and RT_SYSEX_BUFFER_SIZE preprocessor defines in RtMidi.cpp and recompile.

is_port_open(self)¶: Return True if a port has been opened and False if not.

Note

The isPortOpen method of the RtMidi C++ library does not return True when a virtual port has been openend. The python-rtmidi implementation, on the other hand, does.

open_port(self, unsigned int port=0, name=None)¶

Open the MIDI input or output port with the given port number.

Only one port can be opened per MidiIn or MidiOut instance. An RtMidiError exception is raised if an attempt is made to open a port on a MidiIn or MidiOut instance, which already opened a (virtual) port.

You can optionally pass a name for the RtMidi port with the name keyword or the second positional argument. Names with non-ASCII characters in them have to be passed as unicode or utf-8 encoded strings in Python 2. The default name is “RtMidi input” resp. “RtMidi output”.

Note

Closing a port and opening it again with a different name does not change the port name. To change the port name, delete its instance, create a new one and open the port again giving a different name.

Exceptions:

RtMidiError: Raised when trying to open a MIDI port when a (virtual) port has already been opened by this instance.

open_virtual_port(self, name=None)¶

Open a virtual MIDI input or output port.

Only one port can be opened per MidiIn or MidiOut instance. An RtMidiError exception is raised if an attempt is made to open a port on a MidiIn or MidiOut instance, which already opened a (virtual) port.

A virtual port is not connected to a physical MIDI device or system port when first opened. You can connect it to another MIDI output with the OS-dependent tools provided by the low-level MIDI framework, e.g. aconnect for ALSA, jack_connect for JACK, or the Audio & MIDI settings dialog for CoreMIDI.

Note

Virtual ports are not supported by some backend APIs, namely the Windows MultiMedia API. You can use special MIDI drivers like MIDI Yoke or loopMIDI to provide hardware-independent virtual MIDI ports as an alternative.

You can optionally pass a name for the RtMidi port with the name keyword or the second positional argument. Names with non-ASCII characters in them have to be passed as unicode or utf-8 encoded strings in Python 2. The default name is “RtMidi virtual input” resp. “RtMidi virtual output”.

Note

Closing a port and opening it again with a different name does not change the port name. To change the port name, delete its instance, create a new one and open the port again giving a different name.

Also, to close a virtual input port, you have to delete its MidiIn or MidiOut instance.

Exceptions:

NotImplementedError: Raised when trying to open a virtual MIDI port with the Windows MultiMedia API, which doesn’t support virtual ports.
RtMidiError: Raised when trying to open a virtual port when a (virtual) port has already been opened by this instance.

set_callback(self, func, data=None)¶

Register a callback function for MIDI input.

The callback function is called whenever a MIDI message is received and must take two arguments. The first argument is a two-element tuple with the MIDI message and a delta time, like the one returned by the get_message method and the second argument is value of the data argument passed to this function when the callback is registered.

Registering a callback function replaces any previously registered callback.

The callback function is safely removed when the input port is closed or the MidiIn instance is deleted.

set_error_callback(self, func, data=None)¶

Register a callback function for errors.

The callback function is called when an error occurs and must take three arguments. The first argument is a member of enum RtMidiError::Type, represented by one of the ERRORTYPE_* constants. The second argument is an error message. The third argument is the value of the data argument passed to this function when the callback is registered.

Registering an error callback function replaces any previously registered error callback.

class rtmidi.MidiOut¶

Midi output client interface.

You can specify the low-level MIDI backend API to use via the rtapi keyword or the first positional argument, passing one of the module-level API_* constants. You can get a list of compiled-in APIs with the module-level get_compiled_api function. If you pass API_UNSPECIFIED (the default), the first compiled-in API, which has any input ports available, will be used.

You can optionally pass a name for the MIDI client with the name keyword or the second positional argument. Names with non-ASCII characters in them have to be passed as unicode or utf-8 encoded strings in Python 2. The default name is "RtMidiOut Client".

Note

With some APIs (e.g. ALSA), the client name is set by the first MidiIn or MidiOut created by your program and does not change until all MidiIn and MidiOut instances are deleted and then a new one is created.

cancel_error_callback(self)¶

Remove the registered callback function for errors.

This can be safely called even when no callback function has been registered.

close_port(self)¶

Close the MIDI input or output port opened via open_port.

It is safe to call this method repeatedly or if no port has been opened (yet) by this instance.

Also cancels a callback function set with set_callback.

To close a virtual port opened via open_virtual_port, you have to delete its MidiIn or MidiOut instance.

get_current_api(self)¶

Return the low-level MIDI backend API used by this instance.

Use this by comparing the returned value to the module-level API_* constants, e.g.:

midiout = rtmidi.MidiOut()

if midiout.get_current_api() == rtmidi.API_UNIX_JACK:
    print("Using JACK API for MIDI output.")

get_port_count(self)¶: Return the number of available MIDI input or output ports.

get_port_name(self, unsigned int port, encoding='auto')¶

Return the name of the MIDI input or output port with given number.

Ports are numbered from zero, separately for input and output ports. The number of available ports is returned by the get_port_count method.

The port name is decoded to a (unicode) string with the encoding given by encoding. If encoding is "auto" (the default), then an appropriate encoding is chosen based on the system and the used backend API. If encoding is None, the name is returned un-decoded, i.e. as type str in Python 2 or bytes in Python 3.

get_ports(self, encoding='auto')¶

Return a list of names of available MIDI input or output ports.

The list index of each port name corresponds to its port number.

The port names are decoded to (unicode) strings with the encoding given by encoding. If encoding is "auto" (the default), then an appropriate encoding is chosen based on the system and the used backend API. If encoding is None, the names are returned un-decoded, i.e. as type str in Python 2 or bytes in Python 3.

is_port_open(self)¶: Return True if a port has been opened and False if not.

Note

The isPortOpen method of the RtMidi C++ library does not return True when a virtual port has been openend. The python-rtmidi implementation, on the other hand, does.

open_port(self, unsigned int port=0, name=None)¶

Open the MIDI input or output port with the given port number.

Only one port can be opened per MidiIn or MidiOut instance. An RtMidiError exception is raised if an attempt is made to open a port on a MidiIn or MidiOut instance, which already opened a (virtual) port.

You can optionally pass a name for the RtMidi port with the name keyword or the second positional argument. Names with non-ASCII characters in them have to be passed as unicode or utf-8 encoded strings in Python 2. The default name is “RtMidi input” resp. “RtMidi output”.

Note

Closing a port and opening it again with a different name does not change the port name. To change the port name, delete its instance, create a new one and open the port again giving a different name.

Exceptions:

RtMidiError: Raised when trying to open a MIDI port when a (virtual) port has already been opened by this instance.

open_virtual_port(self, name=None)¶

Open a virtual MIDI input or output port.

Only one port can be opened per MidiIn or MidiOut instance. An RtMidiError exception is raised if an attempt is made to open a port on a MidiIn or MidiOut instance, which already opened a (virtual) port.

A virtual port is not connected to a physical MIDI device or system port when first opened. You can connect it to another MIDI output with the OS-dependent tools provided by the low-level MIDI framework, e.g. aconnect for ALSA, jack_connect for JACK, or the Audio & MIDI settings dialog for CoreMIDI.

Note

Virtual ports are not supported by some backend APIs, namely the Windows MultiMedia API. You can use special MIDI drivers like MIDI Yoke or loopMIDI to provide hardware-independent virtual MIDI ports as an alternative.

You can optionally pass a name for the RtMidi port with the name keyword or the second positional argument. Names with non-ASCII characters in them have to be passed as unicode or utf-8 encoded strings in Python 2. The default name is “RtMidi virtual input” resp. “RtMidi virtual output”.

Note

Closing a port and opening it again with a different name does not change the port name. To change the port name, delete its instance, create a new one and open the port again giving a different name.

Also, to close a virtual input port, you have to delete its MidiIn or MidiOut instance.

Exceptions:

NotImplementedError: Raised when trying to open a virtual MIDI port with the Windows MultiMedia API, which doesn’t support virtual ports.
RtMidiError: Raised when trying to open a virtual port when a (virtual) port has already been opened by this instance.

send_message(self, message)¶

Send a MIDI message to the output port.

The message must be passed as an iterable of integers, each element representing one byte of the MIDI message.

Normal MIDI messages have a length of one to three bytes, but you can also send system exclusive messages, which can be arbitrarily long, via this method.

No check is made whether the passed data constitutes a valid MIDI message.

set_error_callback(self, func, data=None)¶

Register a callback function for errors.

The callback function is called when an error occurs and must take three arguments. The first argument is a member of enum RtMidiError::Type, represented by one of the ERRORTYPE_* constants. The second argument is an error message. The third argument is the value of the data argument passed to this function when the callback is registered.

Registering an error callback function replaces any previously registered error callback.