pymididefs 0.2.4__py3-none-any.whl

pymididefs/__init__.py

@@ -0,0 +1,34 @@
+"""PyMidiDefs — comprehensive MIDI 1.0 and 2.0 constant definitions for Python.
+
+A zero-dependency reference library covering the MIDI 1.0 Detailed Specification,
+General MIDI Level 1, Universal MIDI Packet (UMP) format, and MIDI-CI.
+
+Modules
+-------
+notes   — MIDI note numbers and name/number conversion.
+cc      — Control Change number assignments and 14-bit pack/unpack helpers.
+rpn     — Standard Registered Parameter Numbers and the 14-bit parameter conventions shared with NRPN.
+drums   — General MIDI Level 1 percussion key map.
+gm      — General MIDI Level 1 instrument program numbers and families.
+status  — MIDI 1.0 status bytes (channel voice, system common, system real-time).
+meta    — Standard MIDI File meta-event type bytes.
+ump     — MIDI 2.0 Universal MIDI Packet message types and constants.
+ci      — MIDI 2.0 Capability Inquiry (MIDI-CI) constants.
+"""
+
+import importlib.metadata
+
+import pymididefs.notes
+
+# Version is derived from the latest git tag at build time via hatch-vcs;
+# `importlib.metadata` then reads it from the installed package metadata.
+# The fallback only fires if someone runs from a raw source checkout without
+# installing the package (e.g. directly from a git clone with no `pip install`).
+try:
+	__version__ = importlib.metadata.version("pymididefs")
+except importlib.metadata.PackageNotFoundError:
+	__version__ = "0.0.0+unknown"
+
+# Convenience re-exports for the most common operations.
+note_to_name = pymididefs.notes.note_to_name
+name_to_note = pymididefs.notes.name_to_note

pymididefs/cc.py

