- Use new external PyMidiDefs for canonical MIDI definitions

Author: Simon Holliday

README.md

@@ -2599,7 +2599,9 @@ Turns real-time International Space Station telemetry into an evolving compositi
 - `subsequence.constants.durations` provides beat-based duration constants. Import as `import subsequence.constants.durations as dur` and write `length = 9 * dur.SIXTEENTH` or `step = dur.DOTTED_EIGHTH` instead of raw floats. Constants: `THIRTYSECOND`, `SIXTEENTH`, `DOTTED_SIXTEENTH`, `TRIPLET_EIGHTH`, `EIGHTH`, `DOTTED_EIGHTH`, `TRIPLET_QUARTER`, `QUARTER`, `DOTTED_QUARTER`, `HALF`, `DOTTED_HALF`, `WHOLE`.
 - `subsequence.constants.velocity` provides MIDI velocity constants. `DEFAULT_VELOCITY = 100` (most notes), `DEFAULT_CHORD_VELOCITY = 90` (harmonic content), `VELOCITY_SHAPE_LOW = 64` and `VELOCITY_SHAPE_HIGH = 127` (velocity shaping boundaries), `MIN_VELOCITY = 0`, `MAX_VELOCITY = 127`.
 - `subsequence.constants.gm_drums` provides the General MIDI Level 1 drum note map. `GM_DRUM_MAP` can be passed as `drum_note_map`; individual constants like `KICK_1` are also available.
-- `subsequence.constants.midi_notes` provides named MIDI note constants C0–G9 (MIDI 12–127). Import as `import subsequence.constants.midi_notes as notes`. Convention: `C4 = 60` (Middle C, MMA standard). Naturals: `C4`, `D4`, … `B4`. Sharps: `CS4` (C♯4), `DS4`, `FS4`, `GS4`, `AS4`. Use instead of raw integers: `root = notes.E2` (40), `p.note(notes.A4)` (69).
+- `subsequence.constants.instruments.gm_instruments` provides all 128 General MIDI Level 1 instrument program numbers. `GM_INSTRUMENT_MAP` for string lookup, `GM_INSTRUMENT_NAMES` for display, `GM_FAMILIES` for family ranges, and individual constants like `VIOLIN`, `FLUTE`, etc.
+- `subsequence.constants.midi_notes` provides named MIDI note constants C_NEG1–G9 (MIDI 0–127). Import as `import subsequence.constants.midi_notes as notes`. Convention: `C4 = 60` (Middle C, MMA standard). Naturals: `C4`, `D4`, … `B4`. Sharps: `CS4` (C♯4), `DS4`, `FS4`, `GS4`, `AS4`. Also provides `note_to_name(60) → "C4"` and `name_to_note("Db4") → 61`. Use instead of raw integers: `root = notes.E2` (40), `p.note(notes.A4)` (69).
+- `subsequence.constants.midi_cc` provides named MIDI CC constants (0–127). Import as `import subsequence.constants.midi_cc as cc`. Constants: `FILTER_CUTOFF` (74), `SUSTAIN_PEDAL` (64), `MODULATION_WHEEL` (1), `VOLUME` (7), `PAN` (10), `ALL_NOTES_OFF` (123), etc. `GM_CC_MAP` dict for string lookup.
 - `subsequence.constants.pulses` provides pulse-based MIDI timing constants used internally by the engine.
 
 ### Infrastructure
