tessl/pypi-python-rtmidi

A Python binding for the RtMidi C++ library providing cross-platform realtime MIDI input/output functionality.

—

Pending

Overview

Eval results

Files

MIDI Constants

Name: tessl/pypi-python-rtmidi
Author: tessl

Comprehensive collection of MIDI message types, controller numbers, system messages, and helper functions for MIDI protocol implementation. Available through the rtmidi.midiconstants module.

Capabilities

MIDI Channel Events (Channel Voice Messages)

Standard MIDI messages that carry musical performance data on specific MIDI channels.

# Channel Voice Messages
NOTE_OFF = 0x80              # Note Off: channel, note, velocity
NOTE_ON = 0x90               # Note On: channel, note, velocity
POLY_AFTERTOUCH = 0xA0       # Polyphonic Aftertouch: channel, note, pressure
POLYPHONIC_PRESSURE = 0xA0   # Alias for POLY_AFTERTOUCH
POLY_PRESSURE = 0xA0         # Alias for POLY_AFTERTOUCH
CONTROLLER_CHANGE = 0xB0     # Control Change: channel, controller, value
CONTROL_CHANGE = 0xB0        # Alias for CONTROLLER_CHANGE
PROGRAM_CHANGE = 0xC0        # Program Change: channel, program
CHANNEL_AFTERTOUCH = 0xD0    # Channel Aftertouch: channel, pressure
CHANNEL_PRESSURE = 0xD0      # Alias for CHANNEL_AFTERTOUCH
MONO_PRESSURE = 0xD0         # Alias for CHANNEL_AFTERTOUCH
PITCH_BEND = 0xE0            # Pitch Bend: channel, value_low, value_high

Continuous Controller Numbers (MSB)

High-resolution continuous controllers (Most Significant Byte) for precise parameter control.

# High Resolution Controllers (MSB)
BANK_SELECT = 0x00                    # Bank Select MSB
BANK_SELECT_MSB = 0x00               # Alias for BANK_SELECT
MODULATION = 0x01                    # Modulation Wheel MSB
MODULATION_WHEEL = 0x01              # Alias for MODULATION
MODULATION_WHEEL_MSB = 0x01          # Alias for MODULATION
BREATH_CONTROLLER = 0x02             # Breath Controller MSB
BREATH_CONTROLLER_MSB = 0x02         # Alias for BREATH_CONTROLLER
FOOT_CONTROLLER = 0x04               # Foot Controller MSB
FOOT_CONTROLLER_MSB = 0x04           # Alias for FOOT_CONTROLLER
PORTAMENTO_TIME = 0x05               # Portamento Time MSB
PORTAMENTO_TIME_MSB = 0x05           # Alias for PORTAMENTO_TIME
DATA_ENTRY = 0x06                    # Data Entry MSB
DATA_ENTRY_MSB = 0x06                # Alias for DATA_ENTRY
VOLUME = 0x07                        # Channel Volume MSB
CHANNEL_VOLUME = 0x07                # Alias for VOLUME
CHANNEL_VOLUME_MSB = 0x07            # Alias for VOLUME
BALANCE = 0x08                       # Balance MSB
BALANCE_MSB = 0x08                   # Alias for BALANCE
PAN = 0x0A                           # Pan MSB
PAN_MSB = 0x0A                       # Alias for PAN
EXPRESSION = 0x0B                    # Expression Controller MSB
EXPRESSION_CONTROLLER = 0x0B         # Alias for EXPRESSION
EXPRESSION_CONTROLLER_MSB = 0x0B     # Alias for EXPRESSION
EFFECT_CONTROL_1 = 0x0C              # Effect Control 1 MSB
EFFECT_CONTROL_1_MSB = 0x0C          # Alias for EFFECT_CONTROL_1
EFFECT_CONTROL_2 = 0x0D              # Effect Control 2 MSB
EFFECT_CONTROL_2_MSB = 0x0D          # Alias for EFFECT_CONTROL_2
GENERAL_PURPOSE_CONTROLLER_1 = 0x10   # General Purpose Controller 1 MSB
GENERAL_PURPOSE_CONTROLLER_1_MSB = 0x10  # Alias
GENERAL_PURPOSE_CONTROLLER_2 = 0x11   # General Purpose Controller 2 MSB
GENERAL_PURPOSE_CONTROLLER_2_MSB = 0x11  # Alias
GENERAL_PURPOSE_CONTROLLER_3 = 0x12   # General Purpose Controller 3 MSB
GENERAL_PURPOSE_CONTROLLER_3_MSB = 0x12  # Alias
GENERAL_PURPOSE_CONTROLLER_4 = 0x13   # General Purpose Controller 4 MSB
GENERAL_PURPOSE_CONTROLLER_4_MSB = 0x13  # Alias

Continuous Controller Numbers (LSB)