@@ -0,0 +1,284 @@
+"""MIDI Control Change (CC) number assignments.
+
+The MIDI specification defines 128 controller numbers (0–127).  This module
+provides named constants for all controllers that have a defined function in
+the MIDI 1.0 Detailed Specification.  Undefined/reserved numbers (3, 9, 14–15,
+20–31, 85–90, 102–119) are omitted — they are available for general-purpose
+use and do not have standard names.
+
+Two ways to use this module::
+
+	import pymididefs.cc
+
+	# As named constants
+	pymididefs.cc.SUSTAIN_PEDAL       # 64
+
+	# As a lookup dictionary
+	pymididefs.cc.CC_MAP["sustain_pedal"]  # 64
+
+Source: MIDI 1.0 Detailed Specification, Table III — Control Change Messages.
+"""
+
+import typing
+
+
+# ── MSB Controllers (0–31) ───────────────────────────────────────────────────
+# High-resolution continuous controllers — most significant byte.
+# Controllers 0–31 each have a corresponding LSB at CC 32–63.
+
+BANK_SELECT_MSB     = 0   # Bank Select
+MODULATION_WHEEL    = 1   # Modulation Wheel or Lever
+BREATH_CONTROLLER   = 2   # Breath Controller
+# CC 3: Undefined
+FOOT_CONTROLLER     = 4   # Foot Controller
+PORTAMENTO_TIME     = 5   # Portamento Time
+DATA_ENTRY_MSB      = 6   # Data Entry MSB
+VOLUME              = 7   # Channel Volume (formerly Main Volume)
+BALANCE             = 8   # Balance
+# CC 9: Undefined
+PAN                 = 10  # Pan
+EXPRESSION          = 11  # Expression Controller
+EFFECT_CONTROL_1    = 12  # Effect Control 1
+EFFECT_CONTROL_2    = 13  # Effect Control 2
+# CC 14–15: Undefined
+GENERAL_PURPOSE_1   = 16  # General Purpose Controller 1
+GENERAL_PURPOSE_2   = 17  # General Purpose Controller 2
+GENERAL_PURPOSE_3   = 18  # General Purpose Controller 3
+GENERAL_PURPOSE_4   = 19  # General Purpose Controller 4
+# CC 20–31: Undefined
+
+
+# ── LSB Controllers (32–63) ──────────────────────────────────────────────────
+# Low-resolution counterparts for CC 0–31.
+# Only the most commonly referenced LSB values are named here.
+
+BANK_SELECT_LSB         = 32  # Bank Select LSB
+MODULATION_WHEEL_LSB    = 33  # Modulation Wheel LSB
+BREATH_CONTROLLER_LSB   = 34  # Breath Controller LSB
+# CC 35: Undefined LSB
+FOOT_CONTROLLER_LSB     = 36  # Foot Controller LSB
+PORTAMENTO_TIME_LSB     = 37  # Portamento Time LSB
+DATA_ENTRY_LSB          = 38  # Data Entry LSB
+VOLUME_LSB              = 39  # Channel Volume LSB
+BALANCE_LSB             = 40  # Balance LSB
+# CC 41: Undefined LSB
+PAN_LSB                 = 42  # Pan LSB
+EXPRESSION_LSB          = 43  # Expression LSB
+EFFECT_CONTROL_1_LSB    = 44  # Effect Control 1 LSB
+EFFECT_CONTROL_2_LSB    = 45  # Effect Control 2 LSB
+
+
+# ── Switch Controllers (64–69) ───────────────────────────────────────────────
+# On/off pedals and switches.  Values 0–63 = Off, 64–127 = On.
+
+SUSTAIN_PEDAL       = 64  # Damper Pedal (Sustain)
+PORTAMENTO_ON_OFF   = 65  # Portamento On/Off
+SOSTENUTO_PEDAL     = 66  # Sostenuto
+SOFT_PEDAL          = 67  # Soft Pedal
+LEGATO_PEDAL        = 68  # Legato Footswitch
+HOLD_2              = 69  # Hold 2
+
+
+# ── Sound Controllers (70–79) ────────────────────────────────────────────────
+# Defined by General MIDI Level 2 for real-time timbre adjustment.
+
+SOUND_VARIATION     = 70  # Sound Controller 1  (default: Sound Variation)
+FILTER_RESONANCE    = 71  # Sound Controller 2  (default: Timbre / Filter Resonance)
+RELEASE_TIME        = 72  # Sound Controller 3  (default: Release Time)
+ATTACK_TIME         = 73  # Sound Controller 4  (default: Attack Time)
+FILTER_CUTOFF       = 74  # Sound Controller 5  (default: Brightness / Filter Cutoff)
+SOUND_CONTROL_6     = 75  # Sound Controller 6  (default: Decay Time — GM2)
+SOUND_CONTROL_7     = 76  # Sound Controller 7  (default: Vibrato Rate — GM2)
+SOUND_CONTROL_8     = 77  # Sound Controller 8  (default: Vibrato Depth — GM2)
+SOUND_CONTROL_9     = 78  # Sound Controller 9  (default: Vibrato Delay — GM2)
+SOUND_CONTROL_10    = 79  # Sound Controller 10 (default: undefined)
+
+
+# ── General Purpose Controllers (80–83) ──────────────────────────────────────
+
+GENERAL_PURPOSE_5   = 80  # General Purpose Controller 5
+GENERAL_PURPOSE_6   = 81  # General Purpose Controller 6
+GENERAL_PURPOSE_7   = 82  # General Purpose Controller 7
+GENERAL_PURPOSE_8   = 83  # General Purpose Controller 8
+
+
+# ── Effects Send Levels (91–95) ──────────────────────────────────────────────
+# CC 84 is Portamento Control; CC 85–90 are undefined.
+
+PORTAMENTO_CONTROL  = 84  # Portamento Control (source note for portamento)
+# CC 85–90: Undefined
+REVERB_DEPTH        = 91  # Effects 1 Depth (default: Reverb Send Level)
+TREMOLO_DEPTH       = 92  # Effects 2 Depth (default: Tremolo Depth)
+CHORUS_DEPTH        = 93  # Effects 3 Depth (default: Chorus Send Level)
+CELESTE_DEPTH       = 94  # Effects 4 Depth (default: Celeste / Detune Depth)
+PHASER_DEPTH        = 95  # Effects 5 Depth (default: Phaser Depth)
+
+
+# ── Parameter Control (96–101) ───────────────────────────────────────────────
+# Used for RPN / NRPN parameter addressing and data manipulation.
+
+DATA_INCREMENT      = 96   # Data Increment (Data Entry +1)
+DATA_DECREMENT      = 97   # Data Decrement (Data Entry -1)
+NRPN_LSB            = 98   # Non-Registered Parameter Number LSB
+NRPN_MSB            = 99   # Non-Registered Parameter Number MSB
+RPN_LSB             = 100  # Registered Parameter Number LSB
+RPN_MSB             = 101  # Registered Parameter Number MSB
+
+# CC 102–119: Undefined
+
+
+# ── Channel Mode Messages (120–127) ─────────────────────────────────────────
+# These use the Control Change status byte but function as channel mode
+# commands rather than continuous controllers.
+
+ALL_SOUND_OFF           = 120  # All Sound Off (value = 0)
+RESET_ALL_CONTROLLERS   = 121  # Reset All Controllers (value = 0)
+LOCAL_CONTROL_ON_OFF    = 122  # Local Control On/Off (0 = Off, 127 = On)
+ALL_NOTES_OFF           = 123  # All Notes Off (value = 0)
+OMNI_MODE_OFF           = 124  # Omni Mode Off (+ All Notes Off)
+OMNI_MODE_ON            = 125  # Omni Mode On (+ All Notes Off)
+MONO_MODE_ON            = 126  # Mono Mode On (+ All Notes Off)
+POLY_MODE_ON            = 127  # Poly Mode On (+ All Notes Off)
+
+
+# ── Lookup dictionary ────────────────────────────────────────────────────────
+# Maps snake_case names to CC numbers for string-based access.
+
+CC_MAP: typing.Final[dict[str, int]] = {
+	# MSB controllers
+	"bank_select_msb":      BANK_SELECT_MSB,
+	"modulation_wheel":     MODULATION_WHEEL,
+	"breath_controller":    BREATH_CONTROLLER,
+	"foot_controller":      FOOT_CONTROLLER,
+	"portamento_time":      PORTAMENTO_TIME,
+	"data_entry_msb":       DATA_ENTRY_MSB,
+	"volume":               VOLUME,
+	"balance":              BALANCE,
+	"pan":                  PAN,
+	"expression":           EXPRESSION,
+	"effect_control_1":     EFFECT_CONTROL_1,
+	"effect_control_2":     EFFECT_CONTROL_2,
+	"general_purpose_1":    GENERAL_PURPOSE_1,
+	"general_purpose_2":    GENERAL_PURPOSE_2,
+	"general_purpose_3":    GENERAL_PURPOSE_3,
+	"general_purpose_4":    GENERAL_PURPOSE_4,
+
+	# LSB controllers
+	"bank_select_lsb":          BANK_SELECT_LSB,
+	"modulation_wheel_lsb":     MODULATION_WHEEL_LSB,
+	"breath_controller_lsb":    BREATH_CONTROLLER_LSB,
+	"foot_controller_lsb":      FOOT_CONTROLLER_LSB,
+	"portamento_time_lsb":      PORTAMENTO_TIME_LSB,
+	"data_entry_lsb":           DATA_ENTRY_LSB,
+	"volume_lsb":               VOLUME_LSB,
+	"balance_lsb":              BALANCE_LSB,
+	"pan_lsb":                  PAN_LSB,
+	"expression_lsb":           EXPRESSION_LSB,
+	"effect_control_1_lsb":     EFFECT_CONTROL_1_LSB,
+	"effect_control_2_lsb":     EFFECT_CONTROL_2_LSB,
+
+	# Switch controllers
+	"sustain_pedal":        SUSTAIN_PEDAL,
+	"portamento_on_off":    PORTAMENTO_ON_OFF,
+	"sostenuto_pedal":      SOSTENUTO_PEDAL,
+	"soft_pedal":           SOFT_PEDAL,
+	"legato_pedal":         LEGATO_PEDAL,
+	"hold_2":               HOLD_2,
+
+	# Sound controllers
+	"sound_variation":      SOUND_VARIATION,
+	"filter_resonance":     FILTER_RESONANCE,
+	"release_time":         RELEASE_TIME,
+	"attack_time":          ATTACK_TIME,
+	"filter_cutoff":        FILTER_CUTOFF,
+	"sound_control_6":      SOUND_CONTROL_6,
+	"sound_control_7":      SOUND_CONTROL_7,
+	"sound_control_8":      SOUND_CONTROL_8,
+	"sound_control_9":      SOUND_CONTROL_9,
+	"sound_control_10":     SOUND_CONTROL_10,
+
+	# General purpose controllers
+	"general_purpose_5":    GENERAL_PURPOSE_5,
+	"general_purpose_6":    GENERAL_PURPOSE_6,
+	"general_purpose_7":    GENERAL_PURPOSE_7,
+	"general_purpose_8":    GENERAL_PURPOSE_8,
+
+	# Effects send levels
+	"portamento_control":   PORTAMENTO_CONTROL,
+	"reverb_depth":         REVERB_DEPTH,
+	"tremolo_depth":        TREMOLO_DEPTH,
+	"chorus_depth":         CHORUS_DEPTH,
+	"celeste_depth":        CELESTE_DEPTH,
+	"phaser_depth":         PHASER_DEPTH,
+
+	# Parameter control
+	"data_increment":       DATA_INCREMENT,
+	"data_decrement":       DATA_DECREMENT,
+	"nrpn_lsb":             NRPN_LSB,
+	"nrpn_msb":             NRPN_MSB,
+	"rpn_lsb":              RPN_LSB,
+	"rpn_msb":              RPN_MSB,
+
+	# Channel mode messages
+	"all_sound_off":            ALL_SOUND_OFF,
+	"reset_all_controllers":    RESET_ALL_CONTROLLERS,
+	"local_control_on_off":     LOCAL_CONTROL_ON_OFF,
+	"all_notes_off":            ALL_NOTES_OFF,
+	"omni_mode_off":            OMNI_MODE_OFF,
+	"omni_mode_on":             OMNI_MODE_ON,
+	"mono_mode_on":             MONO_MODE_ON,
+	"poly_mode_on":             POLY_MODE_ON,
+}
+
+
+# ── 14-bit value pack/unpack ─────────────────────────────────────────────────
+# Many MIDI 1.0 message types — Bank Select, Data Entry, RPN/NRPN parameter
+# numbers, pitch bend, song position pointer — split a 14-bit value across
+# two 7-bit MSB/LSB bytes.  These helpers convert between the integer form
+# and the wire-format byte pair.
+
+def pack_14bit (value: int) -> tuple[int, int]:
+
+	"""Split a 14-bit integer (0–16383) into ``(MSB, LSB)`` bytes.
+
+	Each returned byte is in the 7-bit range 0–127.  The tuple ordering
+	``(MSB, LSB)`` is the logical pairing — wire-transmission order is
+	message-dependent (Bank Select and RPN/NRPN parameter selection send MSB
+	first, but pitch bend sends LSB first).
+
+	>>> pack_14bit(0)
+	(0, 0)
+	>>> pack_14bit(16383)
+	(127, 127)
+	>>> pack_14bit(8192)
+	(64, 0)
+	"""
+
+	if not 0 <= value <= 16383:
+		raise ValueError(
+			f"14-bit value must be 0–16383, got {value}"
+		)
+
+	return (value >> 7) & 0x7F, value & 0x7F
+
+
+def unpack_14bit (msb: int, lsb: int) -> int:
+
+	"""Combine an ``(MSB, LSB)`` byte pair into a 14-bit integer (0–16383).
+
+	Both inputs must be in the 7-bit range 0–127.
+
+	>>> unpack_14bit(0, 0)
+	0
+	>>> unpack_14bit(127, 127)
+	16383
+	>>> unpack_14bit(64, 0)
+	8192
+	"""
+
+	if not 0 <= msb <= 127:
+		raise ValueError(f"MSB must be 0–127, got {msb}")
+	if not 0 <= lsb <= 127:
+		raise ValueError(f"LSB must be 0–127, got {lsb}")
+
+	return (msb << 7) | lsb

