midi_drums

MIDI Drums - Comprehensive drum track generation system.

View Source

 1"""MIDI Drums - Comprehensive drum track generation system."""
 2
 3from midi_drums.core.models.pattern import Beat, Pattern
 4from midi_drums.core.models.song import Section, Song
 5from midi_drums.core.value_objects.generation_parameters import (
 6    GenerationParameters,
 7)
 8from midi_drums.core.value_objects.time_signature import TimeSignature
 9from midi_drums.generation.engines.drum_generator import DrumGenerator
10
11__version__ = "0.4.0-alpha.1"
12__all__ = [
13    "DrumGenerator",
14    "Pattern",
15    "Beat",
16    "TimeSignature",
17    "Song",
18    "Section",
19    "GenerationParameters",
20]

@dataclass

class Pattern: View Source

 58@dataclass
 59class Pattern:
 60    """Complete drum pattern with timing and metadata."""
 61
 62    name: str
 63    beats: list[Beat] = field(default_factory=list)
 64    time_signature: TimeSignature = field(default_factory=TimeSignature)
 65    subdivision: int = 16  # 16th note resolution
 66    swing_ratio: float = 0.0  # 0.0 = straight, 0.5 = triplet swing
 67    metadata: dict[str, Any] = field(default_factory=dict)
 68
 69    def add_beat(
 70        self,
 71        position: float,
 72        instrument: DrumInstrument,
 73        velocity: int = 100,
 74        **kwargs,
 75    ) -> "Pattern":
 76        """Add a beat to the pattern."""
 77        beat = Beat(
 78            position=position,
 79            instrument=instrument,
 80            velocity=velocity,
 81            **kwargs,
 82        )
 83        self.beats.append(beat)
 84        return self
 85
 86    def get_beats_at_position(
 87        self, position: float, tolerance: float = 0.01
 88    ) -> list[Beat]:
 89        """Get all beats at a specific position."""
 90        return [
 91            beat
 92            for beat in self.beats
 93            if abs(beat.position - position) <= tolerance
 94        ]
 95
 96    def get_beats_by_instrument(self, instrument: DrumInstrument) -> list[Beat]:
 97        """Get all beats for a specific instrument."""
 98        return [beat for beat in self.beats if beat.instrument == instrument]
 99
100    def duration_bars(self) -> float:
101        """Calculate pattern duration in bars."""
102        if not self.beats:
103            return 1.0
104        max_position = max(beat.position for beat in self.beats)
105        return max(
106            1.0, (max_position + 1.0) / self.time_signature.beats_per_bar
107        )
108
109    def humanize(
110        self, timing_variance: float = 0.02, velocity_variance: float = 10
111    ) -> "Pattern":
112        """Apply humanization to timing and velocity."""
113        humanized_beats = []
114        for beat in self.beats:
115            # Add slight timing variations
116            timing_offset = random.uniform(-timing_variance, timing_variance)
117            new_position = max(0, beat.position + timing_offset)
118
119            # Add velocity variations
120            velocity_offset = random.randint(
121                -velocity_variance, velocity_variance
122            )
123            new_velocity = max(1, min(127, beat.velocity + velocity_offset))
124
125            humanized_beat = Beat(
126                position=new_position,
127                instrument=beat.instrument,
128                velocity=new_velocity,
129                duration=beat.duration,
130                ghost_note=beat.ghost_note,
131                accent=beat.accent,
132                instrument_promoted=beat.instrument_promoted,
133            )
134            humanized_beats.append(humanized_beat)
135
136        return Pattern(
137            name=f"{self.name}_humanized",
138            beats=humanized_beats,
139            time_signature=self.time_signature,
140            subdivision=self.subdivision,
141            swing_ratio=self.swing_ratio,
142            metadata={**self.metadata, "humanized": True},
143        )
144
145    def copy(self) -> "Pattern":
146        """Create a deep copy of the pattern.
147
148        Logs warning if pattern has no beats to aid debugging.
149        """
150        if not self.beats:
151            logger.warning(
152                f"Pattern '{self.name}' has no beats - copying empty pattern. "
153                "This may cause issues with drummer plugins."
154            )
155
156        return Pattern(
157            name=self.name,
158            beats=[
159                Beat(
160                    position=beat.position,
161                    instrument=beat.instrument,
162                    velocity=beat.velocity,
163                    duration=beat.duration,
164                    ghost_note=beat.ghost_note,
165                    accent=beat.accent,
166                    instrument_promoted=beat.instrument_promoted,
167                )
168                for beat in self.beats
169            ],
170            time_signature=TimeSignature(
171                self.time_signature.numerator, self.time_signature.denominator
172            ),
173            subdivision=self.subdivision,
174            swing_ratio=self.swing_ratio,
175            metadata=self.metadata.copy(),
176        )

Complete drum pattern with timing and metadata.

Pattern( name: str, beats: list[Beat] = <factory>, time_signature: TimeSignature = <factory>, subdivision: int = 16, swing_ratio: float = 0.0, metadata: dict[str, typing.Any] = <factory>)

