0
# python-rtmidi
1

2
A Python binding for the RtMidi C++ library providing cross-platform realtime MIDI input/output functionality. Supports Linux (ALSA & JACK), macOS (CoreMIDI & JACK), and Windows (MultiMedia System) with a thin Cython wrapper around the RtMidi C++ interface, adapted to Python PEP-8 conventions.
3

4
## Package Information
5

6
- **Package Name**: python-rtmidi
7
- **Language**: Python (with Cython extensions)
8
- **Installation**: `pip install python-rtmidi`
9
- **Python Support**: 3.8+
10
- **Platforms**: Linux, macOS, Windows
11

12
## Core Imports
13

14
```python
15
import rtmidi
16
```
17

18
Sub-modules:
19

20
```python
21
import rtmidi.midiconstants
22
import rtmidi.midiutil
23
```
24

25
## Basic Usage
26

27
```python
28
import time
29
import rtmidi
30

31
# Create MIDI output instance
32
midiout = rtmidi.MidiOut()
33
available_ports = midiout.get_ports()
34

35
if available_ports:
36
    midiout.open_port(0)
37
else:
38
    midiout.open_virtual_port("My virtual output")
39

40
# Send MIDI messages using context manager
41
with midiout:
42
    note_on = [0x90, 60, 112]  # channel 1, middle C, velocity 112
43
    note_off = [0x80, 60, 0]
44
    midiout.send_message(note_on)
45
    time.sleep(0.5)
46
    midiout.send_message(note_off)
47
    time.sleep(0.1)
48

49
del midiout
50
```
51

52
## Architecture
53

54
python-rtmidi provides a thin wrapper around RtMidi's C++ classes:
55

56
- **MidiIn/MidiOut**: Core MIDI I/O classes for receiving and sending MIDI data
57
- **API Backend Selection**: Support for multiple low-level MIDI APIs per platform
58
- **Virtual Port Support**: Create virtual MIDI ports (except Windows MM API)
59
- **Error Handling**: Custom exception hierarchy for different error conditions
60
- **Context Manager Support**: Automatic resource cleanup with `with` statements
61

62
## Capabilities
63

64
### Core MIDI I/O Classes
65

66
Primary interfaces for MIDI input and output operations, including port management, message handling, callback registration, and error handling.
67

68
```python { .api }
69
class MidiIn:
70
    def __init__(self, rtapi=API_UNSPECIFIED, name="RtMidi Client", queue_size_limit=1024): ...
71
    def get_current_api(self): ...
72
    def get_port_count(self): ...
73
    def get_ports(self, encoding='auto'): ...
74
    def open_port(self, port=0, name=None): ...
75
    def open_virtual_port(self, name=None): ...
76
    def close_port(self): ...
77
    def get_message(self): ...
78
    def set_callback(self, func, data=None): ...
79

80
class MidiOut:
81
    def __init__(self, rtapi=API_UNSPECIFIED, name="RtMidi Client"): ...
82
    def get_current_api(self): ...
83
    def get_port_count(self): ...
84
    def get_ports(self, encoding='auto'): ...
85
    def open_port(self, port=0, name=None): ...
86
    def open_virtual_port(self, name=None): ...
87
    def close_port(self): ...
88
    def send_message(self, message): ...
89
```
90

91
[Core MIDI I/O](./midi-io.md)
92

93
### MIDI Constants and Definitions
94

95
Comprehensive collection of MIDI message types, controller numbers, system messages, and helper functions for MIDI protocol implementation.
96

97
```python { .api }
98
# MIDI Channel Events (from rtmidi.midiconstants)
99
NOTE_OFF = 0x80
100
NOTE_ON = 0x90
101
CONTROLLER_CHANGE = 0xB0
102
PROGRAM_CHANGE = 0xC0
103
PITCH_BEND = 0xE0
104

105
# Controller Numbers
106
MODULATION = 0x01
107
VOLUME = 0x07
108
PAN = 0x0A
109
SUSTAIN = 0x40
110

111
# System Messages
112
SYSTEM_EXCLUSIVE = 0xF0
113
TIMING_CLOCK = 0xF8
114
ACTIVE_SENSING = 0xFE
115

116
def is_status(byte): ...
117
```
118

