Decouple Song from MIDI protocol with new MidiCompiler, Song is now a pure data container for musical intent, legacy API preserved with deprecation warnings for backward compatibility

Author: cainky

midigen/__init__.py

@@ -10,3 +10,5 @@
 from .instruments import INSTRUMENT_MAP
 from .time_utils import TimeConverter
 from .melody import Melody
+from .channel_pool import ChannelPool, ChannelExhaustedError
+from .compiler import MidiCompiler

midigen/channel_pool.py

@@ -0,0 +1,165 @@
+"""
+MIDI Channel Pool Manager.
+
+MIDI has 16 channels (0-15). Channel 9 is reserved for percussion
+per General MIDI specification. This module manages channel allocation
+to prevent channel overflow and ensure correct drum channel usage.
+"""
+
+from typing import Set, Dict, Optional
+
+
+class ChannelExhaustedError(Exception):
+    """Raised when no MIDI channels are available for allocation."""
+    pass
+
+
+class ChannelPool:
+    """
+    Manages MIDI channel allocation for instruments.
+
+    MIDI has 16 channels (0-15). Channel 9 is reserved for percussion
+    per General MIDI specification. This pool manages melodic channel
+    allocation and provides the drum channel separately.
+
+    Example:
+        >>> pool = ChannelPool()
+        >>> piano_ch = pool.allocate("Piano")  # Returns 0
+        >>> bass_ch = pool.allocate("Bass")    # Returns 1
+        >>> drums_ch = pool.allocate_drums()   # Returns 9
+        >>> pool.release("Piano")              # Channel 0 available again
+    """
+
+    DRUM_CHANNEL = 9
+    MAX_CHANNELS = 16
+    MELODIC_CHANNELS = set(range(MAX_CHANNELS)) - {DRUM_CHANNEL}
+
+    def __init__(self):
+        """Initialize the channel pool with all melodic channels available."""
+        self._available: Set[int] = self.MELODIC_CHANNELS.copy()
+        self._allocated: Dict[str, int] = {}  # instrument_name -> channel
+        self._drums_allocated: bool = False
+
+    def allocate(self, instrument_name: str) -> int:
+        """
+        Allocate a channel for an instrument.
+
+        If the instrument has already been allocated a channel, returns
+        the same channel (idempotent).
+
+        Args:
+            instrument_name: Unique name/identifier for the instrument.
+
+        Returns:
+            Channel number (0-15, excluding 9).
+
+        Raises:
+            ChannelExhaustedError: If all 15 melodic channels are in use.
+
+        Example:
+            >>> pool = ChannelPool()
+            >>> pool.allocate("Acoustic Grand Piano")
+            0
+            >>> pool.allocate("Electric Bass")
+            1
+        """
+        # Return existing allocation if instrument already has a channel
+        if instrument_name in self._allocated:
+            return self._allocated[instrument_name]
+
+        if not self._available:
+            raise ChannelExhaustedError(
+                f"All {len(self.MELODIC_CHANNELS)} melodic channels exhausted. "
+                f"MIDI supports max 15 melodic instruments + 1 drum channel. "
+                f"Currently allocated: {list(self._allocated.keys())}"
+            )
+
+        # Prefer lower channels for predictability
+        channel = min(self._available)
+        self._available.remove(channel)
+        self._allocated[instrument_name] = channel
+        return channel
+
+    def allocate_drums(self) -> int:
+        """
+        Return the drum channel (always 9).
+
+        The drum channel is separate from the melodic pool and can be
+        allocated independently.
+
+        Returns:
+            The drum channel (9).
+
+        Example:
+            >>> pool = ChannelPool()
+            >>> pool.allocate_drums()
+            9
+        """
+        self._drums_allocated = True
+        return self.DRUM_CHANNEL
+
+    def release(self, instrument_name: str) -> None:
+        """
+        Release a channel back to the pool.
+
+        Args:
+            instrument_name: The instrument to release.
+
+        Note:
+            Releasing an unallocated instrument is a no-op.
+        """
+        if instrument_name in self._allocated:
+            channel = self._allocated.pop(instrument_name)
+            self._available.add(channel)
+
+    def release_drums(self) -> None:
+        """Release the drum channel."""
+        self._drums_allocated = False
+
+    def get_channel(self, instrument_name: str) -> Optional[int]:
+        """
+        Get the channel allocated to an instrument without allocating.
+
+        Args:
+            instrument_name: The instrument to look up.
+
+        Returns:
+            The channel number, or None if not allocated.
+        """
+        return self._allocated.get(instrument_name)
+
+    def is_allocated(self, instrument_name: str) -> bool:
+        """Check if an instrument has been allocated a channel."""
+        return instrument_name in self._allocated
+
+    def is_drums_allocated(self) -> bool:
+        """Check if the drum channel has been allocated."""
+        return self._drums_allocated
+
+    @property
+    def available_count(self) -> int:
+        """Number of melodic channels still available."""
+        return len(self._available)
+
+    @property
+    def allocated_count(self) -> int:
+        """Number of melodic channels currently allocated."""
+        return len(self._allocated)
+
+    @property
+    def allocated_instruments(self) -> Dict[str, int]:
+        """Copy of the instrument -> channel mapping."""
+        return self._allocated.copy()
+
+    def reset(self) -> None:
+        """Reset the pool to initial state (all channels available)."""
+        self._available = self.MELODIC_CHANNELS.copy()
+        self._allocated.clear()
+        self._drums_allocated = False
+
+    def __repr__(self) -> str:
+        return (
+            f"ChannelPool(available={self.available_count}, "
+            f"allocated={self.allocated_count}, "
+            f"drums={'allocated' if self._drums_allocated else 'free'})"
+        )