High-resolution continuous controllers (Least Significant Byte) for fine control adjustments.

# High Resolution Controllers (LSB)
BANK_SELECT_LSB = 0x20               # Bank Select LSB
MODULATION_LSB = 0x21                # Modulation Wheel LSB
MODULATION_WHEEL_LSB = 0x21          # Alias for MODULATION_LSB
BREATH_CONTROLLER_LSB = 0x22         # Breath Controller LSB
FOOT_CONTROLLER_LSB = 0x24           # Foot Controller LSB
PORTAMENTO_TIME_LSB = 0x25           # Portamento Time LSB
DATA_ENTRY_LSB = 0x26                # Data Entry LSB
VOLUME_LSB = 0x27                    # Channel Volume LSB
CHANNEL_VOLUME_LSB = 0x27            # Alias for VOLUME_LSB
BALANCE_LSB = 0x28                   # Balance LSB
PAN_LSB = 0x2A                       # Pan LSB
EXPRESSION_LSB = 0x2B                # Expression Controller LSB
EXPRESSION_CONTROLLER_LSB = 0x2B     # Alias for EXPRESSION_LSB
EFFECT_CONTROL_1_LSB = 0x2C          # Effect Control 1 LSB
EFFECT_CONTROL_2_LSB = 0x2D          # Effect Control 2 LSB
GENERAL_PURPOSE_CONTROLLER_1_LSB = 0x30  # General Purpose Controller 1 LSB
GENERAL_PURPOSE_CONTROLLER_2_LSB = 0x31  # General Purpose Controller 2 LSB
GENERAL_PURPOSE_CONTROLLER_3_LSB = 0x32  # General Purpose Controller 3 LSB
GENERAL_PURPOSE_CONTROLLER_4_LSB = 0x33  # General Purpose Controller 4 LSB

Switch Controllers

Binary on/off controllers (off: value ≤ 63, on: value ≥ 64).

# Switch Controllers (On/Off)
SUSTAIN = 0x40                       # Sustain Pedal
SUSTAIN_ONOFF = 0x40                 # Alias for SUSTAIN
PORTAMENTO = 0x41                    # Portamento On/Off
PORTAMENTO_ONOFF = 0x41              # Alias for PORTAMENTO
SOSTENUTO = 0x42                     # Sostenuto On/Off
SOSTENUTO_ONOFF = 0x42               # Alias for SOSTENUTO
SOFT_PEDAL = 0x43                    # Soft Pedal On/Off
SOFT_PEDAL_ONOFF = 0x43              # Alias for SOFT_PEDAL
LEGATO = 0x44                        # Legato On/Off
LEGATO_ONOFF = 0x44                  # Alias for LEGATO
HOLD_2 = 0x45                        # Hold 2 On/Off
HOLD_2_ONOFF = 0x45                  # Alias for HOLD_2

Sound Controllers

Low-resolution controllers for sound parameter adjustment.

# Sound Controllers
SOUND_CONTROLLER_1 = 0x46            # Sound Variation / FX: Exciter On/Off
SOUND_CONTROLLER_2 = 0x47            # Harmonic Content / FX: Compressor On/Off
SOUND_CONTROLLER_3 = 0x48            # Release Time / FX: Distortion On/Off
SOUND_CONTROLLER_4 = 0x49            # Attack Time / FX: EQ On/Off
SOUND_CONTROLLER_5 = 0x4A            # Brightness / FX: Expander On/Off
SOUND_CONTROLLER_6 = 0x4B            # Decay Time / FX: Reverb On/Off
SOUND_CONTROLLER_7 = 0x4C            # Vibrato Rate / FX: Delay On/Off
SOUND_CONTROLLER_8 = 0x4D            # Vibrato Depth / FX: Pitch Transpose On/Off
SOUND_CONTROLLER_9 = 0x4E            # Vibrato Delay / FX: Flange/Chorus On/Off
SOUND_CONTROLLER_10 = 0x4F           # Undefined / FX: Special Effects On/Off

Additional Controllers

Extended controller definitions and parameter management.

# Additional Controllers
GENERAL_PURPOSE_CONTROLLER_5 = 0x50   # General Purpose Controller 5
GENERAL_PURPOSE_CONTROLLER_6 = 0x51   # General Purpose Controller 6
GENERAL_PURPOSE_CONTROLLER_7 = 0x52   # General Purpose Controller 7
GENERAL_PURPOSE_CONTROLLER_8 = 0x53   # General Purpose Controller 8
PORTAMENTO_CONTROL = 0x54            # Portamento Control (source note number)
PTC = 0x54                           # Alias for PORTAMENTO_CONTROL
HIGH_RESOLUTION_VELOCITY_PREFIX = 0x58  # High Resolution Velocity Prefix