pymididefs/ci.py

@@ -0,0 +1,79 @@
+"""MIDI 2.0 Capability Inquiry (MIDI-CI) constants.
+
+MIDI-CI enables bidirectional communication between MIDI devices for
+capability discovery, profile configuration, and property exchange.
+MIDI-CI messages are transported as Universal System Exclusive (Non-Real-Time).
+
+::
+
+	import pymididefs.ci
+	pymididefs.ci.DISCOVERY      # 0x70
+	pymididefs.ci.CI_SUB_ID      # 0x0D
+
+Source: M2-101-UM v1.2 — MIDI-CI Specification.
+"""
+
+
+# ── Universal SysEx Framing ──────────────────────────────────────────────────
+# MIDI-CI messages are wrapped in Universal Non-Real-Time SysEx:
+#   F0 7E <device_id> 0D <sub_id_2> <data...> F7
+
+UNIVERSAL_NON_REALTIME  = 0x7E  # Universal Non-Real-Time SysEx ID byte
+UNIVERSAL_REALTIME      = 0x7F  # Universal Real-Time SysEx ID byte
+CI_SUB_ID               = 0x0D  # MIDI-CI Sub-ID #1 (identifies CI messages)
+BROADCAST_ADDRESS       = 0x7F  # Device ID for broadcast (all devices on port)
+
+
+# ── MIDI-CI Message Types (Sub-ID #2) ────────────────────────────────────────
+# These identify the specific MIDI-CI message within the SysEx payload.
+
+# Management messages
+DISCOVERY               = 0x70  # Discovery Inquiry
+DISCOVERY_REPLY         = 0x71  # Reply to Discovery
+INVALIDATE_MUID         = 0x7E  # Invalidate MUID (device going offline)
+NAK                     = 0x7F  # NAK (negative acknowledgement)
+
+# Profile Configuration messages
+PROFILE_INQUIRY             = 0x20  # Profile Inquiry
+PROFILE_INQUIRY_REPLY       = 0x21  # Reply to Profile Inquiry
+SET_PROFILE_ON              = 0x22  # Set Profile On
+SET_PROFILE_OFF             = 0x23  # Set Profile Off
+PROFILE_ENABLED             = 0x24  # Profile Enabled Report
+PROFILE_DISABLED            = 0x25  # Profile Disabled Report
+PROFILE_ADDED               = 0x26  # Profile Added Report
+PROFILE_REMOVED             = 0x27  # Profile Removed Report
+PROFILE_DETAILS_INQUIRY     = 0x28  # Profile Details Inquiry
+PROFILE_DETAILS_REPLY       = 0x29  # Reply to Profile Details Inquiry
+PROFILE_SPECIFIC_DATA       = 0x2F  # Profile Specific Data
+
+# Property Exchange messages
+PROPERTY_CAPABILITIES       = 0x30  # Inquiry: Property Exchange Capabilities
+PROPERTY_CAPABILITIES_REPLY = 0x31  # Reply to Property Exchange Capabilities
+PROPERTY_GET                = 0x34  # Get Property Data Inquiry
+PROPERTY_GET_REPLY          = 0x35  # Reply to Get Property Data
+PROPERTY_SET                = 0x36  # Set Property Data Inquiry
+PROPERTY_SET_REPLY          = 0x37  # Reply to Set Property Data
+PROPERTY_SUBSCRIBE          = 0x38  # Subscription Inquiry
+PROPERTY_SUBSCRIBE_REPLY    = 0x39  # Reply to Subscription
+PROPERTY_NOTIFY             = 0x3F  # Notify (subscription update)
+
+# Process Inquiry messages (MIDI-CI 1.2)
+PROCESS_INQUIRY             = 0x40  # Process Inquiry
+PROCESS_INQUIRY_REPLY       = 0x41  # Reply to Process Inquiry
+PROCESS_MIDI_REPORT         = 0x42  # MIDI Message Report
+PROCESS_MIDI_REPORT_REPLY   = 0x43  # Reply to MIDI Message Report
+PROCESS_MIDI_REPORT_END     = 0x44  # End of MIDI Message Report
+
+
+# ── Broadcast MUID ───────────────────────────────────────────────────────────
+# 28-bit MUID (Message Unique Identifier) value used for broadcast discovery.
+# Sent as 4 bytes in the SysEx payload (7 bits each, totalling 28 bits).
+
+BROADCAST_MUID          = 0x0FFFFFFF  # All-ones 28-bit MUID (broadcast)
+
+
+# ── MIDI-CI Version ──────────────────────────────────────────────────────────
+# Version byte included in Discovery and Reply to Discovery messages.
+
+CI_VERSION_1_1          = 0x01  # MIDI-CI version 1.1
+CI_VERSION_1_2          = 0x02  # MIDI-CI version 1.2

