rtmidi package — python-rtmidi 1.5.3 documentation

# rtmidi package

## Submodules

## rtmidi.midiconstants module

Definitions of midi events, controller numbers and parameters.

rtmidi.midiconstants.is_status(byte)

  Return True if the given byte is a MIDI status byte, False otherwise.

## rtmidi.midiutil module

Collection of utility functions for handling MIDI I/O and ports.

Currently contains functions to list MIDI input/output ports, to get the RtMidi API to use from the environment and to open MIDI ports.

rtmidi.midiutil.get_api_from_environment(api=0)

  Return RtMidi API specified in the environment if any.

  If the optional api argument is `rtmidi.API_UNSPECIFIED` (the default), look in the environment variable `RTMIDI_API` for the name of the RtMidi API to use. Valid names are `LINUX_ALSA`, `UNIX_JACK`, `MACOSX_CORE`, `WINDOWS_MM` and `RTMIDI_DUMMY`. If no valid value is found, `rtmidi.API_UNSPECIFIED` will be used.

  Returns a `rtmidi.API_*` constant.

rtmidi.midiutil.list_available_ports(ports=None, midiio=None)

  List MIDI ports given or available on given MIDI I/O instance.

rtmidi.midiutil.list_input_ports(api=0)

  List available MIDI input ports.

  Optionally the RtMidi API can be passed with the `api` argument. If not it will be determined via the `get_api_from_environment` function.

  Exceptions:

  `rtmidi.SystemError`

    Raised when RtMidi backend initialization fails.

rtmidi.midiutil.list_output_ports(api=0)

  List available MIDI output ports.

  Optionally the RtMidi API can be passed with the `api` argument. If not it will be determined via the `get_api_from_environment` function.

  Exceptions:

  `rtmidi.SystemError`

    Raised when RtMidi backend initialization fails.

rtmidi.midiutil.open_midiinput(port=None, api=0, use_virtual=False, interactive=True, client_name=None, port_name=None)

  Open a MIDI port for input and return a MidiIn instance and port name.

  See the `open_midiport` function for information on parameters, return types and possible exceptions.

rtmidi.midiutil.open_midioutput(port=None, api=0, use_virtual=False, interactive=True, client_name=None, port_name=None)

  Open a MIDI port for output and return a MidiOut instance and port name.

  See the `open_midiport` function for information on parameters, return types and possible exceptions.

rtmidi.midiutil.open_midiport(port=None, type_='input', api=0, use_virtual=False, interactive=True, client_name=None, port_name=None)

  Open MIDI port for in-/output and return MidiIn/-Out instance and port name.

  Arguments:

  `port`

    A MIDI port number or (substring of) a port name or `None`.

    Available ports are enumerated starting from zero separately for input and output ports. If only a substring of a port name is given, the first matching port is used.

  `type_`

    Must be `"input"` or `"output"`. Determines whether a `MidiIn` or `MidiOut` instance will be created and returned.

  `api`

    Select the low-level MIDI API to use. Defaults to `API_UNSPECIFIED`, The specified api will be passed to the `get_api_from_environment` function and its return value will be used. If it’s `API_UNSPECIFIED` the first compiled-in API, which has any input resp. output ports available, will be used.

  `use_virtual`

    If `port` is `None`, should a virtual MIDI port be opened? Defaults to `False`.

  `interactive`

    If `port` is `None` or no MIDI port matching the port number or name is available, should the user be prompted on the console whether to open a virtual MIDI port (if `use_virtual` is `True`) and/or with a list of available MIDI ports and the option to choose one? Defaults to `True`.

  `client_name`

    The name of the MIDI client passed when instantiating a `MidiIn` or `MidiOut` object.

    See the documentation of the constructor for these classes for the default values and caveats and OS-dependent ideosyncracies regarding the client name.

  `port_name`

    The name of the MIDI port passed to the `open_port` or `open_virtual_port` method of the new `MidiIn` or `MidiOut` instance.

    See the documentation of the `open_port` resp. `open_virtual_port` methods for the default values and caveats when wanting to change the port name afterwards.

  Returns:

  A two-element tuple of a new `MidiIn` or `MidiOut` instance and the name of the MIDI port which was opened.

  Exceptions:

  `KeyboardInterrupt, EOFError`

    Raised when the user presses Control-C or Control-D during a console prompt.

  `rtmidi.SystemError`

    Raised when RtMidi backend initialization fails.

  `rtmidi.NoDevicesError`

    Raised when no MIDI input or output ports (depending on what was requested) are available.

  `rtmidi.InvalidPortError`

    Raised when an invalid port number or name is passed and `interactive` is `False`.