# Effects Depth Controllers
EFFECTS_1 = 0x5B                     # Reverb Send Level (formerly Ext. Effects Depth)
EFFECTS_1_DEPTH = 0x5B               # Alias for EFFECTS_1
EFFECTS_2 = 0x5C                     # Formerly Tremolo Depth
EFFECTS_2_DEPTH = 0x5C               # Alias for EFFECTS_2
EFFECTS_3 = 0x5D                     # Chorus Send Level (formerly Chorus Depth)
EFFECTS_3_DEPTH = 0x5D               # Alias for EFFECTS_3
EFFECTS_4 = 0x5E                     # Formerly Celeste (Detune) Depth
EFFECTS_4_DEPTH = 0x5E               # Alias for EFFECTS_4
EFFECTS_5 = 0x5F                     # Formerly Phaser Depth
EFFECTS_5_DEPTH = 0x5F               # Alias for EFFECTS_5

# Parameter Control
DATA_INCREMENT = 0x60                # Data Increment (value should be 0)
DATA_DECREMENT = 0x61                # Data Decrement (value should be 0)
NRPN_LSB = 0x62                      # Non-Registered Parameter Number LSB
NON_REGISTERED_PARAMETER_NUMBER_LSB = 0x62  # Alias for NRPN_LSB
NRPN_MSB = 0x63                      # Non-Registered Parameter Number MSB
NON_REGISTERED_PARAMETER_NUMBER_MSB = 0x63  # Alias for NRPN_MSB
RPN_LSB = 0x64                       # Registered Parameter Number LSB
REGISTERED_PARAMETER_NUMBER_LSB = 0x64     # Alias for RPN_LSB
RPN_MSB = 0x65                       # Registered Parameter Number MSB
REGISTERED_PARAMETER_NUMBER_MSB = 0x65     # Alias for RPN_MSB

Channel Mode Messages

Channel mode control messages for voice allocation and system behavior.

# Channel Mode Messages
ALL_SOUND_OFF = 0x78                 # All Sound Off (value should be 0)
RESET_ALL_CONTROLLERS = 0x79         # Reset All Controllers (value should be 0)
LOCAL_CONTROL = 0x7A                 # Local Control (0=off, 127=on)
LOCAL_CONTROL_ONOFF = 0x7A           # Alias for LOCAL_CONTROL
ALL_NOTES_OFF = 0x7B                 # All Notes Off (value should be 0)
OMNI_MODE_OFF = 0x7C                 # Omni Mode Off (causes All Notes Off)
OMNI_MODE_ON = 0x7D                  # Omni Mode On (causes All Notes Off)
MONO_MODE_ON = 0x7E                  # Mono Mode On/Poly Off (causes All Notes Off)
POLY_MODE_ON = 0x7F                  # Poly Mode On/Mono Off (causes All Notes Off)

System Common Messages

System-wide messages for all MIDI channels and devices.

# System Common Messages
SYSTEM_EXCLUSIVE = 0xF0              # System Exclusive start
MIDI_TIME_CODE = 0xF1                # MIDI Time Code Quarter Frame
MTC = 0xF1                           # Alias for MIDI_TIME_CODE
SONG_POSITION_POINTER = 0xF2         # Song Position Pointer
SONG_SELECT = 0xF3                   # Song Select
TUNING_REQUEST = 0xF6                # Tuning Request
TUNE_REQUEST = 0xF6                  # Alias for TUNING_REQUEST
END_OF_EXCLUSIVE = 0xF7              # End of System Exclusive

MIDI File Meta-Events

Meta-events used in Standard MIDI File format.

# MIDI File Meta-Events
SEQUENCE_NUMBER = 0x00               # Sequence Number
TEXT = 0x01                          # Text Event
COPYRIGHT = 0x02                     # Copyright Notice
SEQUENCE_NAME = 0x03                 # Sequence/Track Name
INSTRUMENT_NAME = 0x04               # Instrument Name
LYRIC = 0x05                         # Lyric
MARKER = 0x06                        # Marker
CUEPOINT = 0x07                      # Cue Point
PROGRAM_NAME = 0x08                  # Program Name
DEVICE_NAME = 0x09                   # Device Name
MIDI_CH_PREFIX = 0x20                # MIDI Channel Prefix (deprecated)
MIDI_PORT = 0x21                     # MIDI Port (deprecated but still used)
END_OF_TRACK = 0x2F                  # End of Track
TEMPO = 0x51                         # Set Tempo (microseconds per quarter note)
SMTP_OFFSET = 0x54                   # SMPTE Offset
TIME_SIGNATURE = 0x58                # Time Signature
KEY_SIGNATURE = 0x59                 # Key Signature
SPECIFIC = 0x7F                      # Sequencer Specific

System Realtime Messages

Real-time messages for MIDI clock synchronization and transport control.