beats: list[Beat]

time_signature: TimeSignature

subdivision: int = 16

swing_ratio: float = 0.0

metadata: dict[str, typing.Any]

def add_beat( self, position: float, instrument: midi_drums.core.value_objects.drum_instrument.DrumInstrument, velocity: int = 100, **kwargs) -> Pattern: View Source

69    def add_beat(
70        self,
71        position: float,
72        instrument: DrumInstrument,
73        velocity: int = 100,
74        **kwargs,
75    ) -> "Pattern":
76        """Add a beat to the pattern."""
77        beat = Beat(
78            position=position,
79            instrument=instrument,
80            velocity=velocity,
81            **kwargs,
82        )
83        self.beats.append(beat)
84        return self

Add a beat to the pattern.

def get_beats_at_position( self, position: float, tolerance: float = 0.01) -> list[Beat]: View Source

86    def get_beats_at_position(
87        self, position: float, tolerance: float = 0.01
88    ) -> list[Beat]:
89        """Get all beats at a specific position."""
90        return [
91            beat
92            for beat in self.beats
93            if abs(beat.position - position) <= tolerance
94        ]

Get all beats at a specific position.

def get_beats_by_instrument( self, instrument: midi_drums.core.value_objects.drum_instrument.DrumInstrument) -> list[Beat]: View Source

96    def get_beats_by_instrument(self, instrument: DrumInstrument) -> list[Beat]:
97        """Get all beats for a specific instrument."""
98        return [beat for beat in self.beats if beat.instrument == instrument]

Get all beats for a specific instrument.

def duration_bars(self) -> float: View Source

100    def duration_bars(self) -> float:
101        """Calculate pattern duration in bars."""
102        if not self.beats:
103            return 1.0
104        max_position = max(beat.position for beat in self.beats)
105        return max(
106            1.0, (max_position + 1.0) / self.time_signature.beats_per_bar
107        )

Calculate pattern duration in bars.

def humanize( self, timing_variance: float = 0.02, velocity_variance: float = 10) -> Pattern: View Source

109    def humanize(
110        self, timing_variance: float = 0.02, velocity_variance: float = 10
111    ) -> "Pattern":
112        """Apply humanization to timing and velocity."""
113        humanized_beats = []
114        for beat in self.beats:
115            # Add slight timing variations
116            timing_offset = random.uniform(-timing_variance, timing_variance)
117            new_position = max(0, beat.position + timing_offset)
118
119            # Add velocity variations
120            velocity_offset = random.randint(
121                -velocity_variance, velocity_variance
122            )
123            new_velocity = max(1, min(127, beat.velocity + velocity_offset))
124
125            humanized_beat = Beat(
126                position=new_position,
127                instrument=beat.instrument,
128                velocity=new_velocity,
129                duration=beat.duration,
130                ghost_note=beat.ghost_note,
131                accent=beat.accent,
132                instrument_promoted=beat.instrument_promoted,
133            )
134            humanized_beats.append(humanized_beat)
135
136        return Pattern(
137            name=f"{self.name}_humanized",
138            beats=humanized_beats,
139            time_signature=self.time_signature,
140            subdivision=self.subdivision,
141            swing_ratio=self.swing_ratio,
142            metadata={**self.metadata, "humanized": True},
143        )

Apply humanization to timing and velocity.

def copy(self) -> Pattern: View Source

145    def copy(self) -> "Pattern":
146        """Create a deep copy of the pattern.
147
148        Logs warning if pattern has no beats to aid debugging.
149        """
150        if not self.beats:
151            logger.warning(
152                f"Pattern '{self.name}' has no beats - copying empty pattern. "
153                "This may cause issues with drummer plugins."
154            )
155
156        return Pattern(
157            name=self.name,
158            beats=[
159                Beat(
160                    position=beat.position,
161                    instrument=beat.instrument,
162                    velocity=beat.velocity,
163                    duration=beat.duration,
164                    ghost_note=beat.ghost_note,
165                    accent=beat.accent,
166                    instrument_promoted=beat.instrument_promoted,
167                )
168                for beat in self.beats
169            ],
170            time_signature=TimeSignature(
171                self.time_signature.numerator, self.time_signature.denominator
172            ),
173            subdivision=self.subdivision,
174            swing_ratio=self.swing_ratio,
175            metadata=self.metadata.copy(),
176        )

Create a deep copy of the pattern.

Logs warning if pattern has no beats to aid debugging.

@dataclass

class Beat: View Source