## rtmidi.version module

## Module contents

A Python binding for the RtMidi C++ library implemented using Cython.

### Overview

RtMidi is a set of C++ classes which provides a concise and simple, cross-platform API (Application Programming Interface) for realtime MIDI input / output across Linux (ALSA & JACK), macOS / OS X (CoreMIDI & JACK), and Windows (MultiMedia System) operating systems.

python-rtmidi is a Python binding for RtMidi implemented using Cython and provides a thin wrapper around the RtMidi C++ interface. The API is basically the same as the C++ one but with the naming scheme of classes, methods and parameters adapted to the Python PEP-8 conventions and requirements of the Python package naming structure. python-rtmidi supports Python 3 (3.6, 3.7, 3.8, and 3.9).

### Usage example

Here’s a short example of how to use python-rtmidi to open the first available MIDI output port and send a middle C note on MIDI channel 1:

    import time
    import rtmidi

    midiout = rtmidi.MidiOut()
    available_ports = midiout.get_ports()

    if available_ports:
        midiout.open_port(0)
    else:
        midiout.open_virtual_port("My virtual output")

    with midiout:
        note_on = [0x90, 60, 112] # channel 1, middle C, velocity 112
        note_off = [0x80, 60, 0]
        midiout.send_message(note_on)
        time.sleep(0.5)
        midiout.send_message(note_off)
        time.sleep(0.1)

    del midiout

### Constants

#### Low-level APIs

These constants are returned by the `get_compiled_api` function and the `MidiIn.get_current_api` resp. `MidiOut.get_current_api` methods and are used to specify the low-level MIDI backend API to use when creating a `MidiIn` or `MidiOut` instance.

`API_UNSPECIFIED`

  Use first compiled-in API, which has any input resp. output ports

`API_MACOSX_CORE`

  macOS (OS X) CoreMIDI

`API_LINUX_ALSA`

  Linux ALSA

`API_UNIX_JACK`

  Jack Client

`API_WINDOWS_MM`

  Windows MultiMedia

`API_RTMIDI_DUMMY`

  RtMidi Dummy API (used when no suitable API was found)

`API_RWEB_MIDI`

  W3C Web MIDI API

#### Error types

These constants are passed as the first argument to an error handler function registered with `set_error_callback` method of a `MidiIn` or `MidiOut` instance. For the meaning of each value, please see the RtMidi API reference.

- `ERRORTYPE_DEBUG_WARNING`

- `ERRORTYPE_DRIVER_ERROR`

- `ERRORTYPE_INVALID_DEVICE`

- `ERRORTYPE_INVALID_PARAMETER`

- `ERRORTYPE_INVALID_USE`

- `ERRORTYPE_MEMORY_ERROR`

- `ERRORTYPE_NO_DEVICES_FOUND`

- `ERRORTYPE_SYSTEM_ERROR`

- `ERRORTYPE_THREAD_ERROR`

- `ERRORTYPE_UNSPECIFIED`

- `ERRORTYPE_WARNING`

### Functions

rtmidi.get_api_name(api)

  Return the name of a specified MIDI API.

  This returns a short lower-case name used for identification purposes.

  The `api` should be given as the one of `API_*` constants in the module namespace, e.g.:

      name = rtmidi.get_api_name(rtmidi.API_UNIX_JACK)

  If the API is unknown, this function will return the empty string.

rtmidi.get_api_display_name(api)

  Return the display name of a specified MIDI API.

  This returns a long name used for display purposes.

  The `api` should be given as the one of `API_*` constants in the module namespace, e.g.:

      display_name = rtmidi.get_api_display_name(rtmidi.API_UNIX_JACK)

  If the API is unknown, this function will return the empty string.

rtmidi.get_compiled_api()

  Return a list of low-level MIDI backend APIs this module supports.

  Check for support for a particular API by using the `API_*` constants in the module namespace, i.e.:

      if rtmidi.API_UNIX_JACK in rtmidi.get_compiled_api():
          ...