# System Realtime Messages
TIMING_CLOCK = 0xF8                  # Timing Clock (24 per quarter note)
SONG_START = 0xFA                    # Start playback from beginning
SONG_CONTINUE = 0xFB                 # Continue playback from current position
SONG_STOP = 0xFC                     # Stop playback
ACTIVE_SENSING = 0xFE                # Active Sensing (sent every 300ms max)
SYSTEM_RESET = 0xFF                  # System Reset

Additional Constants

Meta-events, file format constants, and timecode definitions.

# Meta Event Constants
META_EVENT = 0xFF                    # Meta Event (MIDI files only)
ESCAPE_SEQUENCE = 0xF7               # Escape Sequence

# MIDI File Format Constants
FILE_HEADER = 'MThd'                 # MIDI file header identifier
TRACK_HEADER = 'MTrk'                # Track chunk header identifier

# Timecode Resolution (frames per second)
FPS_24 = 0xE8                        # 24 fps
FPS_25 = 0xE7                        # 25 fps
FPS_29 = 0xE3                        # 29.97 fps (30 drop frame)
FPS_30 = 0xE2                        # 30 fps

Helper Functions

Utility functions for MIDI message analysis and validation.

def is_status(byte):
    """
    Check if byte is a MIDI status byte.
    
    Parameters:
    - byte: Integer byte value (0-255)
    
    Returns:
    - bool: True if byte has bit 7 set (0x80 & byte == 0x80)
    """

Usage Examples

Basic MIDI Message Construction

import rtmidi.midiconstants as mc

# Create common MIDI messages
note_on = [mc.NOTE_ON | 0, 60, 100]    # Channel 1, Middle C, velocity 100
note_off = [mc.NOTE_OFF | 0, 60, 0]    # Channel 1, Middle C, velocity 0

# Control change messages
volume_change = [mc.CONTROLLER_CHANGE | 0, mc.VOLUME, 100]
pan_center = [mc.CONTROLLER_CHANGE | 0, mc.PAN, 64]
sustain_on = [mc.CONTROLLER_CHANGE | 0, mc.SUSTAIN, 127]
sustain_off = [mc.CONTROLLER_CHANGE | 0, mc.SUSTAIN, 0]

# Program change
piano_patch = [mc.PROGRAM_CHANGE | 0, 0]  # Channel 1, patch 0

# System messages
sysex_msg = [mc.SYSTEM_EXCLUSIVE, 0x43, 0x12, 0x00, mc.END_OF_EXCLUSIVE]

MIDI Message Analysis

import rtmidi.midiconstants as mc

def analyze_midi_message(message):
    if not message:
        return "Empty message"
    
    status_byte = message[0]
    
    if not mc.is_status(status_byte):
        return "Invalid: First byte is not a status byte"
    
    msg_type = status_byte & 0xF0
    channel = status_byte & 0x0F
    
    if msg_type == mc.NOTE_ON:
        note, velocity = message[1], message[2]
        return f"Note On: Channel {channel+1}, Note {note}, Velocity {velocity}"
    elif msg_type == mc.NOTE_OFF:
        note, velocity = message[1], message[2]
        return f"Note Off: Channel {channel+1}, Note {note}, Velocity {velocity}"
    elif msg_type == mc.CONTROLLER_CHANGE:
        controller, value = message[1], message[2]
        return f"CC: Channel {channel+1}, Controller {controller}, Value {value}"
    elif status_byte == mc.SYSTEM_EXCLUSIVE:
        return f"SysEx: {len(message)} bytes"
    else:
        return f"Other message type: 0x{status_byte:02X}"

# Usage
message = [0x90, 60, 100]  # Note On
print(analyze_midi_message(message))  # "Note On: Channel 1, Note 60, Velocity 100"

Controller Value Interpretation

import rtmidi.midiconstants as mc

def interpret_controller_value(controller, value):
    """Interpret controller values based on controller type."""
    
    # Switch controllers (on/off)
    if controller in [mc.SUSTAIN, mc.PORTAMENTO, mc.SOSTENUTO, 
                      mc.SOFT_PEDAL, mc.LEGATO, mc.HOLD_2]:
        return "On" if value >= 64 else "Off"
    
    # Centered controllers (pan, balance)
    elif controller in [mc.PAN, mc.BALANCE]:
        if value == 64:
            return "Center"
        elif value < 64:
            return f"Left {64-value}"
        else:
            return f"Right {value-64}"
    
    # Standard 0-127 range
    else:
        return f"{value}/127 ({value/127*100:.1f}%)"

# Usage
print(interpret_controller_value(mc.SUSTAIN, 127))  # "On"
print(interpret_controller_value(mc.PAN, 64))       # "Center"
print(interpret_controller_value(mc.VOLUME, 100))   # "100/127 (78.7%)"

Install with Tessl CLI

npx tessl i tessl/pypi-python-rtmidi

docs