15@dataclass
16class Beat:
17    """Individual drum hit within a pattern.
18
19    ``instrument_promoted`` is provenance, not a playing instruction: it is
20    True only when this beat's ``instrument`` was changed in place by
21    ``GenrePlugin._apply_ride_hihat_logic`` promoting an existing hi-hat
22    beat to a higher-energy cymbal for a high-energy section (issue #18).
23    A cymbal beat placed directly by a pattern template/genre style (e.g.
24    ``CrashAccents``) is never promoted and always carries the default
25    False, even though its ``instrument`` may be the exact same cymbal a
26    promotion would have chosen. This lets drummer modifications that only
27    care about "the timekeeping cymbal" - PocketStretching,
28    MinimalCreativity, SpeedPrecision in
29    ``midi_drums.modifications.drummer_mods`` - tell a promoted timekeeping
30    beat apart from a genuinely-placed accent of the same instrument
31    (issue #36 item 1), instead of matching on instrument type alone.
32
33    Every call site that reconstructs a Beat from an existing one (
34    ``Pattern.copy()``, ``Pattern.humanize()``, and the drummer
35    modification/humanization pipelines) must carry this field forward
36    explicitly - dataclass field-by-field reconstruction does not do this
37    automatically, and a dropped flag silently falls back to False.
38    """
39
40    position: float  # Beat position (0.0-4.0 for 4/4)
41    instrument: DrumInstrument
42    velocity: int = 100  # MIDI velocity 0-127
43    duration: float = 0.25  # Note duration in beats
44    ghost_note: bool = False  # Quiet accent note
45    accent: bool = False  # Emphasized note
46    instrument_promoted: bool = False  # True if instrument was promoted
47
48    def __post_init__(self):
49        """Validate beat parameters."""
50        if not 0 <= self.velocity <= 127:
51            raise ValueError(f"Velocity must be 0-127, got {self.velocity}")
52        if self.position < 0:
53            raise ValueError(
54                f"Position cannot be negative, got {self.position}"
55            )

Individual drum hit within a pattern.

instrument_promoted is provenance, not a playing instruction: it is True only when this beat's instrument was changed in place by GenrePlugin._apply_ride_hihat_logic promoting an existing hi-hat beat to a higher-energy cymbal for a high-energy section (issue #18). A cymbal beat placed directly by a pattern template/genre style (e.g. CrashAccents) is never promoted and always carries the default False, even though its instrument may be the exact same cymbal a promotion would have chosen. This lets drummer modifications that only care about "the timekeeping cymbal" - PocketStretching, MinimalCreativity, SpeedPrecision in midi_drums.modifications.drummer_mods - tell a promoted timekeeping beat apart from a genuinely-placed accent of the same instrument (issue #36 item 1), instead of matching on instrument type alone.

Every call site that reconstructs a Beat from an existing one ( Pattern.copy(), Pattern.humanize(), and the drummer modification/humanization pipelines) must carry this field forward explicitly - dataclass field-by-field reconstruction does not do this automatically, and a dropped flag silently falls back to False.

Beat( position: float, instrument: midi_drums.core.value_objects.drum_instrument.DrumInstrument, velocity: int = 100, duration: float = 0.25, ghost_note: bool = False, accent: bool = False, instrument_promoted: bool = False)

position: float

instrument: midi_drums.core.value_objects.drum_instrument.DrumInstrument

velocity: int = 100

duration: float = 0.25

ghost_note: bool = False

accent: bool = False

instrument_promoted: bool = False

@dataclass

class TimeSignature: View Source

 7@dataclass
 8class TimeSignature:
 9    """Time signature representation."""
10
11    numerator: int = 4
12    denominator: int = 4
13
14    def __post_init__(self) -> None:
15        if self.numerator <= 0:
16            raise ValueError(
17                f"Time signature numerator must be positive, got "
18                f"{self.numerator}"
19            )
20        if self.denominator <= 0 or (
21            self.denominator & (self.denominator - 1) != 0
22        ):
23            raise ValueError(
24                f"Time signature denominator must be a positive power of "
25                f"two (1, 2, 4, 8, 16, ...), got {self.denominator}"
26            )
27
28    @property
29    def beats_per_bar(self) -> float:
30        return self.numerator * (4.0 / self.denominator)
31
32    def __str__(self) -> str:
33        return f"{self.numerator}/{self.denominator}"

Time signature representation.

TimeSignature(numerator: int = 4, denominator: int = 4)

numerator: int = 4

denominator: int = 4

beats_per_bar: float View Source

28    @property
29    def beats_per_bar(self) -> float:
30        return self.numerator * (4.0 / self.denominator)

@dataclass

class Song: View Source