@@ -2681,6 +2683,7 @@ Subsequence makes use of these excellent open-source libraries:
 | [mido ↗](https://github.com/mido/mido) | MIDI message handling and file I/O | MIT |
 | [python-rtmidi ↗](https://github.com/SpotlightKid/python-rtmidi) | Real-time MIDI I/O | MIT |
 | [python-osc ↗](https://github.com/attwad/python-osc) | OSC protocol support | Unlicense |
+| [pymididefs ↗](https://github.com/simonholliday/PyMidiDefs) | Canonical MIDI 1.0/2.0 constant definitions | MIT |
 | [websockets ↗](https://github.com/python-websockets/websockets) | Web UI dashboard communication | BSD-3-Clause |
 | [aalink ↗](https://github.com/artfwo/aalink) *(optional)* | Ableton Link integration | GPL-3.0 |
 

pyproject.toml

@@ -19,6 +19,7 @@ dependencies = [
     "python-rtmidi",
     "python-osc",
     "websockets",
+    "pymididefs @ git+https://github.com/simonholliday/PyMidiDefs.git",
 ]
 
 [project.urls]

subsequence/constants/instruments/gm_drums.py

@@ -23,144 +23,10 @@ def drums (p):
        @composition.pattern(channel=9, length=4)
        def drums (p):
            p.hit_steps(subsequence.constants.instruments.gm_drums.KICK_1, [0, 4, 8, 12], velocity=127)
-"""
-
-import typing
-
-
-# ─── Individual note constants ───────────────────────────────────────
-#
-# General MIDI Level 1 percussion key map (notes 27-87).
-# Names follow the GM specification with underscores for readability.
 
-HIGH_Q = 27
-SLAP = 28
-SCRATCH_PUSH = 29
-SCRATCH_PULL = 30
-STICKS = 31
-SQUARE_CLICK = 32
-METRONOME_CLICK = 33
-METRONOME_BELL = 34
-KICK_2 = 35
-KICK_1 = 36
-SIDE_STICK = 37
-SNARE_1 = 38
-HAND_CLAP = 39
-SNARE_2 = 40
-LOW_FLOOR_TOM = 41
-HI_HAT_CLOSED = 42
-HIGH_FLOOR_TOM = 43
-HI_HAT_PEDAL = 44
-LOW_TOM = 45
-HI_HAT_OPEN = 46
-LOW_MID_TOM = 47
-HIGH_MID_TOM = 48
-CRASH_1 = 49
-HIGH_TOM = 50
-RIDE_1 = 51
-CHINESE_CYMBAL = 52
-RIDE_BELL = 53
-TAMBOURINE = 54
-SPLASH_CYMBAL = 55
-COWBELL = 56
-CRASH_2 = 57
-VIBRASLAP = 58
-RIDE_2 = 59
-HIGH_BONGO = 60
-LOW_BONGO = 61
-MUTE_HIGH_CONGA = 62
-OPEN_HIGH_CONGA = 63
-LOW_CONGA = 64
-HIGH_TIMBALE = 65
-LOW_TIMBALE = 66
-HIGH_AGOGO = 67
-LOW_AGOGO = 68
-CABASA = 69
-MARACAS = 70
-SHORT_WHISTLE = 71
-LONG_WHISTLE = 72
-SHORT_GUIRO = 73
-LONG_GUIRO = 74
-CLAVES = 75
-HIGH_WOODBLOCK = 76
-LOW_WOODBLOCK = 77
-MUTE_CUICA = 78
-OPEN_CUICA = 79
-MUTE_TRIANGLE = 80
-OPEN_TRIANGLE = 81
-SHAKER = 82
-JINGLE_BELL = 83
-BELL_TREE = 84
-CASTANETS = 85
-MUTE_SURDO = 86
-OPEN_SURDO = 87
-
-
-# ─── Complete drum note map ──────────────────────────────────────────
-#
-# Pass this dict as the drum_note_map parameter to use string names
-# in hit_steps(), hit(), note(), euclidean(), and bresenham().
+Canonical source: `pymididefs <https://github.com/simonholliday/PyMidiDefs>`_.
+"""
 
-GM_DRUM_MAP: typing.Dict[str, int] = {
-	"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_2": KICK_2,
-	"kick_1": KICK_1,
-	"side_stick": SIDE_STICK,
-	"snare_1": SNARE_1,
-	"hand_clap": HAND_CLAP,
-	"snare_2": SNARE_2,
-	"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,
-	"crash_1": CRASH_1,
-	"high_tom": HIGH_TOM,
-	"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,
-	"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,
-	"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,
-	"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,
-}
+# Re-export everything from pymididefs.drums — all drum constants and the lookup dict.
+from pymididefs.drums import *  # noqa: F401,F403
+from pymididefs.drums import GM_DRUM_MAP  # noqa: F401 — explicit re-export for type checkers

subsequence/constants/instruments/gm_instruments.py

@@ -0,0 +1,32 @@
+"""General MIDI Level 1 instrument program numbers.
+
+All 128 GM Level 1 instrument assignments, organised into 16 families of 8.
+Use these constants with ``p.program_change()`` to select instruments on
+GM-compatible synthesizers and sound modules.
+
+Usage::
+
+    import subsequence.constants.instruments.gm_instruments as gm
+
+    @composition.pattern(channel=1, length=4)
+    def strings (p):
+        p.program_change(gm.VIOLIN)
+        p.note(60, beat=0)
+
+    # Lookup by name
+    gm.GM_INSTRUMENT_MAP["flute"]        # 73
+    gm.GM_INSTRUMENT_NAMES[73]           # "Flute"
+
+    # Family ranges
+    gm.GM_FAMILIES["piano"]              # (0, 7)
+
+Canonical source: `pymididefs <https://github.com/simonholliday/PyMidiDefs>`_.
+"""
+
+# Re-export everything from pymididefs.gm — all instrument constants and lookup tables.
+from pymididefs.gm import *  # noqa: F401,F403
+from pymididefs.gm import (  # noqa: F401 — explicit re-exports for type checkers
+	GM_FAMILIES,
+	GM_INSTRUMENT_MAP,
+	GM_INSTRUMENT_NAMES,
+)

subsequence/constants/midi_cc.py

@@ -8,163 +8,30 @@
 1. **As constants** - reference CC numbers directly when sending raw MIDI or mapping features::
 
 	import subsequence.constants.midi_cc as cc
-	
+
 	@composition.pattern(...)
 	def sweep (p):
 		p.cc(cc.FILTER_CUTOFF, 127)
 
 2. **As a lookup map** - pass ``GM_CC_MAP`` if you want to allow string-based mapping in your extensions::
 
 	print(subsequence.constants.midi_cc.GM_CC_MAP["filter_cutoff"]) # 74
+
+Canonical source: `pymididefs <https://github.com/simonholliday/PyMidiDefs>`_.
 """
 
 import typing
 
-# ─── Common Continuous Controllers (MSB) ─────────────────────────────
-BANK_SELECT_MSB = 0
-MODULATION_WHEEL = 1
-BREATH_CONTROLLER = 2
-FOOT_CONTROLLER = 4
-PORTAMENTO_TIME = 5
-DATA_ENTRY_MSB = 6
-VOLUME = 7
-BALANCE = 8
-PAN = 10
-EXPRESSION = 11
-EFFECT_CONTROL_1 = 12
-EFFECT_CONTROL_2 = 13
-
-# ─── General Purpose Controllers (MSB) ───────────────────────────────
-GENERAL_PURPOSE_1 = 16
-GENERAL_PURPOSE_2 = 17
-GENERAL_PURPOSE_3 = 18
-GENERAL_PURPOSE_4 = 19
-
-# ─── Common Continuous Controllers (LSB) ─────────────────────────────
-BANK_SELECT_LSB = 32
-MODULATION_WHEEL_LSB = 33
-BREATH_CONTROLLER_LSB = 34
-FOOT_PEDAL_LSB = 36
-PORTAMENTO_TIME_LSB = 37
-DATA_ENTRY_LSB = 38
-
-# ─── On/Off Switches (0-63=Off, 64-127=On) ───────────────────────────
-SUSTAIN_PEDAL = 64
-PORTAMENTO_ON_OFF = 65
-SOSTENUTO_PEDAL = 66
-SOFT_PEDAL = 67
-LEGATO_PEDAL = 68
-HOLD_2 = 69
-
-# ─── Sound Controllers ───────────────────────────────────────────────
-SOUND_VARIATION = 70
-FILTER_RESONANCE = 71
-RELEASE_TIME = 72
-ATTACK_TIME = 73
-FILTER_CUTOFF = 74
-SOUND_CONTROL_6 = 75
-SOUND_CONTROL_7 = 76
-SOUND_CONTROL_8 = 77
-SOUND_CONTROL_9 = 78
-SOUND_CONTROL_10 = 79
-
-# ─── General Purpose Controllers (LSB) ───────────────────────────────
-GENERAL_PURPOSE_5 = 80
-GENERAL_PURPOSE_6 = 81
-GENERAL_PURPOSE_7 = 82
-GENERAL_PURPOSE_8 = 83
-
-# ─── Effect Controllers ──────────────────────────────────────────────
-PORTAMENTO_CONTROL = 84
-REVERB_DEPTH = 91
-TREMOLO_DEPTH = 92
-CHORUS_DEPTH = 93
-CELESTE_DEPTH = 94
-PHASER_DEPTH = 95
-
-# ─── Parameter Control ───────────────────────────────────────────────
-DATA_INCREMENT = 96
-DATA_DECREMENT = 97
-NRPN_LSB = 98
-NRPN_MSB = 99
-RPN_LSB = 100
-RPN_MSB = 101
-
-# ─── Channel Mode Messages ───────────────────────────────────────────
-ALL_SOUND_OFF = 120
-RESET_ALL_CONTROLLERS = 121
-LOCAL_CONTROL_ON_OFF = 122
-ALL_NOTES_OFF = 123
-OMNI_MODE_OFF = 124
-OMNI_MODE_ON = 125
-MONO_MODE_ON = 126
-POLY_MODE_ON = 127
+# Re-export everything from pymididefs.cc — all CC constants and the lookup dict.
+from pymididefs.cc import *  # noqa: F401,F403
+from pymididefs.cc import CC_MAP  # noqa: F401
 
-# ─── Complete CC map ─────────────────────────────────────────────────
-#
-# Pass this dict to map string names to CC integers if needed.
+# ─── Backward-compatibility aliases ─────────────────────────────────────────
+# Subsequence used FOOT_PEDAL_LSB; pymididefs uses FOOT_CONTROLLER_LSB.
+FOOT_PEDAL_LSB = FOOT_CONTROLLER_LSB  # noqa: F405
 
+# Subsequence exposed the lookup dict as GM_CC_MAP; pymididefs uses CC_MAP.
 GM_CC_MAP: typing.Dict[str, int] = {
-	"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,
-	"bank_select_lsb": BANK_SELECT_LSB,
-	"modulation_wheel_lsb": MODULATION_WHEEL_LSB,
-	"breath_controller_lsb": BREATH_CONTROLLER_LSB,
+	**CC_MAP,
 	"foot_pedal_lsb": FOOT_PEDAL_LSB,
-	"portamento_time_lsb": PORTAMENTO_TIME_LSB,
-	"data_entry_lsb": DATA_ENTRY_LSB,
-	"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_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_5": GENERAL_PURPOSE_5,
-	"general_purpose_6": GENERAL_PURPOSE_6,
-	"general_purpose_7": GENERAL_PURPOSE_7,
-	"general_purpose_8": GENERAL_PURPOSE_8,
-	"portamento_control": PORTAMENTO_CONTROL,
-	"reverb_depth": REVERB_DEPTH,
-	"tremolo_depth": TREMOLO_DEPTH,
-	"chorus_depth": CHORUS_DEPTH,
-	"celeste_depth": CELESTE_DEPTH,
-	"phaser_depth": PHASER_DEPTH,
-	"data_increment": DATA_INCREMENT,
-	"data_decrement": DATA_DECREMENT,
-	"nrpn_lsb": NRPN_LSB,
-	"nrpn_msb": NRPN_MSB,
-	"rpn_lsb": RPN_LSB,
-	"rpn_msb": RPN_MSB,
-	"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,
 }