midigen/chord.py

@@ -1,8 +1,8 @@
 from typing import List
 from midigen.note import Note
 from midigen.key import KEY_MAP, Key
+from midigen.roman import get_chord_pitches
 from enum import Enum
-import music21
 
 
 class Chord:
@@ -307,29 +307,35 @@ def from_roman_numerals(
         duration: int = 480,
         time_per_chord: int = 0
     ):
-        m21_key = music21.key.Key(key.name, key.mode)
+        """
+        Create a chord progression from Roman numeral notation.
+
+        Args:
+            key: The key for the progression (e.g., Key("C", "major"))
+            progression_string: Dash-separated Roman numerals (e.g., "I-V-vi-IV")
+            octave: Base octave for the chords (default 4)
+            duration: Duration of each note in ticks (default 480)
+            time_per_chord: Time between chord starts in ticks (default 0)
+
+        Returns:
+            ChordProgression containing the parsed chords.
+        """
         roman_numerals = progression_string.split('-')
         chords = []
         current_time = 0
+
         for rn_str in roman_numerals:
-            rn = music21.roman.RomanNumeral(rn_str, m21_key)
-            pitches = rn.pitches
+            # Use native parser to get MIDI pitches
+            pitches = get_chord_pitches(key.name, key.mode, rn_str, octave=octave)
+
             notes = []
-            for i, pitch in enumerate(pitches):
-                note_name = f"{pitch.nameWithOctave}"
-                # A simple way to handle octave, might need refinement
-                note_name_without_octave = ''.join(filter(str.isalpha, pitch.name))
-                full_note_name = f"{note_name_without_octave}{octave}"
-                midi_pitch = KEY_MAP.get(full_note_name)
-
-                # If the note is not in the current octave, try the next one
-                if midi_pitch is None:
-                    full_note_name = f"{note_name_without_octave}{octave + 1}"
-                    midi_pitch = KEY_MAP.get(full_note_name)
-
-                if midi_pitch:
-                    # All notes in the chord start at the same time (current_time)
-                    notes.append(Note(pitch=midi_pitch, velocity=64, duration=duration, time=current_time))
+            for midi_pitch in pitches:
+                notes.append(Note(
+                    pitch=midi_pitch,
+                    velocity=64,
+                    duration=duration,
+                    time=current_time
+                ))
 
             if notes:
                 chords.append(Chord(notes))

midigen/compiler/__init__.py

@@ -0,0 +1,10 @@
+"""
+Compiler package for transforming musical intent into MIDI protocol.
+
+This package bridges the gap between high-level musical concepts
+(songs, sections, progressions) and low-level MIDI implementation.
+"""
+
+from .midi_compiler import MidiCompiler
+
+__all__ = ["MidiCompiler"]