rtmidi.get_compiled_api_by_name(name)

  Return the compiled MIDI API having the given name.

  A case insensitive comparison will check the specified name against the list of compiled APIs, and return the one which matches. On failure, the function returns `API_UNSPECIFIED`.

rtmidi.get_rtmidi_version()

  Return the version string of the wrapped RtMidi library.

### Exceptions

class rtmidi.RtMidiError(msg, type=None)

  Base general RtMidi exception.

  All other exceptions in this module derive form this exception.

  Instances have a `type` attribute that maps to one of the `ERRORTYPE_*` constants.

class rtmidi.InvalidPortError(msg, type=None)

  Raised when an invalid port number is used.

  Also derives from `ValueError`.

class rtmidi.InvalidUseError(msg, type=None)

  Raised when an method call is not allowed in the current state.

  Also derives from `RuntimeError`.

class rtmidi.MemoryAllocationError(msg, type=None)

  Raised if a memory allocation failed on the C++ level.

  Also derives from `MemoryError`.

class rtmidi.NoDevicesError(msg, type=None)

  Raised if no MIDI devices are found.

  Derives from `rtmidi.SystemError`.

class rtmidi.SystemError(msg, type=None)

  Raised if an error happened at the MIDI driver or OS level.

  Also derives from `OSError`.

class rtmidi.UnsupportedOperationError(msg, type=None)

  Raised if a method is not supported by the low-level API.

  Also derives from `RuntimeError`.

### Classes

class rtmidi.MidiIn

  Midi input client interface.

  `rtmidi.MidiIn(rtapi=API_UNSPECIFIED, name="RtMidi Client", queue_size_limit=1024)`

  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 unless you either use the `set_client_name` method, or 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).

  Exceptions:

  `SystemError`

    Raised when the RtMidi backend initialization fails. The execption message should have more information on the cause of the error.

  `TypeError`

    Raised when an incompatible value type is passed for a parameter.

  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 and reinstates the default error handler.

  close_port(self)
  delete(self)

    De-allocate pointer to C++ class instance.

    Warning

    the instance must not be used anymore after calling this method, otherwise the program will crash with a segmentation fault!

    The reason this potentially dangerous method exists is that in some cases it is desirable to destroy the internal `RtMidiIn` C++ class instance with immediate effect, thereby closing the backend MIDI API client and all the ports it opened. By merely using `del` on the `rtmidi.MidiIn` Python instance, the destruction of the C++ instance may be delayed for an arbitrary amount of time, until the Python garbage collector cleans up the 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.:

        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=u'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_sense = 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 `InvalidUseError` 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, use the `set_port_name` method where supported, or delete its instance, create a new one and open the port again giving a different name.

    Exceptions:

    `InvalidPortError`

      Raised when an invalid port number is passed.

    `InvalidUseError`

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

    `TypeError`

      Raised when an incompatible value type is passed for the `port` or `name` parameter.

  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 `InvalidUseError` 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, use the `set_port_name` method where supported, or 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:

    `InvalidUseError`

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

    `TypeError`

      Raised when an incompatible value type is passed for the `name` parameter.

    `UnsupportedOperationError`

      Raised when trying to open a virtual MIDI port with the Windows MultiMedia API, which doesn’t support virtual ports.

  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. The second argument is value of the `data` argument passed to `set_callback` when the callback is registered. The value of `data` can be any Python object. It can be used inside the callback function to access data that would not be in scope otherwise.

    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_client_name(self, name)

    Set the name of the MIDI client.

    Names with non-ASCII characters in them have to be passed as unicode or UTF-8 encoded strings in Python 2.

    Currently only supported by the ALSA API backend.

    Exceptions:

    `TypeError`

      Raised when an incompatible value type is passed for the `name` parameter.

    `UnsupportedOperationError`

      Raised when trying the backend API does not support changing the client name.

  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.

    Note

    A default error handler function is registered on new instances of `MidiIn` and `MidiOut`, which turns errors reported by the C++ layer into custom exceptions derived from `RtMidiError`.

    If you replace this default error handler, be aware that the exception handling in your code probably needs to be adapted.

    Registering an error callback function replaces any previously registered error callback, including the above mentioned default error handler.

  set_port_name(self, name)

    Set the name of the currently opened port.

    Names with non-ASCII characters in them have to be passed as unicode or UTF-8 encoded strings in Python 2.

    Currently only supported by the ALSA and JACK API backends.

    Exceptions:

    `InvalidUseError`

      Raised when no port is currently opened.

    `TypeError`

      Raised when an incompatible value type is passed for the `name` parameter.

    `UnsupportedOperationError`

      Raised when trying the backend API does not support changing the port name.