pymididefs/drums.py

@@ -0,0 +1,221 @@
+"""General MIDI Level 1 percussion key map.
+
+Standard MIDI percussion assignments for channel 10 (0-indexed channel 9).
+These note numbers are defined by the General MIDI Level 1 specification and
+are supported by virtually all GM-compatible instruments, drum machines, and
+DAWs.
+
+Two ways to use this module::
+
+	import pymididefs.drums
+
+	# As named constants
+	pymididefs.drums.KICK_1         # 36
+	pymididefs.drums.HI_HAT_CLOSED  # 42
+
+	# As a lookup dictionary
+	pymididefs.drums.GM_DRUM_MAP["kick_1"]  # 36
+
+The four instruments GM defines in numbered pairs — kick, snare, crash, ride —
+also have unnumbered *primary aliases* pointing to the "1" variant: the
+``KICK`` / ``SNARE`` / ``CRASH`` / ``RIDE`` constants and the
+``GM_DRUM_PRIMARY_ALIASES`` lookup, kept separate from ``GM_DRUM_MAP`` so the
+canonical key map stays one name per note.
+
+Source: General MIDI Level 1 Specification — Percussion Key Map.
+Note range: 27 (High Q) through 87 (Open Surdo).
+Channel: 10 (1-indexed) / 9 (0-indexed).
+"""
+
+import typing
+
+
+# ── GM Level 1 Percussion Key Map (notes 27–87) ─────────────────────────────
+# Organised by instrument family for readability.
+
+# Electronic percussion / effects (27–34)
+HIGH_Q              = 27  # High Q
+SLAP                = 28  # Slap
+SCRATCH_PUSH        = 29  # Scratch Push
+SCRATCH_PULL        = 30  # Scratch Pull
+STICKS              = 31  # Sticks
+SQUARE_CLICK        = 32  # Square Click
+METRONOME_CLICK     = 33  # Metronome Click
+METRONOME_BELL      = 34  # Metronome Bell
+
+# Kick drums (35–36)
+KICK_2              = 35  # Acoustic Bass Drum
+KICK_1              = 36  # Bass Drum 1
+
+# Snare and side stick (37–40)
+SIDE_STICK          = 37  # Side Stick
+SNARE_1             = 38  # Acoustic Snare
+HAND_CLAP           = 39  # Hand Clap
+SNARE_2             = 40  # Electric Snare
+
+# Toms (41, 43, 45, 47, 48, 50)
+LOW_FLOOR_TOM       = 41  # Low Floor Tom
+HI_HAT_CLOSED       = 42  # Closed Hi-Hat
+HIGH_FLOOR_TOM      = 43  # High Floor Tom
+HI_HAT_PEDAL        = 44  # Pedal Hi-Hat
+LOW_TOM             = 45  # Low Tom
+HI_HAT_OPEN         = 46  # Open Hi-Hat
+LOW_MID_TOM         = 47  # Low-Mid Tom
+HIGH_MID_TOM        = 48  # Hi-Mid Tom
+CRASH_1             = 49  # Crash Cymbal 1
+HIGH_TOM            = 50  # High Tom
+
+# Cymbals (51–53, 55, 57, 59)
+RIDE_1              = 51  # Ride Cymbal 1
+CHINESE_CYMBAL      = 52  # Chinese Cymbal
+RIDE_BELL           = 53  # Ride Bell
+TAMBOURINE          = 54  # Tambourine
+SPLASH_CYMBAL       = 55  # Splash Cymbal
+COWBELL             = 56  # Cowbell
+CRASH_2             = 57  # Crash Cymbal 2
+VIBRASLAP           = 58  # Vibraslap
+RIDE_2              = 59  # Ride Cymbal 2
+
+# Latin percussion (60–69)
+HIGH_BONGO          = 60  # Hi Bongo
+LOW_BONGO           = 61  # Low Bongo
+MUTE_HIGH_CONGA     = 62  # Mute Hi Conga
+OPEN_HIGH_CONGA     = 63  # Open Hi Conga
+LOW_CONGA           = 64  # Low Conga
+HIGH_TIMBALE        = 65  # High Timbale
+LOW_TIMBALE         = 66  # Low Timbale
+HIGH_AGOGO          = 67  # High Agogo
+LOW_AGOGO           = 68  # Low Agogo
+CABASA              = 69  # Cabasa
+
+# Shakers and small percussion (70–79)
+MARACAS             = 70  # Maracas
+SHORT_WHISTLE       = 71  # Short Whistle
+LONG_WHISTLE        = 72  # Long Whistle
+SHORT_GUIRO         = 73  # Short Guiro
+LONG_GUIRO          = 74  # Long Guiro
+CLAVES              = 75  # Claves
+HIGH_WOODBLOCK      = 76  # Hi Wood Block
+LOW_WOODBLOCK       = 77  # Low Wood Block
+MUTE_CUICA          = 78  # Mute Cuica
+OPEN_CUICA          = 79  # Open Cuica
+
+# Triangle and bells (80–87)
+MUTE_TRIANGLE       = 80  # Mute Triangle
+OPEN_TRIANGLE       = 81  # Open Triangle
+SHAKER              = 82  # Shaker
+JINGLE_BELL         = 83  # Jingle Bell
+BELL_TREE           = 84  # Bell Tree
+CASTANETS           = 85  # Castanets
+MUTE_SURDO          = 86  # Mute Surdo
+OPEN_SURDO          = 87  # Open Surdo
+
+
+# ── Lookup dictionary ────────────────────────────────────────────────────────
+# Maps snake_case names to MIDI note numbers for string-based access.
+
+GM_DRUM_MAP: typing.Final[dict[str, int]] = {
+	# Electronic percussion / effects
+	"high_q":           HIGH_Q,
+	"slap":             SLAP,
+	"scratch_push":     SCRATCH_PUSH,
+	"scratch_pull":     SCRATCH_PULL,
+	"sticks":           STICKS,
+	"square_click":     SQUARE_CLICK,
+	"metronome_click":  METRONOME_CLICK,
+	"metronome_bell":   METRONOME_BELL,
+
+	# Kick drums
+	"kick_2":           KICK_2,
+	"kick_1":           KICK_1,
+
+	# Snare and side stick
+	"side_stick":       SIDE_STICK,
+	"snare_1":          SNARE_1,
+	"hand_clap":        HAND_CLAP,
+	"snare_2":          SNARE_2,
+
+	# Toms and hi-hats
+	"low_floor_tom":    LOW_FLOOR_TOM,
+	"hi_hat_closed":    HI_HAT_CLOSED,
+	"high_floor_tom":   HIGH_FLOOR_TOM,
+	"hi_hat_pedal":     HI_HAT_PEDAL,
+	"low_tom":          LOW_TOM,
+	"hi_hat_open":      HI_HAT_OPEN,
+	"low_mid_tom":      LOW_MID_TOM,
+	"high_mid_tom":     HIGH_MID_TOM,
+	"high_tom":         HIGH_TOM,
+
+	# Cymbals
+	"crash_1":          CRASH_1,
+	"ride_1":           RIDE_1,
+	"chinese_cymbal":   CHINESE_CYMBAL,
+	"ride_bell":        RIDE_BELL,
+	"tambourine":       TAMBOURINE,
+	"splash_cymbal":    SPLASH_CYMBAL,
+	"cowbell":          COWBELL,
+	"crash_2":          CRASH_2,
+	"vibraslap":        VIBRASLAP,
+	"ride_2":           RIDE_2,
+
+	# Latin percussion
+	"high_bongo":       HIGH_BONGO,
+	"low_bongo":        LOW_BONGO,
+	"mute_high_conga":  MUTE_HIGH_CONGA,
+	"open_high_conga":  OPEN_HIGH_CONGA,
+	"low_conga":        LOW_CONGA,
+	"high_timbale":     HIGH_TIMBALE,
+	"low_timbale":      LOW_TIMBALE,
+	"high_agogo":       HIGH_AGOGO,
+	"low_agogo":        LOW_AGOGO,
+	"cabasa":           CABASA,
+
+	# Shakers and small percussion
+	"maracas":          MARACAS,
+	"short_whistle":    SHORT_WHISTLE,
+	"long_whistle":     LONG_WHISTLE,
+	"short_guiro":      SHORT_GUIRO,
+	"long_guiro":       LONG_GUIRO,
+	"claves":           CLAVES,
+	"high_woodblock":   HIGH_WOODBLOCK,
+	"low_woodblock":    LOW_WOODBLOCK,
+	"mute_cuica":       MUTE_CUICA,
+	"open_cuica":       OPEN_CUICA,
+
+	# Triangle and bells
+	"mute_triangle":    MUTE_TRIANGLE,
+	"open_triangle":    OPEN_TRIANGLE,
+	"shaker":           SHAKER,
+	"jingle_bell":      JINGLE_BELL,
+	"bell_tree":        BELL_TREE,
+	"castanets":        CASTANETS,
+	"mute_surdo":       MUTE_SURDO,
+	"open_surdo":       OPEN_SURDO,
+}
+
+
+# ── Primary aliases ──────────────────────────────────────────────────────────
+# General MIDI defines four instruments in numbered pairs — two kicks, two
+# snares, two crashes, two rides.  These unnumbered aliases point to the
+# GM-designated *primary* (the "1" variant): Bass Drum 1, Acoustic Snare,
+# Crash Cymbal 1, Ride Cymbal 1 — the notes every GM kit treats as the main
+# kick / snare / crash / ride.  Use ``KICK`` when you just want "the kick"
+# rather than choosing between the two.
+#
+# Kept separate from GM_DRUM_MAP, which stays one name per note (the canonical
+# percussion key map).  Only these four instruments come in numbered pairs; the
+# single-instance voices (closed/open/pedal hi-hat, side stick, cowbell, …) are
+# already unnumbered.  Ambiguous cases with no clear primary (e.g. the six toms)
+# are deliberately not aliased.
+
+KICK  = KICK_1   # Bass Drum 1 (36)
+SNARE = SNARE_1  # Acoustic Snare (38)
+CRASH = CRASH_1  # Crash Cymbal 1 (49)
+RIDE  = RIDE_1   # Ride Cymbal 1 (51)
+
+GM_DRUM_PRIMARY_ALIASES: typing.Final[dict[str, int]] = {
+	"kick":  KICK_1,
+	"snare": SNARE_1,
+	"crash": CRASH_1,
+	"ride":  RIDE_1,
+}