rtmidi package¶
Submodules¶
rtmidi.midiconstants module¶
Definitions of midi events, controller numbers and parameters.
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)[source]¶
Return RtMidi API specified in the environment if any.
If the optional api argument is
rtmidi.API_UNSPECIFIED(the default), look in the environment variableRTMIDI_APIfor the name of the RtMidi API to use. Valid names areLINUX_ALSA,UNIX_JACK,MACOSX_CORE,WINDOWS_MMandRTMIDI_DUMMY. If no valid value is found,rtmidi.API_UNSPECIFIEDwill be used.Returns a
rtmidi.API_*constant.
- rtmidi.midiutil.list_available_ports(ports=None, midiio=None)[source]¶
List MIDI ports given or available on given MIDI I/O instance.
- rtmidi.midiutil.list_input_ports(api=0)[source]¶
List available MIDI input ports.
Optionally the RtMidi API can be passed with the
apiargument. If not it will be determined via theget_api_from_environmentfunction.Exceptions:
rtmidi.SystemErrorRaised when RtMidi backend initialization fails.
- rtmidi.midiutil.list_output_ports(api=0)[source]¶
List available MIDI output ports.
Optionally the RtMidi API can be passed with the
apiargument. If not it will be determined via theget_api_from_environmentfunction.Exceptions:
rtmidi.SystemErrorRaised when RtMidi backend initialization fails.
- rtmidi.midiutil.open_midiinput(port=None, api=0, use_virtual=False, interactive=True, client_name=None, port_name=None)[source]¶
Open a MIDI port for input and return a MidiIn instance.
See the
open_midiportfunction for information on parameters and possible exceptions.
- rtmidi.midiutil.open_midioutput(port=None, api=0, use_virtual=False, interactive=True, client_name=None, port_name=None)[source]¶
Open a MIDI port for output and return a MidiOut instance.
See the
open_midiportfunction for information on parameters and possible exceptions.
- rtmidi.midiutil.open_midiport(port=None, type_='input', api=0, use_virtual=False, interactive=True, client_name=None, port_name=None)[source]¶
Open MIDI port for input or output and return MidiIn/MidiOut instance.
Arguments:
portA 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 aMidiInorMidiOutinstance will be created and returned.apiSelect the low-level MIDI API to use. Defaults to
API_UNSPECIFIED, The specified api will be passed to theget_api_from_environmentfunction and its return value will be used. If it’sAPI_UNSPECIFIEDthe first compiled-in API, which has any input resp. output ports available, will be used.use_virtualIf
portisNone, should a virtual MIDI port be opened? Defaults toFalse.interactiveIf
portisNoneor 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 (ifuse_virtualisTrue) and/or with a list of available MIDI ports and the option to choose one? Defaults toTrue.client_nameThe name of the MIDI client passed when instantiating a
MidiInorMidiOutobject.See the documentation of the constructor for these classes for the default values and caveats and OS-dependent ideosyncracies regarding the client name.
port_nameThe name of the MIDI port passed to the
open_portoropen_virtual_portmethod of the newMidiInorMidiOutinstance.See the documentation of the
open_portresp.open_virtual_portmethods for the default values and caveats when wanting to change the port name afterwards.
Returns:
A two-element tuple of a new
MidiInorMidiOutinstance and the name of the MIDI port which was opened.Exceptions:
KeyboardInterrupt, EOFErrorRaised when the user presses Control-C or Control-D during a console prompt.
rtmidi.SystemErrorRaised when RtMidi backend initialization fails.
rtmidi.NoDevicesErrorRaised when no MIDI input or output ports (depending on what was requested) are available.
rtmidi.InvalidPortErrorRaised when an invalid port number or name is passed and
interactiveisFalse.
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_UNSPECIFIEDUse first compiled-in API, which has any input resp. output ports
API_MACOSX_COREmacOS (OS X) CoreMIDI
API_LINUX_ALSALinux ALSA
API_UNIX_JACKJack Client
API_WINDOWS_MMWindows MultiMedia
API_RTMIDI_DUMMYRtMidi Dummy API (used when no suitable API was found)
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_WARNINGERRORTYPE_DRIVER_ERRORERRORTYPE_INVALID_DEVICEERRORTYPE_INVALID_PARAMETERERRORTYPE_INVALID_USEERRORTYPE_MEMORY_ERRORERRORTYPE_NO_DEVICES_FOUNDERRORTYPE_SYSTEM_ERRORERRORTYPE_THREAD_ERRORERRORTYPE_UNSPECIFIEDERRORTYPE_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
apishould be given as the one ofAPI_*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
apishould be given as the one ofAPI_*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
typeattribute that maps to one of theERRORTYPE_*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
rtapikeyword or the first positional argument, passing one of the module-levelAPI_*constants. You can get a list of compiled-in APIs with the module-levelget_compiled_apifunction. If you passAPI_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
namekeyword 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
MidiInorMidiOutcreated by your program and does not change unless you either use theset_client_namemethod, or until allMidiInandMidiOutinstances are deleted and then a new one is created.The
queue_size_limitargument specifies the size of the internal ring buffer in which incoming MIDI events are placed until retrieved via theget_messagemethod (i.e. when no callback function is registered). The default value is1024(overriding the default value100of the underlying C++ RtMidi library).Exceptions:
SystemErrorRaised when the RtMidi backend initialization fails. The execption message should have more information on the cause of the error.
TypeErrorRaised 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
RtMidiInC++ class instance with immediate effect, thereby closing the backend MIDI API client and all the ports it opened. By merely usingdelon thertmidi.MidiInPython 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_countmethod.The port name is decoded to a (unicode) string with the encoding given by
encoding. Ifencodingis"auto"(the default), then an appropriate encoding is chosen based on the system and the used backend API. IfencodingisNone, the name is returned un-decoded, i.e. as typestrin Python 2 orbytesin 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. Ifencodingis"auto"(the default), then an appropriate encoding is chosen based on the system and the used backend API. IfencodingisNone, the names are returned un-decoded, i.e. as typestrin Python 2 orbytesin 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_COUNTandRT_SYSEX_BUFFER_SIZEpreprocessor defines inRtMidi.cppand recompile.
- is_port_open(self)¶
Return
Trueif a port has been opened andFalseif not.Note
The
isPortOpenmethod of the RtMidi C++ library does not returnTruewhen 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
MidiInorMidiOutinstance. AnInvalidUseErrorexception is raised if an attempt is made to open a port on aMidiInorMidiOutinstance, which already opened a (virtual) port.You can optionally pass a name for the RtMidi port with the
namekeyword 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_namemethod where supported, or delete its instance, create a new one and open the port again giving a different name.Exceptions:
InvalidPortErrorRaised when an invalid port number is passed.
InvalidUseErrorRaised when trying to open a MIDI port when a (virtual) port has already been opened by this instance.
TypeErrorRaised when an incompatible value type is passed for the
portornameparameter.
- open_virtual_port(self, name=None)¶
Open a virtual MIDI input or output port.
Only one port can be opened per
MidiInorMidiOutinstance. AnInvalidUseErrorexception is raised if an attempt is made to open a port on aMidiInorMidiOutinstance, 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.
aconnectfor ALSA,jack_connectfor 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
namekeyword 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_namemethod 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
MidiInorMidiOutinstance.Exceptions:
InvalidUseErrorRaised when trying to open a virtual port when a (virtual) port has already been opened by this instance.
TypeErrorRaised when an incompatible value type is passed for the
nameparameter.UnsupportedOperationErrorRaised 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_messagemethod. The second argument is value of thedataargument passed toset_callbackwhen the callback is registered. The value ofdatacan 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
MidiIninstance 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:
TypeErrorRaised when an incompatible value type is passed for the
nameparameter.UnsupportedOperationErrorRaised 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 theERRORTYPE_*constants. The second argument is an error message. The third argument is the value of thedataargument passed to this function when the callback is registered.Note
A default error handler function is registered on new instances of
MidiInandMidiOut, which turns errors reported by the C++ layer into custom exceptions derived fromRtMidiError.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:
InvalidUseErrorRaised when no port is currently opened.
TypeErrorRaised when an incompatible value type is passed for the
nameparameter.UnsupportedOperationErrorRaised 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
rtapikeyword or the first positional argument, passing one of the module-levelAPI_*constants. You can get a list of compiled-in APIs with the module-levelget_compiled_apifunction. If you passAPI_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
namekeyword 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
MidiInorMidiOutcreated by your program and does not change unless you either use theset_client_namemethod, or until allMidiInandMidiOutinstances are deleted and then a new one is created.Exceptions:
SystemErrorRaised when the RtMidi backend initialization fails. The execption message should have more information on the cause of the error.
TypeErrorRaised 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 itsMidiInorMidiOutinstance.
- 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
RtMidiOutC++ class instance with immediate effect, thereby closing the backend MIDI API client and all the ports it opened. By merely usingdelon thertmidi.MidiOutPython 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_countmethod.The port name is decoded to a (unicode) string with the encoding given by
encoding. Ifencodingis"auto"(the default), then an appropriate encoding is chosen based on the system and the used backend API. IfencodingisNone, the name is returned un-decoded, i.e. as typestrin Python 2 orbytesin 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. Ifencodingis"auto"(the default), then an appropriate encoding is chosen based on the system and the used backend API. IfencodingisNone, the names are returned un-decoded, i.e. as typestrin Python 2 orbytesin Python 3.
- is_port_open(self)¶
Return
Trueif a port has been opened andFalseif not.Note
The
isPortOpenmethod of the RtMidi C++ library does not returnTruewhen 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
MidiInorMidiOutinstance. AnInvalidUseErrorexception is raised if an attempt is made to open a port on aMidiInorMidiOutinstance, which already opened a (virtual) port.You can optionally pass a name for the RtMidi port with the
namekeyword 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_namemethod where supported, or delete its instance, create a new one and open the port again giving a different name.Exceptions:
InvalidPortErrorRaised when an invalid port number is passed.
InvalidUseErrorRaised when trying to open a MIDI port when a (virtual) port has already been opened by this instance.
TypeErrorRaised when an incompatible value type is passed for the
portornameparameter.
- open_virtual_port(self, name=None)¶
Open a virtual MIDI input or output port.
Only one port can be opened per
MidiInorMidiOutinstance. AnInvalidUseErrorexception is raised if an attempt is made to open a port on aMidiInorMidiOutinstance, 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.
aconnectfor ALSA,jack_connectfor 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
namekeyword 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_namemethod 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
MidiInorMidiOutinstance.Exceptions:
InvalidUseErrorRaised when trying to open a virtual port when a (virtual) port has already been opened by this instance.
TypeErrorRaised when an incompatible value type is passed for the
nameparameter.UnsupportedOperationErrorRaised 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:
ValueErrorRaised if
messageargument 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:
TypeErrorRaised when an incompatible value type is passed for the
nameparameter.UnsupportedOperationErrorRaised 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 theERRORTYPE_*constants. The second argument is an error message. The third argument is the value of thedataargument passed to this function when the callback is registered.Note
A default error handler function is registered on new instances of
MidiInandMidiOut, which turns errors reported by the C++ layer into custom exceptions derived fromRtMidiError.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:
InvalidUseErrorRaised when no port is currently opened.
TypeErrorRaised when an incompatible value type is passed for the
nameparameter.UnsupportedOperationErrorRaised when trying the backend API does not support changing the port name.