class rtmidi.MidiOut

  Midi output client interface.

  `rtmidi.MidiOut(rtapi=API_UNSPECIFIED, name="RtMidi Client")`

  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 backend APIs (e.g. ALSA), the client name is set by the first `MidiIn` or `MidiOut` created by your program and does not change unless you either use the `set_client_name` method, or until all `MidiIn` and `MidiOut` instances are deleted and then a new one is created.

  Exceptions:

  `SystemError`

    Raised when the RtMidi backend initialization fails. The execption message should have more information on the cause of the error.

  `TypeError`

    Raised when an incompatible value type is passed for a parameter.

  cancel_error_callback(self)

    Remove the registered callback function for errors.

    This can be safely called even when no callback function has been registered and reinstates the default error handler.

  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.

  delete(self)

    De-allocate pointer to C++ class instance.

    Warning

    the instance must not be used anymore after calling this method, otherwise the program will crash with a segmentation fault!

    The reason this potentially dangerous method exists is that in some cases it is desirable to destroy the internal `RtMidiOut` C++ class instance with immediate effect, thereby closing the backend MIDI API client and all the ports it opened. By merely using `del` on the `rtmidi.MidiOut` Python instance, the destruction of the C++ instance may be delayed for an arbitrary amount of time, until the Python garbage collector cleans up the 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=u'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 `InvalidUseError` 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, use the `set_port_name` method where supported, or delete its instance, create a new one and open the port again giving a different name.

    Exceptions:

    `InvalidPortError`

      Raised when an invalid port number is passed.

    `InvalidUseError`

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

    `TypeError`

      Raised when an incompatible value type is passed for the `port` or `name` parameter.

  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 `InvalidUseError` 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, use the `set_port_name` method where supported, or 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:

    `InvalidUseError`

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

    `TypeError`

      Raised when an incompatible value type is passed for the `name` parameter.

    `UnsupportedOperationError`

      Raised when trying to open a virtual MIDI port with the Windows MultiMedia API, which doesn’t support virtual ports.

  send_message(self, message)

    Send a MIDI message to the output port.

    The message must be passed as an iterable yielding 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 but if it is longer than 3 bytes, the value of the first byte must be a start-of-sysex status byte, i.e. 0xF0.

    Note

    with some backend APIs (notably ``WINDOWS_MM`) this function blocks until the whole message is sent. While sending the message the global interpreter lock is released, so multiple Python threads can send messages using different MidiOut instances concurrently.

    Exceptions:

    `ValueError`

      Raised if `message` argument is empty or more than 3 bytes long and not a SysEx message.

  set_client_name(self, name)

    Set the name of the MIDI client.

    Names with non-ASCII characters in them have to be passed as unicode or UTF-8 encoded strings in Python 2.

    Currently only supported by the ALSA API backend.

    Exceptions:

    `TypeError`

      Raised when an incompatible value type is passed for the `name` parameter.

    `UnsupportedOperationError`

      Raised when trying the backend API does not support changing the client name.

  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.

    Note

    A default error handler function is registered on new instances of `MidiIn` and `MidiOut`, which turns errors reported by the C++ layer into custom exceptions derived from `RtMidiError`.

    If you replace this default error handler, be aware that the exception handling in your code probably needs to be adapted.

    Registering an error callback function replaces any previously registered error callback, including the above mentioned default error handler.

  set_port_name(self, name)

    Set the name of the currently opened port.

    Names with non-ASCII characters in them have to be passed as unicode or UTF-8 encoded strings in Python 2.

    Currently only supported by the ALSA and JACK API backends.

    Exceptions:

    `InvalidUseError`

      Raised when no port is currently opened.

    `TypeError`

      Raised when an incompatible value type is passed for the `name` parameter.

    `UnsupportedOperationError`

      Raised when trying the backend API does not support changing the port name.