164@dataclass
165class Song:
166    """Complete song structure with sections and global parameters."""
167
168    name: str
169    tempo: int = 120  # BPM
170    time_signature: TimeSignature = field(default_factory=TimeSignature)
171    sections: list[Section] = field(default_factory=list)
172    global_parameters: GenerationParameters | None = None
173    metadata: dict[str, Any] = field(default_factory=dict)
174
175    def __post_init__(self):
176        """Validate song parameters."""
177        if not 60 <= self.tempo <= 300:
178            raise ValueError(
179                f"Tempo must be between 60-300 BPM, got {self.tempo}"
180            )
181
182    def add_section(self, section: Section) -> "Song":
183        """Add a section to the song."""
184        self.sections.append(section)
185        return self
186
187    def total_bars(self) -> int:
188        """Calculate total number of bars in the song."""
189        return sum(section.bars for section in self.sections)
190
191    def total_duration_seconds(self) -> float:
192        """Calculate total song duration in seconds.
193
194        Accounts for per-segment tempo/time-signature overrides (see
195        SongSegment) - a section with no segments contributes
196        ``bars * time_signature.beats_per_bar / (tempo / 60)`` using the
197        song's global values, identical to the pre-segment calculation.
198        """
199        total_seconds = 0.0
200        for section in self.sections:
201            for bars, tempo, time_sig in section.resolved_bar_specs(
202                self.tempo, self.time_signature
203            ):
204                beats = bars * time_sig.beats_per_bar
205                total_seconds += beats / (tempo / 60.0)
206        return total_seconds
207
208    def section_start_times(self) -> list[float]:
209        """Return each section's start time in seconds.
210
211        Resolves per-segment tempo/time-signature overrides (see
212        SongSegment) the same way :meth:`total_duration_seconds` does, so
213        callers that need per-section positions (e.g. REAPER markers)
214        stay in sync with segmented songs instead of assuming a single
215        global tempo/time signature for the whole song.
216        """
217        times = []
218        elapsed = 0.0
219        for section in self.sections:
220            times.append(elapsed)
221            for bars, tempo, time_sig in section.resolved_bar_specs(
222                self.tempo, self.time_signature
223            ):
224                beats = bars * time_sig.beats_per_bar
225                elapsed += beats / (tempo / 60.0)
226        return times
227
228    def get_section_by_name(self, name: str) -> Section | None:
229        """Find first section with the given name."""
230        for section in self.sections:
231            if section.name == name:
232                return section
233        return None
234
235    def get_sections_by_name(self, name: str) -> list[Section]:
236        """Find all sections with the given name."""
237        return [section for section in self.sections if section.name == name]
238
239    @classmethod
240    def create_simple_structure(
241        cls,
242        name: str,
243        tempo: int = 120,
244        genre: str = "rock",
245        style: str = "default",
246    ) -> "Song":
247        """Create a song with basic verse-chorus structure."""
248        # Create placeholder patterns (will be generated by plugins)
249        verse_pattern = Pattern(f"{genre}_{style}_verse")
250        chorus_pattern = Pattern(f"{genre}_{style}_chorus")
251
252        song = cls(name=name, tempo=tempo)
253        song.global_parameters = GenerationParameters(genre=genre, style=style)
254
255        # Standard pop/rock structure
256        song.add_section(Section("intro", verse_pattern, bars=4))
257        song.add_section(Section("verse", verse_pattern, bars=8))
258        song.add_section(Section("chorus", chorus_pattern, bars=8))
259        song.add_section(Section("verse", verse_pattern, bars=8))
260        song.add_section(Section("chorus", chorus_pattern, bars=8))
261        song.add_section(Section("bridge", verse_pattern, bars=4))
262        song.add_section(Section("chorus", chorus_pattern, bars=8))
263        song.add_section(Section("outro", chorus_pattern, bars=4))
264
265        return song

Complete song structure with sections and global parameters.

Song( name: str, tempo: int = 120, time_signature: TimeSignature = <factory>, sections: list[Section] = <factory>, global_parameters: GenerationParameters | None = None, metadata: dict[str, typing.Any] = <factory>)

tempo: int = 120

time_signature: TimeSignature

sections: list[Section]

global_parameters: GenerationParameters | None = None

metadata: dict[str, typing.Any]

def add_section( self, section: Section) -> Song: View Source

182    def add_section(self, section: Section) -> "Song":
183        """Add a section to the song."""
184        self.sections.append(section)
185        return self

Add a section to the song.

def total_bars(self) -> int: View Source

187    def total_bars(self) -> int:
188        """Calculate total number of bars in the song."""
189        return sum(section.bars for section in self.sections)

Calculate total number of bars in the song.

def total_duration_seconds(self) -> float: View Source

191    def total_duration_seconds(self) -> float:
192        """Calculate total song duration in seconds.
193
194        Accounts for per-segment tempo/time-signature overrides (see
195        SongSegment) - a section with no segments contributes
196        ``bars * time_signature.beats_per_bar / (tempo / 60)`` using the
197        song's global values, identical to the pre-segment calculation.
198        """
199        total_seconds = 0.0
200        for section in self.sections:
201            for bars, tempo, time_sig in section.resolved_bar_specs(
202                self.tempo, self.time_signature
203            ):
204                beats = bars * time_sig.beats_per_bar
205                total_seconds += beats / (tempo / 60.0)
206        return total_seconds

Calculate total song duration in seconds.

Accounts for per-segment tempo/time-signature overrides (see SongSegment) - a section with no segments contributes bars * time_signature.beats_per_bar / (tempo / 60) using the song's global values, identical to the pre-segment calculation.

def section_start_times(self) -> list[float]: View Source

