0
# MIDI Constants
1
2
Comprehensive collection of MIDI message types, controller numbers, system messages, and helper functions for MIDI protocol implementation. Available through the `rtmidi.midiconstants` module.
3
4
## Capabilities
5
6
### MIDI Channel Events (Channel Voice Messages)
7
8
Standard MIDI messages that carry musical performance data on specific MIDI channels.
9
10
```python { .api }
11
# Channel Voice Messages
12
NOTE_OFF = 0x80 # Note Off: channel, note, velocity
13
NOTE_ON = 0x90 # Note On: channel, note, velocity
14
POLY_AFTERTOUCH = 0xA0 # Polyphonic Aftertouch: channel, note, pressure
15
POLYPHONIC_PRESSURE = 0xA0 # Alias for POLY_AFTERTOUCH
16
POLY_PRESSURE = 0xA0 # Alias for POLY_AFTERTOUCH
17
CONTROLLER_CHANGE = 0xB0 # Control Change: channel, controller, value
18
CONTROL_CHANGE = 0xB0 # Alias for CONTROLLER_CHANGE
19
PROGRAM_CHANGE = 0xC0 # Program Change: channel, program
20
CHANNEL_AFTERTOUCH = 0xD0 # Channel Aftertouch: channel, pressure
21
CHANNEL_PRESSURE = 0xD0 # Alias for CHANNEL_AFTERTOUCH
22
MONO_PRESSURE = 0xD0 # Alias for CHANNEL_AFTERTOUCH
23
PITCH_BEND = 0xE0 # Pitch Bend: channel, value_low, value_high
24
```
25
26
### Continuous Controller Numbers (MSB)
27
28
High-resolution continuous controllers (Most Significant Byte) for precise parameter control.
29
30
```python { .api }
31
# High Resolution Controllers (MSB)
32
BANK_SELECT = 0x00 # Bank Select MSB
33
BANK_SELECT_MSB = 0x00 # Alias for BANK_SELECT
34
MODULATION = 0x01 # Modulation Wheel MSB
35
MODULATION_WHEEL = 0x01 # Alias for MODULATION
36
MODULATION_WHEEL_MSB = 0x01 # Alias for MODULATION
37
BREATH_CONTROLLER = 0x02 # Breath Controller MSB
38
BREATH_CONTROLLER_MSB = 0x02 # Alias for BREATH_CONTROLLER
39
FOOT_CONTROLLER = 0x04 # Foot Controller MSB
40
FOOT_CONTROLLER_MSB = 0x04 # Alias for FOOT_CONTROLLER
41
PORTAMENTO_TIME = 0x05 # Portamento Time MSB
42
PORTAMENTO_TIME_MSB = 0x05 # Alias for PORTAMENTO_TIME
43
DATA_ENTRY = 0x06 # Data Entry MSB
44
DATA_ENTRY_MSB = 0x06 # Alias for DATA_ENTRY
45
VOLUME = 0x07 # Channel Volume MSB
46
CHANNEL_VOLUME = 0x07 # Alias for VOLUME
47
CHANNEL_VOLUME_MSB = 0x07 # Alias for VOLUME
48
BALANCE = 0x08 # Balance MSB
49
BALANCE_MSB = 0x08 # Alias for BALANCE
50
PAN = 0x0A # Pan MSB
51
PAN_MSB = 0x0A # Alias for PAN
52
EXPRESSION = 0x0B # Expression Controller MSB
53
EXPRESSION_CONTROLLER = 0x0B # Alias for EXPRESSION
54
EXPRESSION_CONTROLLER_MSB = 0x0B # Alias for EXPRESSION
55
EFFECT_CONTROL_1 = 0x0C # Effect Control 1 MSB
56
EFFECT_CONTROL_1_MSB = 0x0C # Alias for EFFECT_CONTROL_1
57
EFFECT_CONTROL_2 = 0x0D # Effect Control 2 MSB
58
EFFECT_CONTROL_2_MSB = 0x0D # Alias for EFFECT_CONTROL_2
59
GENERAL_PURPOSE_CONTROLLER_1 = 0x10 # General Purpose Controller 1 MSB
60
GENERAL_PURPOSE_CONTROLLER_1_MSB = 0x10 # Alias
61
GENERAL_PURPOSE_CONTROLLER_2 = 0x11 # General Purpose Controller 2 MSB
62
GENERAL_PURPOSE_CONTROLLER_2_MSB = 0x11 # Alias
63
GENERAL_PURPOSE_CONTROLLER_3 = 0x12 # General Purpose Controller 3 MSB
64
GENERAL_PURPOSE_CONTROLLER_3_MSB = 0x12 # Alias
65
GENERAL_PURPOSE_CONTROLLER_4 = 0x13 # General Purpose Controller 4 MSB
66
GENERAL_PURPOSE_CONTROLLER_4_MSB = 0x13 # Alias
67
```
68
69
### Continuous Controller Numbers (LSB)
70
71
High-resolution continuous controllers (Least Significant Byte) for fine control adjustments.
72
73
```python { .api }
74
# High Resolution Controllers (LSB)
75
BANK_SELECT_LSB = 0x20 # Bank Select LSB
76
MODULATION_LSB = 0x21 # Modulation Wheel LSB
77
MODULATION_WHEEL_LSB = 0x21 # Alias for MODULATION_LSB
78
BREATH_CONTROLLER_LSB = 0x22 # Breath Controller LSB
79
FOOT_CONTROLLER_LSB = 0x24 # Foot Controller LSB
80
PORTAMENTO_TIME_LSB = 0x25 # Portamento Time LSB
81
DATA_ENTRY_LSB = 0x26 # Data Entry LSB
82
VOLUME_LSB = 0x27 # Channel Volume LSB
83
CHANNEL_VOLUME_LSB = 0x27 # Alias for VOLUME_LSB
84
BALANCE_LSB = 0x28 # Balance LSB
85
PAN_LSB = 0x2A # Pan LSB
86
EXPRESSION_LSB = 0x2B # Expression Controller LSB
87
EXPRESSION_CONTROLLER_LSB = 0x2B # Alias for EXPRESSION_LSB
88
EFFECT_CONTROL_1_LSB = 0x2C # Effect Control 1 LSB
89
EFFECT_CONTROL_2_LSB = 0x2D # Effect Control 2 LSB
90
GENERAL_PURPOSE_CONTROLLER_1_LSB = 0x30 # General Purpose Controller 1 LSB
91
GENERAL_PURPOSE_CONTROLLER_2_LSB = 0x31 # General Purpose Controller 2 LSB
92
GENERAL_PURPOSE_CONTROLLER_3_LSB = 0x32 # General Purpose Controller 3 LSB
93
GENERAL_PURPOSE_CONTROLLER_4_LSB = 0x33 # General Purpose Controller 4 LSB
94
```
95
96
### Switch Controllers
97
98
Binary on/off controllers (off: value ≤ 63, on: value ≥ 64).
99
100
```python { .api }
101
# Switch Controllers (On/Off)
102
SUSTAIN = 0x40 # Sustain Pedal
103
SUSTAIN_ONOFF = 0x40 # Alias for SUSTAIN
104
PORTAMENTO = 0x41 # Portamento On/Off
105
PORTAMENTO_ONOFF = 0x41 # Alias for PORTAMENTO
106
SOSTENUTO = 0x42 # Sostenuto On/Off
107
SOSTENUTO_ONOFF = 0x42 # Alias for SOSTENUTO
108
SOFT_PEDAL = 0x43 # Soft Pedal On/Off
109
SOFT_PEDAL_ONOFF = 0x43 # Alias for SOFT_PEDAL
110
LEGATO = 0x44 # Legato On/Off
111
LEGATO_ONOFF = 0x44 # Alias for LEGATO
112
HOLD_2 = 0x45 # Hold 2 On/Off
113
HOLD_2_ONOFF = 0x45 # Alias for HOLD_2
114
```
115
116
### Sound Controllers
117
118
Low-resolution controllers for sound parameter adjustment.
119
120
```python { .api }
121
# Sound Controllers
122
SOUND_CONTROLLER_1 = 0x46 # Sound Variation / FX: Exciter On/Off
123
SOUND_CONTROLLER_2 = 0x47 # Harmonic Content / FX: Compressor On/Off
124
SOUND_CONTROLLER_3 = 0x48 # Release Time / FX: Distortion On/Off
125
SOUND_CONTROLLER_4 = 0x49 # Attack Time / FX: EQ On/Off
126
SOUND_CONTROLLER_5 = 0x4A # Brightness / FX: Expander On/Off
127
SOUND_CONTROLLER_6 = 0x4B # Decay Time / FX: Reverb On/Off
128
SOUND_CONTROLLER_7 = 0x4C # Vibrato Rate / FX: Delay On/Off
129
SOUND_CONTROLLER_8 = 0x4D # Vibrato Depth / FX: Pitch Transpose On/Off
130
SOUND_CONTROLLER_9 = 0x4E # Vibrato Delay / FX: Flange/Chorus On/Off
131
SOUND_CONTROLLER_10 = 0x4F # Undefined / FX: Special Effects On/Off
132
```
133
134
### Additional Controllers
135
136
Extended controller definitions and parameter management.
137
138
```python { .api }
139
# Additional Controllers
140
GENERAL_PURPOSE_CONTROLLER_5 = 0x50 # General Purpose Controller 5
141
GENERAL_PURPOSE_CONTROLLER_6 = 0x51 # General Purpose Controller 6
142
GENERAL_PURPOSE_CONTROLLER_7 = 0x52 # General Purpose Controller 7
143
GENERAL_PURPOSE_CONTROLLER_8 = 0x53 # General Purpose Controller 8
144
PORTAMENTO_CONTROL = 0x54 # Portamento Control (source note number)
145
PTC = 0x54 # Alias for PORTAMENTO_CONTROL
146
HIGH_RESOLUTION_VELOCITY_PREFIX = 0x58 # High Resolution Velocity Prefix
147
148
# Effects Depth Controllers
149
EFFECTS_1 = 0x5B # Reverb Send Level (formerly Ext. Effects Depth)
150
EFFECTS_1_DEPTH = 0x5B # Alias for EFFECTS_1
151
EFFECTS_2 = 0x5C # Formerly Tremolo Depth
152
EFFECTS_2_DEPTH = 0x5C # Alias for EFFECTS_2
153
EFFECTS_3 = 0x5D # Chorus Send Level (formerly Chorus Depth)
154
EFFECTS_3_DEPTH = 0x5D # Alias for EFFECTS_3
155
EFFECTS_4 = 0x5E # Formerly Celeste (Detune) Depth
156
EFFECTS_4_DEPTH = 0x5E # Alias for EFFECTS_4
157
EFFECTS_5 = 0x5F # Formerly Phaser Depth
158
EFFECTS_5_DEPTH = 0x5F # Alias for EFFECTS_5
159
160
# Parameter Control
161
DATA_INCREMENT = 0x60 # Data Increment (value should be 0)
162
DATA_DECREMENT = 0x61 # Data Decrement (value should be 0)
163
NRPN_LSB = 0x62 # Non-Registered Parameter Number LSB
164
NON_REGISTERED_PARAMETER_NUMBER_LSB = 0x62 # Alias for NRPN_LSB
165
NRPN_MSB = 0x63 # Non-Registered Parameter Number MSB
166
NON_REGISTERED_PARAMETER_NUMBER_MSB = 0x63 # Alias for NRPN_MSB
167
RPN_LSB = 0x64 # Registered Parameter Number LSB
168
REGISTERED_PARAMETER_NUMBER_LSB = 0x64 # Alias for RPN_LSB
169
RPN_MSB = 0x65 # Registered Parameter Number MSB
170
REGISTERED_PARAMETER_NUMBER_MSB = 0x65 # Alias for RPN_MSB
171
```
172
173
### Channel Mode Messages
174
175
Channel mode control messages for voice allocation and system behavior.
176
177
```python { .api }
178
# Channel Mode Messages
179
ALL_SOUND_OFF = 0x78 # All Sound Off (value should be 0)
180
RESET_ALL_CONTROLLERS = 0x79 # Reset All Controllers (value should be 0)
181
LOCAL_CONTROL = 0x7A # Local Control (0=off, 127=on)
182
LOCAL_CONTROL_ONOFF = 0x7A # Alias for LOCAL_CONTROL
183
ALL_NOTES_OFF = 0x7B # All Notes Off (value should be 0)
184
OMNI_MODE_OFF = 0x7C # Omni Mode Off (causes All Notes Off)
185
OMNI_MODE_ON = 0x7D # Omni Mode On (causes All Notes Off)
186
MONO_MODE_ON = 0x7E # Mono Mode On/Poly Off (causes All Notes Off)
187
POLY_MODE_ON = 0x7F # Poly Mode On/Mono Off (causes All Notes Off)
188
```
189
190
### System Common Messages
191
192
System-wide messages for all MIDI channels and devices.
193
194
```python { .api }
195
# System Common Messages
196
SYSTEM_EXCLUSIVE = 0xF0 # System Exclusive start
197
MIDI_TIME_CODE = 0xF1 # MIDI Time Code Quarter Frame
198
MTC = 0xF1 # Alias for MIDI_TIME_CODE
199
SONG_POSITION_POINTER = 0xF2 # Song Position Pointer
200
SONG_SELECT = 0xF3 # Song Select
201
TUNING_REQUEST = 0xF6 # Tuning Request
202
TUNE_REQUEST = 0xF6 # Alias for TUNING_REQUEST
203
END_OF_EXCLUSIVE = 0xF7 # End of System Exclusive
204
```
205
206
### MIDI File Meta-Events
207
208
Meta-events used in Standard MIDI File format.
209
210
```python { .api }
211
# MIDI File Meta-Events
212
SEQUENCE_NUMBER = 0x00 # Sequence Number
213
TEXT = 0x01 # Text Event
214
COPYRIGHT = 0x02 # Copyright Notice
215
SEQUENCE_NAME = 0x03 # Sequence/Track Name
216
INSTRUMENT_NAME = 0x04 # Instrument Name
217
LYRIC = 0x05 # Lyric
218
MARKER = 0x06 # Marker
219
CUEPOINT = 0x07 # Cue Point
220
PROGRAM_NAME = 0x08 # Program Name
221
DEVICE_NAME = 0x09 # Device Name
222
MIDI_CH_PREFIX = 0x20 # MIDI Channel Prefix (deprecated)
223
MIDI_PORT = 0x21 # MIDI Port (deprecated but still used)
224
END_OF_TRACK = 0x2F # End of Track
225
TEMPO = 0x51 # Set Tempo (microseconds per quarter note)
226
SMTP_OFFSET = 0x54 # SMPTE Offset
227
TIME_SIGNATURE = 0x58 # Time Signature
228
KEY_SIGNATURE = 0x59 # Key Signature
229
SPECIFIC = 0x7F # Sequencer Specific
230
```
231
232
### System Realtime Messages
233
234
Real-time messages for MIDI clock synchronization and transport control.
235
236
```python { .api }
237
# System Realtime Messages
238
TIMING_CLOCK = 0xF8 # Timing Clock (24 per quarter note)
239
SONG_START = 0xFA # Start playback from beginning
240
SONG_CONTINUE = 0xFB # Continue playback from current position
241
SONG_STOP = 0xFC # Stop playback
242
ACTIVE_SENSING = 0xFE # Active Sensing (sent every 300ms max)
243
SYSTEM_RESET = 0xFF # System Reset
244
```
245
246
### Additional Constants
247
248
Meta-events, file format constants, and timecode definitions.
249
250
```python { .api }
251
# Meta Event Constants
252
META_EVENT = 0xFF # Meta Event (MIDI files only)
253
ESCAPE_SEQUENCE = 0xF7 # Escape Sequence
254
255
# MIDI File Format Constants
256
FILE_HEADER = 'MThd' # MIDI file header identifier
257
TRACK_HEADER = 'MTrk' # Track chunk header identifier
258
259
# Timecode Resolution (frames per second)
260
FPS_24 = 0xE8 # 24 fps
261
FPS_25 = 0xE7 # 25 fps
262
FPS_29 = 0xE3 # 29.97 fps (30 drop frame)
263
FPS_30 = 0xE2 # 30 fps
264
```
265
266
### Helper Functions
267
268
Utility functions for MIDI message analysis and validation.
269
270
```python { .api }
271
def is_status(byte):
272
"""
273
Check if byte is a MIDI status byte.
274
275
Parameters:
276
- byte: Integer byte value (0-255)
277
278
Returns:
279
- bool: True if byte has bit 7 set (0x80 & byte == 0x80)
280
"""
281
```
282
283
## Usage Examples
284
285
### Basic MIDI Message Construction
286
287
```python
288
import rtmidi.midiconstants as mc
289
290
# Create common MIDI messages
291
note_on = [mc.NOTE_ON | 0, 60, 100] # Channel 1, Middle C, velocity 100
292
note_off = [mc.NOTE_OFF | 0, 60, 0] # Channel 1, Middle C, velocity 0
293
294
# Control change messages
295
volume_change = [mc.CONTROLLER_CHANGE | 0, mc.VOLUME, 100]
296
pan_center = [mc.CONTROLLER_CHANGE | 0, mc.PAN, 64]
297
sustain_on = [mc.CONTROLLER_CHANGE | 0, mc.SUSTAIN, 127]
298
sustain_off = [mc.CONTROLLER_CHANGE | 0, mc.SUSTAIN, 0]
299
300
# Program change
301
piano_patch = [mc.PROGRAM_CHANGE | 0, 0] # Channel 1, patch 0
302
303
# System messages
304
sysex_msg = [mc.SYSTEM_EXCLUSIVE, 0x43, 0x12, 0x00, mc.END_OF_EXCLUSIVE]
305
```
306
307
### MIDI Message Analysis
308
309
```python
310
import rtmidi.midiconstants as mc
311
312
def analyze_midi_message(message):
313
if not message:
314
return "Empty message"
315
316
status_byte = message[0]
317
318
if not mc.is_status(status_byte):
319
return "Invalid: First byte is not a status byte"
320
321
msg_type = status_byte & 0xF0
322
channel = status_byte & 0x0F
323
324
if msg_type == mc.NOTE_ON:
325
note, velocity = message[1], message[2]
326
return f"Note On: Channel {channel+1}, Note {note}, Velocity {velocity}"
327
elif msg_type == mc.NOTE_OFF:
328
note, velocity = message[1], message[2]
329
return f"Note Off: Channel {channel+1}, Note {note}, Velocity {velocity}"
330
elif msg_type == mc.CONTROLLER_CHANGE:
331
controller, value = message[1], message[2]
332
return f"CC: Channel {channel+1}, Controller {controller}, Value {value}"
333
elif status_byte == mc.SYSTEM_EXCLUSIVE:
334
return f"SysEx: {len(message)} bytes"
335
else:
336
return f"Other message type: 0x{status_byte:02X}"
337
338
# Usage
339
message = [0x90, 60, 100] # Note On
340
print(analyze_midi_message(message)) # "Note On: Channel 1, Note 60, Velocity 100"
341
```
342
343
### Controller Value Interpretation
344
345
```python
346
import rtmidi.midiconstants as mc
347
348
def interpret_controller_value(controller, value):
349
"""Interpret controller values based on controller type."""
350
351
# Switch controllers (on/off)
352
if controller in [mc.SUSTAIN, mc.PORTAMENTO, mc.SOSTENUTO,
353
mc.SOFT_PEDAL, mc.LEGATO, mc.HOLD_2]:
354
return "On" if value >= 64 else "Off"
355
356
# Centered controllers (pan, balance)
357
elif controller in [mc.PAN, mc.BALANCE]:
358
if value == 64:
359
return "Center"
360
elif value < 64:
361
return f"Left {64-value}"
362
else:
363
return f"Right {value-64}"
364
365
# Standard 0-127 range
366
else:
367
return f"{value}/127 ({value/127*100:.1f}%)"
368
369
# Usage
370
print(interpret_controller_value(mc.SUSTAIN, 127)) # "On"
371
print(interpret_controller_value(mc.PAN, 64)) # "Center"
372
print(interpret_controller_value(mc.VOLUME, 100)) # "100/127 (78.7%)"
373
```