API¶
Python bindings for the RtMidi C++ library using nanobind, inspired by python-rtmidi.
- class MidiBase(rt_midi: R)¶
Bases:
Generic[R]Base class for MIDI input and output clients.
- __enter__() Self¶
Support the context manager protocol.
>>> from supriya_midi import MidiOut >>> >>> with MidiOut().open_port(0) as midi_out: ... midi_out.send_message([0x90, 48, 100]) ...- Returns:
This MIDI client instance.
- cancel_error_callback() None¶
Cancel the current error callback function and replace it with the default error callback.
- close_port() None¶
Close any MIDI port opened via
open_port.Note
If a virtual port was opened, the MIDI client instance must be deleted to close it.
- delete() None¶
Immediately delete this client’s C++ backend.
When deleting the client (or simply losing a reference to it), Python’s garbage collector may delay deleting the underlying C++ backend for an arbitrary amount of time. Manually deleting ensures the backend is freed exactly when you desire it to be freed. This can be especially useful when virtual ports have been opened, as they can only be closed by deleting the backend.
Warning
The client must not be used once deleted for risk of segmentation fault.
- get_port_count() int¶
Get the number of available MIDI input or output ports.
- Returns:
The port count
-
get_port_name(port_number: int =
0) str¶ Get the name of the MIDI input or output port at index
port_number.- Parameters:
- port_number: int =
0¶ The index of the port to describe
- port_number: int =
- Returns:
The port name
- get_ports() list[str]¶
Get a list of available MIDI input or output port names.
- Returns:
A list of available port names
- property is_deleted : bool¶
True if the client’s backend has been deleted.
- property is_port_open : bool¶
True if the client’s has a real or virtual port open.
-
open_port(port_number: int =
0, port_name: str ='RtMidi') Self¶ Open a MIDI input or output port with the given
port_number.
-
open_virtual_port(port_name: str =
'RtMidi') Self¶ Open a virtual MIDI input or output port.
Note
Not supported by the Windows backend API.
- Parameters:
- port_name: str =
'RtMidi'¶ An optional port name to apply when opening a port for the first time
- port_name: str =
- Returns:
This MIDI client, to facilitate chaining when entering a context
- property port_number : int | None¶
The client’s current port number (or
-1if a virtual port is open) otherwiseNone.
- set_client_name(client_name: str) None¶
Set the MIDI client name.
Note
Only supported by the ALSA backend API.
- Parameters:
- client_name: str¶
The client name
-
set_error_callback(callback: Callable[[RtMidiErrorType, str, Any], None], data: Any =
None) None¶ Register a callback callable for backend API errors.
Error callbacks fire when the C++ backend raises errors, e.g. when opening ports that don’t exist. Error callbacks may raise errors.
Note
MIDI clients are instantiated with a default error callback.
Note
Only one callback may be registered at a time. Registering a new callback replaces any previously registered callback.
- Parameters:
- callback: Callable[[RtMidiErrorType, str, Any], None]¶
The error callback callable
- data: Any =
None¶ Optional additional data to pass as the third argument to the callback when invoked
-
class MidiIn(api: RtMidiAPI =
RtMidiAPI.UNSPECIFIED, client_name: str ='RtMidi Input Client', queue_size_limit: int =1024)¶ Bases:
MidiBase[RtMidiIn]A MIDI input client.
- Parameters:
- cancel_callback() None¶
Remove any registered MIDI message callback.
- get_message() tuple[list[int], float]¶
Poll for MIDI messages.
- Returns:
Pair of the MIDI message and delta timestamp, or
Noneif no message available
-
ignore_types(sysex: bool =
True, timing: bool =True, active_sense: bool =True) None¶ Enable or disable filtering of specific types of MIDI messages.
System Exclusive (sysex), MIDI clock (timing) and Active Sensing messages are ignored by default because they can quickly fill up input buffers. To enable receiving them, set their corresponding flags to
False.
-
set_buffer_size(size: int =
1024, count: int =4) None¶ Set the size and count of the MIDI input buffer(s).
-
class MidiOut(api: RtMidiAPI =
RtMidiAPI.UNSPECIFIED, client_name: str ='RtMidi Output Client')¶ Bases:
MidiBase[RtMidiOut]A MIDI output client.
- Parameters:
- send_message(message: Iterable[int]) None¶
Send a MIDI message to the client’s output port.
No validation is performed on the message except that if its longer than 3 byes (the standard MIDI message length), the first byte must be a start-of-sysex status byte, 0xF0.
- Parameters:
- message: Iterable[int]¶
The MIDI message to send
- get_compiled_api() list[RtMidiAPI]¶
Get the backend APIs supported by this module.
- Returns:
A list of supported backend APIs
- get_compiled_api_by_name(name: str) RtMidiAPI¶
Get a supported backend API by case-insensitive name match.
- Parameters:
- name: str¶
The backend API name
- Returns:
The matching backend API or UNSPECIFIED
- get_rtmidi_version() str¶
Get the version of RtMidi compiled with this library.
- Returns:
The RtMidi version string
- list_ports() list[str]¶
Get a list of available MIDI input or output port names.
- Returns:
A list of available port names
-
exception RtMidiError(message: str, error_type: RtMidiErrorType =
RtMidiErrorType.UNSPECIFIED)¶ An RtMidi error.