208    def section_start_times(self) -> list[float]:
209        """Return each section's start time in seconds.
210
211        Resolves per-segment tempo/time-signature overrides (see
212        SongSegment) the same way :meth:`total_duration_seconds` does, so
213        callers that need per-section positions (e.g. REAPER markers)
214        stay in sync with segmented songs instead of assuming a single
215        global tempo/time signature for the whole song.
216        """
217        times = []
218        elapsed = 0.0
219        for section in self.sections:
220            times.append(elapsed)
221            for bars, tempo, time_sig in section.resolved_bar_specs(
222                self.tempo, self.time_signature
223            ):
224                beats = bars * time_sig.beats_per_bar
225                elapsed += beats / (tempo / 60.0)
226        return times

Return each section's start time in seconds.

Resolves per-segment tempo/time-signature overrides (see SongSegment) the same way total_duration_seconds() does, so callers that need per-section positions (e.g. REAPER markers) stay in sync with segmented songs instead of assuming a single global tempo/time signature for the whole song.

def get_section_by_name(self, name: str) -> Section | None: View Source

228    def get_section_by_name(self, name: str) -> Section | None:
229        """Find first section with the given name."""
230        for section in self.sections:
231            if section.name == name:
232                return section
233        return None

Find first section with the given name.

def get_sections_by_name(self, name: str) -> list[Section]: View Source

235    def get_sections_by_name(self, name: str) -> list[Section]:
236        """Find all sections with the given name."""
237        return [section for section in self.sections if section.name == name]

Find all sections with the given name.

@classmethod

def create_simple_structure( cls, name: str, tempo: int = 120, genre: str = 'rock', style: str = 'default') -> Song: View Source

239    @classmethod
240    def create_simple_structure(
241        cls,
242        name: str,
243        tempo: int = 120,
244        genre: str = "rock",
245        style: str = "default",
246    ) -> "Song":
247        """Create a song with basic verse-chorus structure."""
248        # Create placeholder patterns (will be generated by plugins)
249        verse_pattern = Pattern(f"{genre}_{style}_verse")
250        chorus_pattern = Pattern(f"{genre}_{style}_chorus")
251
252        song = cls(name=name, tempo=tempo)
253        song.global_parameters = GenerationParameters(genre=genre, style=style)
254
255        # Standard pop/rock structure
256        song.add_section(Section("intro", verse_pattern, bars=4))
257        song.add_section(Section("verse", verse_pattern, bars=8))
258        song.add_section(Section("chorus", chorus_pattern, bars=8))
259        song.add_section(Section("verse", verse_pattern, bars=8))
260        song.add_section(Section("chorus", chorus_pattern, bars=8))
261        song.add_section(Section("bridge", verse_pattern, bars=4))
262        song.add_section(Section("chorus", chorus_pattern, bars=8))
263        song.add_section(Section("outro", chorus_pattern, bars=4))
264
265        return song

Create a song with basic verse-chorus structure.

@dataclass

class Section: View Source

 55@dataclass
 56class Section:
 57    """Song section (verse, chorus, etc.) with pattern and variations."""
 58
 59    name: str  # "verse", "chorus", "bridge", "breakdown", "intro", "outro"
 60    pattern: Pattern
 61    bars: int = 4
 62    variations: list[PatternVariation] = field(default_factory=list)
 63    fills: list[Fill] = field(default_factory=list)
 64    section_parameters: dict[str, Any] = field(default_factory=dict)
 65    segments: list[SongSegment] = field(default_factory=list)
 66
 67    def __post_init__(self):
 68        """Validate that segment bars (if any) account for the whole section."""
 69        if self.segments:
 70            segment_bars = sum(segment.bars for segment in self.segments)
 71            if segment_bars != self.bars:
 72                raise ValueError(
 73                    f"Section '{self.name}' segments sum to {segment_bars} "
 74                    f"bars but Section.bars is {self.bars}"
 75                )
 76
 77    def segment_for_bar(self, bar_number: int) -> SongSegment | None:
 78        """Return the segment covering local ``bar_number`` (0-indexed).
 79
 80        Returns None when this section has no segments - callers should
 81        treat that as "use the song's global tempo/time signature."
 82        """
 83        cursor = 0
 84        for segment in self.segments:
 85            if cursor <= bar_number < cursor + segment.bars:
 86                return segment
 87            cursor += segment.bars
 88        return None
 89
 90    def effective_tempo(self, bar_number: int, song_tempo: int) -> int:
 91        """Resolve the tempo that applies at ``bar_number``, inheriting
 92        ``song_tempo`` when this section has no segments or the covering
 93        segment doesn't override tempo."""
 94        segment = self.segment_for_bar(bar_number)
 95        if segment is None or segment.tempo is None:
 96            return song_tempo
 97        return segment.tempo
 98
 99    def effective_time_signature(
100        self, bar_number: int, song_time_signature: TimeSignature
101    ) -> TimeSignature:
102        """Resolve the time signature that applies at ``bar_number``,
103        inheriting ``song_time_signature`` when this section has no
104        segments or the covering segment doesn't override it."""
105        segment = self.segment_for_bar(bar_number)
106        if segment is None or segment.time_signature is None:
107            return song_time_signature
108        return segment.time_signature
109
110    def resolved_bar_specs(
111        self, song_tempo: int, song_time_signature: TimeSignature
112    ) -> list[tuple[int, int, TimeSignature]]:
113        """Return (bars, tempo, time_signature) triples for this section.
114
115        One triple per segment when this section has segments, resolving
116        each segment's ``tempo``/``time_signature`` override against the
117        given song-level defaults; otherwise a single triple for the
118        whole section using those defaults directly. Shared by every
119        caller that needs to walk a section's bars accounting for
120        per-segment overrides (duration, timeline export, song-map
121        export) so segment-resolution semantics live in one place.
122        """
123        if self.segments:
124            return [
125                (
126                    segment.bars,
127                    segment.tempo or song_tempo,
128                    segment.time_signature or song_time_signature,
129                )
130                for segment in self.segments
131            ]
132        return [(self.bars, song_tempo, song_time_signature)]
133
134    def get_effective_pattern(self, bar_number: int) -> Pattern:
135        """Get the pattern for a specific bar, considering variations."""
136        # Check if any variations should apply to this bar
137        for variation in self.variations:
138            if variation.bars is None or bar_number in variation.bars:
139                import random
140
141                if random.random() < variation.probability:
142                    return variation.pattern
143        return self.pattern
144
145    def should_add_fill(
146        self, bar_number: int, fill_frequency: float
147    ) -> Fill | None:
148        """Determine if a fill should be added at this bar."""
149        import random
150
151        if random.random() < fill_frequency and self.fills:
152            # Choose fill based on probabilities
153            total_prob = sum(fill.trigger_probability for fill in self.fills)
154            if total_prob > 0:
155                rand_val = random.random() * total_prob
156                current_sum = 0
157                for fill in self.fills:
158                    current_sum += fill.trigger_probability
159                    if rand_val <= current_sum:
160                        return fill
161        return None