119
[MIDI Constants](./midi-constants.md)
120

121
### Utility Functions
122

123
Helper functions for MIDI port management, API selection, and interactive port opening with support for environment-based configuration.
124

125
```python { .api }
126
def get_api_from_environment(api=rtmidi.API_UNSPECIFIED): ...
127
def list_input_ports(api=rtmidi.API_UNSPECIFIED): ...
128
def list_output_ports(api=rtmidi.API_UNSPECIFIED): ...
129
def open_midiinput(port=None, api=rtmidi.API_UNSPECIFIED, 
130
                   use_virtual=False, interactive=True, 
131
                   client_name=None, port_name=None): ...
132
def open_midioutput(port=None, api=rtmidi.API_UNSPECIFIED, 
133
                    use_virtual=False, interactive=True, 
134
                    client_name=None, port_name=None): ...
135
```
136

137
[MIDI Utilities](./midi-utilities.md)
138

139
## Module Functions and Constants
140

141
```python { .api }
142
# API Backend Information
143
def get_compiled_api(): ...
144
def get_api_name(api): ...
145
def get_api_display_name(api): ...
146
def get_compiled_api_by_name(name): ...
147
def get_rtmidi_version(): ...
148

149
# API Constants
150
API_UNSPECIFIED = 0
151
API_MACOSX_CORE = 1
152
API_LINUX_ALSA = 2  
153
API_UNIX_JACK = 3
154
API_WINDOWS_MM = 4
155
API_WEB_MIDI = 5
156
API_RTMIDI_DUMMY = 6
157

158
# Error Type Constants
159
ERRORTYPE_WARNING = 0
160
ERRORTYPE_DEBUG_WARNING = 1
161
ERRORTYPE_UNSPECIFIED = 2
162
ERRORTYPE_NO_DEVICES_FOUND = 3
163
ERRORTYPE_INVALID_DEVICE = 4
164
ERRORTYPE_MEMORY_ERROR = 5
165
ERRORTYPE_INVALID_PARAMETER = 6
166
ERRORTYPE_INVALID_USE = 7
167
ERRORTYPE_DRIVER_ERROR = 8
168
ERRORTYPE_SYSTEM_ERROR = 9
169
ERRORTYPE_THREAD_ERROR = 10
170
```
171

172
## Exception Hierarchy
173

174
```python { .api }
175
class RtMidiError(Exception):
176
    """
177
    Base exception for all RtMidi errors.
178
    
179
    Attributes:
180
    - type: int - Error type constant (one of ERRORTYPE_* values)
181
    """
182
    type: int
183

184
class InvalidPortError(RtMidiError, ValueError):
185
    """
186
    Invalid port number or unavailable port.
187
    
188
    Raised when:
189
    - Port number exceeds available ports
190
    - Attempting to open non-existent port
191
    - Port selection fails in non-interactive mode
192
    """
193

194
class InvalidUseError(RtMidiError, RuntimeError):
195
    """
196
    Method called in inappropriate state.
197
    
198
    Raised when:
199
    - Opening port when port already open
200
    - Calling port-specific methods when no port open
201
    - Using deleted MidiIn/MidiOut instances
202
    """
203

204
class MemoryAllocationError(RtMidiError, MemoryError):
205
    """
206
    C++ level memory allocation failure.
207
    
208
    Raised when:
209
    - Insufficient memory for MIDI operations
210
    - Internal buffer allocation fails
211
    """
212

213
class SystemError(RtMidiError, OSError):
214
    """
215
    MIDI driver or operating system error.
216
    
217
    Raised when:
218
    - MIDI backend initialization fails
219
    - Driver-level communication errors
220
    - OS-level MIDI system problems
221
    """
222

223
class NoDevicesError(SystemError):
224
    """
225
    No MIDI devices available.
226
    
227
    Raised when:
228
    - No MIDI ports found on system
229
    - All ports in use or inaccessible
230
    - MIDI subsystem unavailable
231
    """
232

233
class UnsupportedOperationError(RtMidiError, RuntimeError):
234
    """
235
    Operation not supported by current API backend.
236
    
237
    Raised when:
238
    - Virtual ports requested on Windows MM API
239
    - Client/port name changes on unsupported APIs
240
    - API-specific feature limitations
241
    """
242
```