Song section (verse, chorus, etc.) with pattern and variations.

Section( name: str, pattern: Pattern, bars: int = 4, variations: list[midi_drums.core.models.song.PatternVariation] = <factory>, fills: list[midi_drums.core.models.song.Fill] = <factory>, section_parameters: dict[str, typing.Any] = <factory>, segments: list[midi_drums.core.models.song.SongSegment] = <factory>)

pattern: Pattern

bars: int = 4

variations: list[midi_drums.core.models.song.PatternVariation]

fills: list[midi_drums.core.models.song.Fill]

section_parameters: dict[str, typing.Any]

segments: list[midi_drums.core.models.song.SongSegment]

def segment_for_bar(self, bar_number: int) -> midi_drums.core.models.song.SongSegment | None: View Source

77    def segment_for_bar(self, bar_number: int) -> SongSegment | None:
78        """Return the segment covering local ``bar_number`` (0-indexed).
79
80        Returns None when this section has no segments - callers should
81        treat that as "use the song's global tempo/time signature."
82        """
83        cursor = 0
84        for segment in self.segments:
85            if cursor <= bar_number < cursor + segment.bars:
86                return segment
87            cursor += segment.bars
88        return None

Return the segment covering local bar_number (0-indexed).

Returns None when this section has no segments - callers should treat that as "use the song's global tempo/time signature."

def effective_tempo(self, bar_number: int, song_tempo: int) -> int: View Source

90    def effective_tempo(self, bar_number: int, song_tempo: int) -> int:
91        """Resolve the tempo that applies at ``bar_number``, inheriting
92        ``song_tempo`` when this section has no segments or the covering
93        segment doesn't override tempo."""
94        segment = self.segment_for_bar(bar_number)
95        if segment is None or segment.tempo is None:
96            return song_tempo
97        return segment.tempo

Resolve the tempo that applies at bar_number, inheriting song_tempo when this section has no segments or the covering segment doesn't override tempo.

def effective_time_signature( self, bar_number: int, song_time_signature: TimeSignature) -> TimeSignature: View Source

 99    def effective_time_signature(
100        self, bar_number: int, song_time_signature: TimeSignature
101    ) -> TimeSignature:
102        """Resolve the time signature that applies at ``bar_number``,
103        inheriting ``song_time_signature`` when this section has no
104        segments or the covering segment doesn't override it."""
105        segment = self.segment_for_bar(bar_number)
106        if segment is None or segment.time_signature is None:
107            return song_time_signature
108        return segment.time_signature

Resolve the time signature that applies at bar_number, inheriting song_time_signature when this section has no segments or the covering segment doesn't override it.

def resolved_bar_specs( self, song_tempo: int, song_time_signature: TimeSignature) -> list[tuple[int, int, TimeSignature]]: View Source

110    def resolved_bar_specs(
111        self, song_tempo: int, song_time_signature: TimeSignature
112    ) -> list[tuple[int, int, TimeSignature]]:
113        """Return (bars, tempo, time_signature) triples for this section.
114
115        One triple per segment when this section has segments, resolving
116        each segment's ``tempo``/``time_signature`` override against the
117        given song-level defaults; otherwise a single triple for the
118        whole section using those defaults directly. Shared by every
119        caller that needs to walk a section's bars accounting for
120        per-segment overrides (duration, timeline export, song-map
121        export) so segment-resolution semantics live in one place.
122        """
123        if self.segments:
124            return [
125                (
126                    segment.bars,
127                    segment.tempo or song_tempo,
128                    segment.time_signature or song_time_signature,
129                )
130                for segment in self.segments
131            ]
132        return [(self.bars, song_tempo, song_time_signature)]

Return (bars, tempo, time_signature) triples for this section.

One triple per segment when this section has segments, resolving each segment's tempo/time_signature override against the given song-level defaults; otherwise a single triple for the whole section using those defaults directly. Shared by every caller that needs to walk a section's bars accounting for per-segment overrides (duration, timeline export, song-map export) so segment-resolution semantics live in one place.

def get_effective_pattern(self, bar_number: int) -> Pattern: View Source

134    def get_effective_pattern(self, bar_number: int) -> Pattern:
135        """Get the pattern for a specific bar, considering variations."""
136        # Check if any variations should apply to this bar
137        for variation in self.variations:
138            if variation.bars is None or bar_number in variation.bars:
139                import random
140
141                if random.random() < variation.probability:
142                    return variation.pattern
143        return self.pattern

Get the pattern for a specific bar, considering variations.

def should_add_fill( self, bar_number: int, fill_frequency: float) -> midi_drums.core.models.song.Fill | None: View Source

145    def should_add_fill(
146        self, bar_number: int, fill_frequency: float
147    ) -> Fill | None:
148        """Determine if a fill should be added at this bar."""
149        import random
150
151        if random.random() < fill_frequency and self.fills:
152            # Choose fill based on probabilities
153            total_prob = sum(fill.trigger_probability for fill in self.fills)
154            if total_prob > 0:
155                rand_val = random.random() * total_prob
156                current_sum = 0
157                for fill in self.fills:
158                    current_sum += fill.trigger_probability
159                    if rand_val <= current_sum:
160                        return fill
161        return None

Determine if a fill should be added at this bar.

@dataclass

class GenerationParameters: View Source

 11@dataclass
 12class GenerationParameters:
 13    """Parameters controlling pattern generation."""
 14
 15    genre: str
 16    style: str = "default"
 17    drummer: str | None = None
 18    drummer_intensity: float = 1.0  # 0.0-1.0, how strongly the drummer's
 19    # signature modifications override the genre plugin's base pattern.
 20    # 1.0 = full drummer character (default, matches prior behavior);
 21    # 0.0 = genre pattern untouched by drummer styling. Lets a user ask
 22    # for e.g. "Porcaro tracking a Death Metal pattern" without the
 23    # drummer's feel fully overwriting the genre's identity.
 24    complexity: float = 0.5  # 0.0-1.0, affects fill density and variation
 25    dynamics: float = 0.5  # 0.0-1.0, affects volume variation
 26    humanization: float = 0.3  # 0.0-1.0, affects timing/velocity variation
 27    fill_frequency: float = 0.2  # 0.0-1.0, how often fills occur
 28    swing_ratio: float = 0.0  # 0.0-1.0, swing feel
 29    ride_threshold: float = 0.9  # 0.0-1.0, complexity above which a
 30    # section switches from hi-hat to ride cymbal timekeeping regardless
 31    # of section name. High by default so section name (chorus/bridge)
 32    # stays the primary trigger; existing patterns commonly run
 33    # complexity 0.7-0.8 for busy-but-still-hihat verses, so this only
 34    # fires as a deliberate high-complexity override.
 35
 36    # Genre context adaptation (NEW)
 37    song_genre_context: str | None = None  # Overall song genre for adaptation
 38    context_blend: float = 0.0  # 0.0-1.0, how much to blend with context
 39
 40    # Riff-lock (audio riff -> kick-locked drum pattern, see
 41    # midi_drums.modifications.riff_lock.RiffLockTransform). Applies to a
 42    # single generate_pattern() call for exactly one bar - passing this
 43    # through create_song()'s **kwargs would apply the same one-bar lock to
 44    # every section, which is not what create_song callers want, so callers
 45    # that need riff-lock must call generate_pattern() directly per section
 46    # (see midi_drums.api.cli's `riff` subcommand).
 47    riff_accents: "RiffAccentMap | None" = None
 48    riff_lock_strength: float = 1.0  # 0.0-1.0, blend toward riff accents
 49
 50    # Snare reaction to the same riff accents (see
 51    # midi_drums.modifications.snare_accent_reaction.SnareAccentReaction).
 52    # Applied after riff-lock, same single-generate_pattern()-call scope as
 53    # riff_accents above. "off" means the pipeline hook never constructs
 54    # SnareAccentReaction at all.
 55    riff_snare_mode: Literal["off", "reinforce", "stab"] = "off"
 56    riff_snare_stab_threshold: float = 0.85
 57
 58    # Cymbal reactions to the same riff accents (see
 59    # midi_drums.modifications.cymbal_accent_reaction.CymbalAccentReaction).
 60    # Same scope/semantics as riff_snare_mode above, one independent
 61    # mode/threshold pair per kit piece - hi-hat, crash, ride, and china
 62    # can each be off/reinforce/stab independently. "off" means the
 63    # pipeline hook never constructs CymbalAccentReaction for that kit
 64    # piece at all.
 65    riff_hihat_mode: Literal["off", "reinforce", "stab"] = "off"
 66    riff_hihat_stab_threshold: float = 0.85
 67    riff_crash_mode: Literal["off", "reinforce", "stab"] = "off"
 68    riff_crash_stab_threshold: float = 0.85
 69    riff_ride_mode: Literal["off", "reinforce", "stab"] = "off"
 70    riff_ride_stab_threshold: float = 0.85
 71    riff_china_mode: Literal["off", "reinforce", "stab"] = "off"
 72    riff_china_stab_threshold: float = 0.85
 73
 74    custom_parameters: dict[str, Any] = field(default_factory=dict)
 75
 76    def __post_init__(self):
 77        """Validate parameters."""
 78        if self.riff_snare_mode not in ("off", "reinforce", "stab"):
 79            raise ValueError(
 80                "riff_snare_mode must be 'off', 'reinforce', or 'stab', "
 81                f"got {self.riff_snare_mode!r}"
 82            )
 83        for param_name, value in [
 84            ("complexity", self.complexity),
 85            ("dynamics", self.dynamics),
 86            ("humanization", self.humanization),
 87            ("fill_frequency", self.fill_frequency),
 88            ("swing_ratio", self.swing_ratio),
 89            ("ride_threshold", self.ride_threshold),
 90            ("context_blend", self.context_blend),
 91            ("drummer_intensity", self.drummer_intensity),
 92            ("riff_lock_strength", self.riff_lock_strength),
 93            ("riff_snare_stab_threshold", self.riff_snare_stab_threshold),
 94            ("riff_hihat_stab_threshold", self.riff_hihat_stab_threshold),
 95            ("riff_crash_stab_threshold", self.riff_crash_stab_threshold),
 96            ("riff_ride_stab_threshold", self.riff_ride_stab_threshold),
 97            ("riff_china_stab_threshold", self.riff_china_stab_threshold),
 98        ]:
 99            if not 0.0 <= value <= 1.0:
100                raise ValueError(
101                    f"{param_name} must be between 0.0 and 1.0, got {value}"
102                )

Parameters controlling pattern generation.

GenerationParameters( genre: str, style: str = 'default', drummer: str | None = None, drummer_intensity: float = 1.0, complexity: float = 0.5, dynamics: float = 0.5, humanization: float = 0.3, fill_frequency: float = 0.2, swing_ratio: float = 0.0, ride_threshold: float = 0.9, song_genre_context: str | None = None, context_blend: float = 0.0, riff_accents: midi_drums.core.value_objects.riff_accent.RiffAccentMap | None = None, riff_lock_strength: float = 1.0, riff_snare_mode: Literal['off', 'reinforce', 'stab'] = 'off', riff_snare_stab_threshold: float = 0.85, riff_hihat_mode: Literal['off', 'reinforce', 'stab'] = 'off', riff_hihat_stab_threshold: float = 0.85, riff_crash_mode: Literal['off', 'reinforce', 'stab'] = 'off', riff_crash_stab_threshold: float = 0.85, riff_ride_mode: Literal['off', 'reinforce', 'stab'] = 'off', riff_ride_stab_threshold: float = 0.85, riff_china_mode: Literal['off', 'reinforce', 'stab'] = 'off', riff_china_stab_threshold: float = 0.85, custom_parameters: dict[str, typing.Any] = <factory>)

genre: str

style: str = 'default'

drummer: str | None = None

drummer_intensity: float = 1.0

complexity: float = 0.5

dynamics: float = 0.5

humanization: float = 0.3

fill_frequency: float = 0.2

swing_ratio: float = 0.0

ride_threshold: float = 0.9

song_genre_context: str | None = None

context_blend: float = 0.0

riff_accents: midi_drums.core.value_objects.riff_accent.RiffAccentMap | None = None

riff_lock_strength: float = 1.0

riff_snare_mode: Literal['off', 'reinforce', 'stab'] = 'off'

riff_snare_stab_threshold: float = 0.85

riff_hihat_mode: Literal['off', 'reinforce', 'stab'] = 'off'

riff_hihat_stab_threshold: float = 0.85

riff_crash_mode: Literal['off', 'reinforce', 'stab'] = 'off'

riff_crash_stab_threshold: float = 0.85

riff_ride_mode: Literal['off', 'reinforce', 'stab'] = 'off'

riff_ride_stab_threshold: float = 0.85

riff_china_mode: Literal['off', 'reinforce', 'stab'] = 'off'

riff_china_stab_threshold: float = 0.85

custom_parameters: dict[str, typing.Any]

midi_drums

Arguments:

Returns:

Arguments:

Returns:

Example:

Generate progressive pattern adapted to metal context