"""``PatternBuilder`` (the ``p`` inside a pattern) — the note-placement surface.
This is the ``p`` handed to every ``@composition.pattern`` function: the verbs
for placing notes, drums, chords, motifs and phrases, plus articulation, the
transforms, and the algorithmic and MIDI mixins it inherits. It renders into
the plain data types in ``pattern``.
"""
import dataclasses
import logging
import random
import time
import typing
import pymididefs.rpn
import subsequence.chords
import subsequence.constants
import subsequence.constants.velocity
import subsequence.easing
import subsequence.groove
import subsequence.held_notes
import subsequence.intervals
import subsequence.pattern
import subsequence.motifs
import subsequence.sequence_utils
import subsequence.mini_notation
import subsequence.conductor
import subsequence.pattern_algorithmic
import subsequence.pattern_midi
import subsequence.progressions
logger = logging.getLogger(__name__)
def _expand_sequence_param (name: str, value: typing.Any, n: int) -> list:
"""Expand a scalar to a list of length n, or adjust a list to length n.
Parameters:
name: The name of the parameter being expanded (used for logging).
value: A scalar (e.g., int, float, str) or an iterable to expand.
n: The target length for the returned list.
Returns:
A list of length ``n``. If ``value`` is a scalar, returns ``[value] * n``.
If ``value`` is a list longer than ``n``, truncates it and logs a warning.
If ``value`` is a list shorter than ``n``, repeats the last value and logs a warning.
"""
if isinstance(value, (int, float, str)):
return [value] * n
result = list(value)
if len(result) == 0:
raise ValueError(f"sequence(): {name} list cannot be empty")
if len(result) > n:
logger.warning("sequence(): %s has %d values but only %d steps - truncating", name, len(result), n)
return result[:n]
if len(result) < n:
logger.warning("sequence(): %s has %d values but %d steps - repeating last value", name, len(result), n)
return result + [result[-1]] * (n - len(result))
return result
[docs]
class BarCycle:
"""Position of the current bar within a repeating cycle of bars.
Returned by :meth:`PatternBuilder.bar_cycle`. Provides readable, musician-friendly
properties for bar-position logic without raw modulo arithmetic.
Attributes:
bar: Zero-indexed bar within the cycle (0 … length−1).
length: The cycle length in bars passed to :meth:`PatternBuilder.bar_cycle`.
"""
__slots__ = ("bar", "length")
def __init__ (self, bar: int, length: int) -> None:
@property
[docs]
def first (self) -> bool:
"""True on the first bar of the cycle (``bar == 0``)."""
return self.bar == 0
@property
[docs]
def last (self) -> bool:
"""True on the last bar of the cycle (``bar == length − 1``)."""
return self.bar == self.length - 1
@property
[docs]
def progress (self) -> float:
"""Fractional progress through the cycle: 0.0 on bar 0, rising each bar.
For a 4-bar cycle: 0.0, 0.25, 0.5, 0.75.
Useful for gradual intensity curves or as a noise/LFO seed.
"""
return self.bar / self.length
[docs]
class PatternBuilder(
subsequence.pattern_algorithmic.PatternAlgorithmicMixin,
subsequence.pattern_midi.PatternMidiMixin,
):
"""
The musician's 'palette' for creating musical content.
A ``PatternBuilder`` instance (commonly named ``p``) is passed to every
pattern function. It provides methods for placing notes, generating rhythms,
and transforming the resulting sequence (e.g., swinging, reversing, or transposing).
Rhythm in Subsequence is typically expressed in **beats** (where 1.0 is a
quarter note) or **steps** (subdivisions of a pattern).
"""
def __init__ (self, pattern: subsequence.pattern.Pattern, cycle: int, conductor: typing.Optional[subsequence.conductor.Conductor] = None, drum_note_map: typing.Optional[typing.Dict[str, int]] = None, cc_name_map: typing.Optional[typing.Dict[str, int]] = None, nrpn_name_map: typing.Optional[typing.Dict[str, int]] = None, section: typing.Any = None, bar: int = 0, rng: typing.Optional[random.Random] = None, tweaks: typing.Optional[typing.Dict[str, typing.Any]] = None, default_grid: int = 16, data: typing.Optional[typing.Dict[str, typing.Any]] = None, key: typing.Optional[str] = None, scale: typing.Optional[str] = None, time_signature: typing.Tuple[int, int] = (4, 4), held_notes: typing.Optional[subsequence.held_notes.HeldNotes] = None, harmony: typing.Optional[typing.Any] = None, section_motifs: typing.Optional[typing.Dict[typing.Tuple[str, typing.Optional[str]], typing.Any]] = None, energy: float = 0.5) -> None:
"""Initialize the builder with pattern context, cycle count, and optional section info.
Parameters:
pattern: The ``Pattern`` instance this builder populates.
cycle: Zero-based rebuild counter.
conductor: Optional ``Conductor`` for time-varying signals.
drum_note_map: Optional mapping of drum names to MIDI notes.
cc_name_map: Optional mapping of CC names to MIDI CC numbers.
nrpn_name_map: Optional mapping of NRPN parameter names to 14-bit
parameter numbers (0–16383). Used by ``p.nrpn()`` and
``p.nrpn_ramp()`` for symbolic access — typically a
device-specific dictionary (e.g. Sequential Take 5's
``Osc1FreqFine`` → 9).
section: Current ``SectionInfo`` (or ``None``).
bar: Global bar count.
rng: Optional seeded ``Random`` for reproducibility.
tweaks: Per-pattern overrides set via ``composition.tweak()``.
default_grid: Number of grid slots used by ``hit_steps()``,
``sequence()``, and ``rotate()`` when no explicit ``grid``
is passed. Normally set automatically from the decorator's
``beats``/``bars``/``steps`` and ``step_duration`` parameters.
data: Shared state dict from the parent ``Composition``
(same object as ``composition.data``). Read and write
via ``p.data`` for cross-pattern communication and
external data access. Patterns rebuild in definition
order; when two patterns share the same ``length``,
a writer defined earlier in source is guaranteed to
run before a reader defined later in the same cycle.
key: The composition's key (e.g. ``"C"``), used by ``p.progression()``
to generate chords from a graph style and by ``p.motif()`` to
resolve scale degrees. ``None`` when the composition has no
key set.
scale: The composition's scale/mode name (e.g. ``"minor"``),
read via ``p.scale`` and used to resolve scale degrees in
``p.motif()``. ``None`` means ionian/major.
time_signature: The composition's time signature, read via
``p.time_signature``; powers the metric-weight table.
section_motifs: Optional reference to the composition's
section-motif registry, read by ``p.section_motif()``.
harmony: Optional read-only harmony window view for this cycle
(``p.harmony``) — ``p.harmony.chord``, ``chord_at(beat)``,
``next_chord``, ``until_change``. ``None`` until the
harmonic clock has published a window.
held_notes: Optional live held-note tracker from ``composition.note_input()``.
Read via ``p.held_notes()``. ``None`` when no note input was declared
(and when rendering headlessly), so the accessor returns an empty list.
energy: The current section's energy level (0.0–1.0), read via
``p.energy`` — the arranging dial. 0.5 when no energy source
is configured.
"""
self._pattern = pattern
self.cycle = cycle
self.conductor = conductor
self._drum_note_map = drum_note_map
self._cc_name_map = cc_name_map
self._nrpn_name_map = nrpn_name_map
self.section = section
self.bar = bar
self.rng: random.Random = rng or random.Random()
self._tweaks: typing.Dict[str, typing.Any] = tweaks or {}
self._default_grid: int = default_grid
self.data: typing.Dict[str, typing.Any] = data if data is not None else {}
self.key: typing.Optional[str] = key # composition key, for p.progression() chord generation
self.scale: typing.Optional[str] = scale # composition scale/mode, for degree resolution
self.time_signature: typing.Tuple[int, int] = time_signature
self.harmony: typing.Optional[typing.Any] = harmony # HarmonyView for this cycle, or None
self.energy: float = energy # current section's energy (the arranging dial)
self._section_motifs: typing.Optional[typing.Dict[typing.Tuple[str, typing.Optional[str]], typing.Any]] = section_motifs
self._held_notes: typing.Optional[subsequence.held_notes.HeldNotes] = held_notes
self._tuning_applied: bool = False # set by apply_tuning() to prevent double-apply
@property
[docs]
def grid (self) -> int:
"""Number of grid slots in this pattern (e.g. 16 for a 4-beat sixteenth-note pattern)."""
return self._default_grid
def _has_pitch_at_beat (self, pitch: typing.Union[int, str], beat: float) -> bool:
"""Helper to check if a pitch is already sounding at a specific beat.
Tolerant of unmappable drum names: a name absent from this pattern's
``drum_note_map`` can't already be sounding here, so it returns False
(the placement itself handles the drop/warn) rather than raising."""
if isinstance(pitch, str):
if self._drum_note_map is None or pitch not in self._drum_note_map:
return False
midi_pitch = self._drum_note_map[pitch]
else:
midi_pitch = pitch
pulse = int(beat * subsequence.constants.MIDI_QUARTER_NOTE)
if pulse in self._pattern.steps:
return any(n.pitch == midi_pitch for n in self._pattern.steps[pulse].notes)
return False
@property
[docs]
def c (self) -> typing.Optional[subsequence.conductor.Conductor]:
"""Alias for self.conductor."""
return self.conductor
[docs]
def signal (self, name: str) -> float:
"""Read a conductor signal at the current bar.
Shorthand for ``p.c.get(name, p.bar * 4)``. Returns 0.0 if
no conductor is attached or the signal is not defined.
"""
if self.conductor is None:
return 0.0
return self.conductor.get(name, self.bar * 4)
[docs]
def held_notes (self) -> typing.List[int]:
"""Return the MIDI notes currently held on the ``note_input`` keyboard.
The notes are sorted ascending. Pass the result straight to
``p.arpeggio()`` to arpeggiate whatever the player is holding —
``p.arpeggio(p.held_notes())`` rests when no keys are down. Returns
an empty list when no ``note_input()`` source was declared and when
rendering headlessly (so seeded output stays deterministic).
The set is sampled once per rebuild; ``note_input(release_ms=…)``
smooths the gap during hand-position changes so the arp does not drop
out, and ``note_input(latch=True)`` holds the chord until you play a
new one.
"""
if self._held_notes is None:
return []
return self._held_notes.snapshot(time.perf_counter())
[docs]
def param (self, name: str, default: typing.Any = None) -> typing.Any:
"""Read a tweakable parameter for this pattern.
Returns the value set via ``composition.tweak()`` if one
exists, otherwise returns ``default``.
Parameters:
name: The parameter name.
default: The value to return if no tweak is active.
Example::
@composition.pattern(channel=1, beats=4)
def bass (p):
pitches = p.param("pitches", [60, 64, 67, 72])
p.sequence(steps=[0, 4, 8, 12], pitches=pitches)
"""
return self._tweaks.get(name, default)
[docs]
def set_length (self, length: float) -> "PatternBuilder":
"""
Dynamically change the length of the pattern.
The new length takes effect immediately for any subsequent notes
placed in the current builder call, and will be used by the
sequencer for next cycle's scheduling.
Parameters:
length: New pattern length in beats (e.g., 4.0 for a bar).
Returns ``self`` for fluent chaining.
"""
if length <= 0:
raise ValueError("Pattern length must be positive")
self._pattern.length = length
return self
def _resolve_pitch (self, pitch: typing.Union[int, str]) -> int:
"""
Resolve a pitch value to a MIDI note number (strict).
Raises on an unknown drum name — the strict counterpart of
:meth:`_resolve_pitch_lenient`. Note-placement and transform methods use
the lenient variant, so a device may legitimately lack a voice others
have; this strict primitive is retained for parity with the sibling
``_resolve_cc`` / ``_resolve_nrpn`` / ``_resolve_rpn`` name resolvers,
where an unknown name is always a configuration error.
"""
if isinstance(pitch, int):
return pitch
if self._drum_note_map is None:
raise ValueError(f"String pitch '{pitch}' requires a drum_note_map, but none was provided")
if pitch not in self._drum_note_map:
raise ValueError(f"Unknown drum name '{pitch}' - not found in drum_note_map")
return self._drum_note_map[pitch]
def _resolve_hit_pitch (self, pitch: typing.Union[int, str]) -> typing.Optional[typing.Tuple[int, typing.Optional[str], bool]]:
"""Resolve a step-note pitch for placement, leniently for named drums.
Returns ``(midi_pitch, origin, primary_unmapped)``, or ``None`` to drop
the hit entirely.
Unlike :meth:`_resolve_pitch`, an unknown drum *name* does not raise:
faithful-core device maps legitimately lack voices other devices have,
so a name a device can't voice is dropped rather than crashing the
pattern. The cases:
- Integer pitch → ``(pitch, None, False)``.
- String in this pattern's ``drum_note_map`` → ``(note, name, False)``.
- String absent here but present in a mirror's map →
``(placeholder, name, True)``: the primary can't voice it, but a
symbolic mirror can (the placeholder pitch is used only by transforms
and display, never for playback — see ``Note.primary_unmapped``).
- String absent everywhere → warn once and return ``None`` (drop).
- String with **no** ``drum_note_map`` at all → still a configuration
error; raises (you forgot the map, this is not a capability gap).
"""
if isinstance(pitch, int):
return (pitch, None, False)
if self._drum_note_map is None:
raise ValueError(f"String pitch '{pitch}' requires a drum_note_map, but none was provided")
if pitch in self._drum_note_map:
return (self._drum_note_map[pitch], pitch, False)
mirror_pitch = self._first_mirror_pitch(pitch)
if mirror_pitch is not None:
return (mirror_pitch, pitch, True)
self._warn_unknown_drum(pitch)
return None
def _first_mirror_pitch (self, name: str) -> typing.Optional[int]:
"""Return the first mirror ``drum_note_map`` value for *name*, or None.
Lets a named hit absent from the primary map still be placed (as a
``primary_unmapped`` Note) when a symbolic (3-tuple) mirror can voice it.
"""
for entry in getattr(self._pattern, 'mirrors', []):
if len(entry) == 3 and entry[2] is not None and name in entry[2]:
return typing.cast(int, entry[2][name])
return None
def _warn_unknown_drum (self, name: str, include_mirrors: bool = True) -> None:
"""Warn once (per pattern, per name) that a drum name maps to nothing.
Deduplicated via the Pattern's ``_warned_drum_names`` set so the per-bar
rebuild does not spam; a hot-reload builds a fresh Pattern and
re-surfaces the warning.
``include_mirrors`` tailors the wording: step-note placement checks the
mirror maps too (the name maps to *no* device), whereas the methods that
resolve against the primary map only — drones, ``arpeggio``, ``evolve``,
``branch``, and the ``thin``/``ratchet`` pitch filter — report just this
device.
"""
warned = getattr(self._pattern, '_warned_drum_names', None)
if warned is not None:
if name in warned:
return
warned.add(name)
fn = getattr(self._pattern, '_builder_fn', None)
label = getattr(fn, '__name__', None)
where = f"pattern '{label}'" if label else f"device {self._pattern.device} channel {self._pattern.channel}"
if include_mirrors:
scope = f"the drum_note_map for {where} or any of its mirror destinations"
reason = "no device maps this voice"
else:
scope = f"the drum_note_map for {where}"
reason = "this device has no such voice"
logger.warning(f"Drum name '{name}' is not in {scope} — the note is dropped ({reason}). Check the spelling, or add it to a map.")
def _resolve_pitch_lenient (self, pitch: typing.Union[int, str]) -> typing.Optional[int]:
"""Resolve a pitch against this pattern's own ``drum_note_map``, leniently.
Like :meth:`_resolve_pitch`, but an unknown drum *name* (a map is present
yet lacks the voice) is **dropped** — warned once, returns ``None`` —
instead of raising, so a device may legitimately lack a voice that other
devices have. Used by the methods that do NOT carry the drum name to
mirror destinations (``note_on``/``note_off``/``drone``, ``arpeggio``,
``evolve``, ``branch``, and the ``thin``/``ratchet`` pitch filter), so
resolution is against the primary map only. A string with **no**
``drum_note_map`` at all is still a configuration error and raises.
"""
if isinstance(pitch, int):
return pitch
if self._drum_note_map is None:
raise ValueError(f"String pitch '{pitch}' requires a drum_note_map, but none was provided")
if pitch in self._drum_note_map:
return self._drum_note_map[pitch]
self._warn_unknown_drum(pitch, include_mirrors=False)
return None
def _resolve_cc (self, control: typing.Union[int, str]) -> int:
"""Resolve a CC name or number to a MIDI CC number."""
if isinstance(control, int):
return control
if self._cc_name_map is None:
raise ValueError(f"String CC name '{control}' requires a cc_name_map, but none was provided")
if control not in self._cc_name_map:
raise ValueError(f"Unknown CC name '{control}' - not found in cc_name_map")
return self._cc_name_map[control]
def _resolve_nrpn (self, parameter: typing.Union[int, str]) -> int:
"""Resolve an NRPN parameter name or number to a 14-bit parameter number.
Strings require an ``nrpn_name_map`` on the pattern decorator —
NRPN parameter numbers are vendor-specific, so subsequence does not
ship a default mapping. Integer parameters must be in the 14-bit
range 0–16383.
"""
if isinstance(parameter, int):
if not 0 <= parameter <= 16383:
raise ValueError(f"NRPN parameter number must be 0–16383, got {parameter}")
return parameter
if self._nrpn_name_map is None:
raise ValueError(f"String NRPN name '{parameter}' requires an nrpn_name_map, but none was provided")
if parameter not in self._nrpn_name_map:
raise ValueError(f"Unknown NRPN name '{parameter}' - not found in nrpn_name_map")
return self._nrpn_name_map[parameter]
def _resolve_rpn (self, parameter: typing.Union[int, str]) -> int:
"""Resolve an RPN parameter name or number to a 14-bit parameter number.
Strings fall back to ``pymididefs.rpn.RPN_MAP`` — the standardised
set of MIDI Registered Parameter Numbers (``pitch_bend_sensitivity``,
``channel_fine_tuning``, ...). No per-pattern map needed. Integer
parameters must be in the 14-bit range 0–16383.
"""
if isinstance(parameter, int):
if not 0 <= parameter <= 16383:
raise ValueError(f"RPN parameter number must be 0–16383, got {parameter}")
return parameter
if parameter not in pymididefs.rpn.RPN_MAP:
raise ValueError(f"Unknown RPN name '{parameter}' - not a standard Registered Parameter Number")
return pymididefs.rpn.RPN_MAP[parameter]
[docs]
def note (self, pitch: typing.Union[int, str], beat: float, velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_VELOCITY, duration: float = 0.25) -> "PatternBuilder":
"""
Place a single MIDI note at a specific beat position.
A drum name is carried through to the mirror fan-out so each device can
re-resolve it through its own ``drum_note_map``. A name no destination
maps (not in the pattern's own map nor any mirror's) is dropped and
warned once — it does not raise — so device maps can legitimately lack
voices others have. (A string pitch with **no** ``drum_note_map`` at all
is still a configuration error and raises.)
Parameters:
pitch: MIDI note number (0-127) or a drum name string from
the pattern's ``drum_note_map``.
beat: The beat position (0.0 is the start). Negative values
wrap from the end (e.g., -1.0 is one beat before the end).
velocity: MIDI velocity (0-127, default 100), or a
``(low, high)`` tuple for a single random draw.
duration: Note duration in beats (default 0.25).
Example:
```python
p.note(60, beat=0, velocity=110) # Middle C on beat 1
p.note("kick", beat=1.0) # Kick on beat 2
p.note(67, beat=-0.5, duration=0.5) # G on the 'and' of the last beat
```
"""
# Resolve leniently: a named drum the target can't voice is dropped (and
# warned once) rather than raising, and the drum name is carried so each
# destination can re-resolve it through its own drum_note_map.
resolution = self._resolve_hit_pitch(pitch)
if resolution is None:
return self # unknown drum name, mapped by no destination — dropped
midi_pitch, origin, primary_unmapped = resolution
resolved_velocity = self._resolve_velocity(velocity)
# Negative beat values wrap to the end of the pattern.
if beat < 0:
beat = beat % self._pattern.length # wrap from the end (any magnitude)
self._pattern.add_note_beats(
beat_position = beat,
pitch = midi_pitch,
velocity = resolved_velocity,
duration_beats = duration,
origin = origin,
primary_unmapped = primary_unmapped
)
return self
[docs]
def note_on (self, pitch: typing.Union[int, str], beat: float, velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_VELOCITY) -> "PatternBuilder":
"""
Place an explicit Note On event without a duration.
Useful for drones or infinite sustains. Must be paired with
a ``note_off()`` later to silence the note.
Parameters:
pitch: MIDI note number (0-127) or a drum name string.
beat: The beat position (0.0 is the start).
velocity: MIDI velocity (0-127, default 100), or a
``(low, high)`` tuple for a single random draw.
A drum name this device's ``drum_note_map`` lacks is dropped (warned
once) rather than raising — consistent with the step-note methods. A
string pitch with no ``drum_note_map`` at all is still a configuration
error and raises.
"""
midi_pitch = self._resolve_pitch_lenient(pitch)
if midi_pitch is None:
return self # drum name this device can't voice — dropped (warned once)
resolved_velocity = self._resolve_velocity(velocity)
if beat < 0:
beat = beat % self._pattern.length # wrap from the end (any magnitude)
self._pattern.add_raw_note_beats(
message_type = 'note_on',
beat_position = beat,
pitch = midi_pitch,
velocity = resolved_velocity
)
return self
[docs]
def note_off (self, pitch: typing.Union[int, str], beat: float) -> "PatternBuilder":
"""
Place an explicit Note Off event to silence a drone.
Parameters:
pitch: MIDI note number (0-127) or a drum name string.
beat: The beat position (0.0 is the start).
A drum name this device's ``drum_note_map`` lacks is dropped (warned
once) rather than raising; with no ``drum_note_map`` at all it raises.
"""
midi_pitch = self._resolve_pitch_lenient(pitch)
if midi_pitch is None:
return self # nothing to silence — this device can't voice the name
if beat < 0:
beat = beat % self._pattern.length # wrap from the end (any magnitude)
self._pattern.add_raw_note_beats(
message_type = 'note_off',
beat_position = beat,
pitch = midi_pitch,
velocity = 0
)
return self
[docs]
def drone (self, pitch: typing.Union[int, str], beat: float = 0.0, velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_VELOCITY) -> "PatternBuilder":
"""
A musical alias for ``note_on``. Places a raw Note On event without a duration,
typically used for sustained notes that span multiple cycles.
Must be silenced later using ``drone_off()``.
Parameters:
pitch: MIDI note number (0-127) or a drum name string.
beat: The beat position (0.0 is the start).
velocity: MIDI velocity (0-127, default 100), or a
``(low, high)`` tuple for a single random draw.
"""
self.note_on(pitch, beat=beat, velocity=velocity)
return self
[docs]
def drone_off (self, pitch: typing.Union[int, str]) -> "PatternBuilder":
"""
A musical alias for ``note_off``. Places a raw Note Off event at beat 0.0.
Used to stop a sequence started by ``drone()``.
Parameters:
pitch: MIDI note number (0-127) or a drum name string.
"""
self.note_off(pitch, beat=0.0)
return self
[docs]
def silence (self, beat: float = 0.0) -> "PatternBuilder":
"""
Sends an 'All Notes Off' (CC 123) and 'All Sound Off' (CC 120) message
on the pattern's channel to immediately silence any ringing notes or drones.
Parameters:
beat: The beat position (0.0 is the start).
"""
self.cc(control=123, value=0, beat=beat)
self.cc(control=120, value=0, beat=beat)
return self
[docs]
def hit (self, pitch: typing.Union[int, str], beats: typing.List[float], velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_VELOCITY, duration: float = 0.1) -> "PatternBuilder":
"""
Place multiple short 'hits' at a list of beat positions.
Parameters:
pitch: MIDI note number or drum name.
beats: List of beat positions.
velocity: MIDI velocity (0-127), or a ``(low, high)`` tuple
for a fresh random draw per hit.
duration: Note duration in beats.
Example:
```python
p.hit("snare", [1, 3]) # Standard backbeat
p.hit("snare", [1, 3], velocity=(80, 110)) # Human velocity range
```
"""
for beat in beats:
self.note(pitch=pitch, beat=beat, velocity=velocity, duration=duration)
return self
[docs]
def hit_steps (self, pitch: typing.Union[int, str], steps: typing.List[int], velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_VELOCITY, duration: float = 0.1, grid: typing.Optional[int] = None, probability: float = 1.0, seed: typing.Optional[int] = None, rng: typing.Optional[random.Random] = None) -> "PatternBuilder":
"""
Place short hits at specific step (grid) positions.
Parameters:
pitch: MIDI note number or drum name.
steps: A list of grid indices (0 to ``grid - 1``).
velocity: MIDI velocity (0-127), or a ``(low, high)`` tuple
for a fresh random draw per step.
duration: Note duration in beats.
grid: How many grid slots the pattern is divided into.
Defaults to the pattern's ``default_grid`` (set from the
decorator's ``steps``/``step_duration``, or sixteenth-note
resolution when ``unit`` is omitted).
probability: Chance (0.0 to 1.0) that each hit will play.
rng: Optional random generator (overrides the pattern's seed).
Example:
```python
# Typical sixteenth-note hi-hats with some probability variation
p.hit_steps("hh", range(16), velocity=70, probability=0.8)
# Humanised hi-hats — each step gets a fresh random velocity.
p.hit_steps("hh", range(16), velocity=(40, 90))
```
"""
rng = self._rng_from(seed, rng)
if grid is None:
grid = self._default_grid
step_duration = self._pattern.length / grid
for i in steps:
if probability < 1.0 and rng.random() >= probability:
continue
beat = i * step_duration
self.note(pitch=pitch, beat=beat, velocity=velocity, duration=duration)
return self
[docs]
def motif (
self,
m: "subsequence.motifs.Motif",
beat: float = 0.0,
span: typing.Optional[float] = None,
root: int = 60,
velocity: typing.Optional[typing.Union[int, typing.Tuple[int, int]]] = None,
fit: typing.Optional[float] = None,
fit_weights: typing.Optional[typing.List[float]] = None,
resolution: typing.Optional[int] = None,
) -> "PatternBuilder":
"""
Place an immutable :class:`~subsequence.motifs.Motif` onto the pattern.
Note events route through the universal ``note()`` funnel (drum names,
mirrors, velocity tuples all work); control gestures emit through the
same machinery as ``cc()`` / ``cc_ramp()`` / ``pitch_bend()`` /
``nrpn()`` / ``osc()``. Pitch specs resolve here, late: ints are MIDI,
strings are drum names, scale degrees resolve against the composition
key + scale anchored near ``root=``. Per-event probabilities roll
fresh each cycle against the pattern's seeded stream.
Parameters:
m: The motif value (anything exposing ``.events`` / ``.length``
places; ``.controls`` is read when present).
beat: Where the motif starts within the pattern.
span: Clamp — events whose onset falls at or beyond *span* beats
into the motif are dropped (the ``arpeggio()`` convention).
root: Register anchor for scale-degree resolution: the tonic
lands at its nearest instance to this MIDI note (ties resolve
upward) and the melody keeps its written contour from there.
velocity: Optional override applied to every note (otherwise each
event's own velocity is used).
fit: The chord-tones-on-strong-beats dial, 0.0–1.0: resolved
Degree/int pitches landing on strong beats (metric weight
>= 0.5) snap to the nearest chord tone with this
probability. Defaults to the motif's own ``fit`` (0.7 on
generated motifs, none on hand-written ones — typed degrees
are sacred); inactive without a chord context. ChordTone
and Approach events never snap — their harmony reading is
inherent (an Approach's chromaticism is the point).
fit_weights: Custom per-step metric weight list (the
``build_ghost_bias`` precedent) for additive or
non-isochronous meters; defaults to the time signature's
table.
resolution: Pulses between control-ramp messages (defaults to
each control verb's own default). Kept out of the value by
design: beats and shapes are music, traffic density is wire.
"""
events = getattr(m, "events", None)
if events is None or not hasattr(m, "length"):
raise TypeError(f"motif() places Motif-like values (.events/.length) — got {type(m).__name__}")
effective_fit = fit if fit is not None else getattr(m, "fit", None)
fit_table: typing.Optional[typing.List[float]] = None
snap_probability = 0.0
if effective_fit:
snap_probability = float(effective_fit)
fit_table = list(fit_weights) if fit_weights is not None else subsequence.sequence_utils.build_metric_weights(
self.time_signature, grid = self._default_grid
)
for event in events:
if span is not None and event.beat >= span:
continue
if event.probability < 1.0 and self.rng.random() >= event.probability:
continue
resolved = self._resolve_motif_pitch(event.pitch, root, beat + event.beat)
# The fit dial reads only Degree/int content: drums have no
# pitch to snap, ChordTones already are chord tones, and an
# Approach's chromaticism is the point.
if (
fit_table is not None
and isinstance(resolved, int)
and isinstance(event.pitch, (int, subsequence.motifs.Degree))
):
resolved = self._fit_snap(resolved, beat + event.beat, snap_probability, fit_table)
self.note(
pitch = resolved,
beat = beat + event.beat,
velocity = velocity if velocity is not None else event.velocity,
duration = event.duration,
)
for control in getattr(m, "controls", ()):
if span is not None and control.beat >= span:
continue
if control.probability < 1.0 and self.rng.random() >= control.probability:
continue
self._emit_control(control, beat, resolution)
return self
def _resolve_motif_pitch (self, pitch: typing.Any, root: int, event_beat: float = 0.0) -> typing.Union[int, str]:
"""Resolve one stored pitch spec to a MIDI int or drum name, late.
``event_beat`` is the event's position within this cycle — chord-
relative specs resolve against the chord sounding *under the event*
(``p.harmony.chord_at``), not the cycle-start snapshot.
"""
if pitch is None:
raise ValueError(
"This motif is a rhythm skeleton (pitches stripped) — "
"re-pitch it with .pitched() before placing"
)
if isinstance(pitch, (int, str)):
return pitch
if isinstance(pitch, subsequence.motifs.Degree):
return self._resolve_degree_pitch(pitch, root)
if isinstance(pitch, subsequence.motifs.ChordTone):
return self._resolve_chord_tone_pitch(pitch, root, event_beat)
if isinstance(pitch, subsequence.motifs.Approach):
return self._resolve_approach_pitch(pitch, root, event_beat)
raise TypeError(f"Unknown pitch spec: {type(pitch).__name__}")
def _resolve_approach_pitch (self, approach: "subsequence.motifs.Approach", root: int, event_beat: float) -> int:
"""Resolve an Approach: one semitone below its target's pitch.
A ``ChordTone`` target reads the chord at the NEXT boundary after the
event (the harmony window's anticipation data) — the approach is the
tension, the target is where the harmony lands. When the window
holds no committed next chord (the live mode horizon's edge), the
sounding chord stands in. ``Degree``/``int`` targets resolve as
usual (no harmony needed).
"""
target = approach.target
if isinstance(target, subsequence.motifs.ChordTone):
if self.harmony is None:
raise ValueError(
"an Approach at a chord tone needs the harmonic clock — "
"call composition.harmony(...) (a style or a bound progression)"
)
chord = self.harmony.next_chord_at(event_beat)
if chord is None:
chord = self.harmony.chord_at(event_beat)
if chord is None:
raise ValueError(
f"No chord is known around beat {event_beat:g} of this cycle — "
"the harmony window does not cover it"
)
tones = chord.tones(root, count = target.index)
resolved = int(tones[target.index - 1]) + 12 * target.octave
elif isinstance(target, subsequence.motifs.Degree):
resolved = self._resolve_degree_pitch(target, root)
elif isinstance(target, int):
resolved = target
else:
raise TypeError(f"cannot approach {type(target).__name__} content")
pitch = resolved - 1
if not 0 <= pitch <= 127:
raise ValueError(
f"Approach resolves to MIDI {pitch}, outside 0–127 — adjust root= or the target's octave"
)
return pitch
def _fit_snap (self, pitch: int, event_beat: float, fit: float, weights: typing.List[float]) -> int:
"""The fit dial: snap a strong-beat pitch to the nearest chord tone, with probability *fit*.
Strong beats are the metric-weight table's >= 0.5 positions
(downbeats and beats); off-grid events take the nearest grid
position's weight. Inactive without a chord context.
"""
if self.harmony is None:
return pitch
bar_beats = float(self.time_signature[0])
grid = len(weights)
step = (event_beat % bar_beats) * grid / bar_beats
weight = weights[int(round(step)) % grid]
if weight < 0.5:
return pitch
if self.rng.random() >= fit:
return pitch
chord = self.harmony.chord_at(event_beat)
if chord is None:
return pitch
chord_pcs = {tone % 12 for tone in chord.tones(pitch)}
if pitch % 12 in chord_pcs:
return pitch
# Nearest chord tone, ties upward.
for delta in (1, -1, 2, -2, 3, -3, 4, -4, 5, -5, 6):
if (pitch + delta) % 12 in chord_pcs and 0 <= pitch + delta <= 127:
return pitch + delta
return pitch
def _resolve_chord_tone_pitch (self, tone: "subsequence.motifs.ChordTone", root: int, event_beat: float) -> int:
"""Resolve a 1-based chord-tone index against the chord under the event.
Reads the harmony window (``p.harmony.chord_at(event_beat)``): indices
walk the sounding chord's tones nearest ``root``, cycling into higher
octaves past the chord's natural size, plus whole-octave shifts.
"""
if self.harmony is None:
raise ValueError(
"ChordTone pitches resolve against the harmonic clock — "
"call composition.harmony(...) (a style or a bound progression)"
)
chord = self.harmony.chord_at(event_beat)
if chord is None:
raise ValueError(
f"No chord is known at beat {event_beat:g} of this cycle — "
"the harmony window does not cover it"
)
tones = chord.tones(root, count = tone.index)
midi = int(tones[tone.index - 1]) + 12 * tone.octave
if not 0 <= midi <= 127:
raise ValueError(
f"Chord tone {tone.index} resolves to MIDI {midi}, outside 0–127 — "
"adjust root= or the tone's octaves"
)
return midi
def _resolve_degree_pitch (self, degree: "subsequence.motifs.Degree", root: int) -> int:
"""
Resolve a 1-based scale degree against the composition key + scale.
The tonic anchors at its nearest instance to ``root`` (ties resolve
upward); the degree then builds from the anchored tonic, so a written
melody keeps its contour. Steps beyond the scale length carry into
higher octaves (8 = tonic an octave up in seven-note scales).
"""
if self.key is None:
raise ValueError("Scale degrees resolve against a key — set Composition(key=...)")
mode = self.scale or "ionian"
pcs = subsequence.intervals.scale_pitch_classes(subsequence.chords.key_name_to_pc(self.key), mode)
idx = (degree.step - 1) % len(pcs)
carry = (degree.step - 1) // len(pcs)
diff = (pcs[0] - root) % 12
tonic = root + diff if diff <= 6 else root + diff - 12
offset = (pcs[idx] - pcs[0]) % 12
midi = tonic + offset + 12 * (carry + degree.octave) + degree.chroma
if not 0 <= midi <= 127:
raise ValueError(
f"Degree {degree.step} resolves to MIDI {midi}, outside 0–127 — "
f"adjust root= or the degree's octaves"
)
return midi
def _emit_control (self, control: "subsequence.motifs.ControlEvent", beat: float, resolution: typing.Optional[int]) -> None:
"""Emit one stored control gesture through the matching builder verb."""
signal = control.signal
onset = beat + control.beat
extra: typing.Dict[str, typing.Any] = {} if resolution is None else {"resolution": resolution}
if isinstance(signal, subsequence.motifs.CC):
if control.end is None:
self.cc(signal.control, int(round(control.start)), beat=onset)
else:
self.cc_ramp(signal.control, int(round(control.start)), int(round(control.end)), beat_start=onset, beat_end=onset + control.span, shape=control.shape, **extra)
elif isinstance(signal, subsequence.motifs.PitchBend):
if control.end is None:
self.pitch_bend(control.start, beat=onset)
else:
self.pitch_bend_ramp(control.start, control.end, beat_start=onset, beat_end=onset + control.span, shape=control.shape, **extra)
elif isinstance(signal, subsequence.motifs.NRPN):
if control.end is None:
self.nrpn(signal.parameter, int(round(control.start)), beat=onset, fine=signal.fine, null_reset=signal.null_reset)
else:
self.nrpn_ramp(signal.parameter, int(round(control.start)), int(round(control.end)), beat_start=onset, beat_end=onset + control.span, shape=control.shape, fine=signal.fine, null_reset=signal.null_reset, **extra)
elif isinstance(signal, subsequence.motifs.RPN):
if control.end is None:
self.rpn(signal.parameter, int(round(control.start)), beat=onset, fine=signal.fine, null_reset=signal.null_reset)
else:
self.rpn_ramp(signal.parameter, int(round(control.start)), int(round(control.end)), beat_start=onset, beat_end=onset + control.span, shape=control.shape, fine=signal.fine, null_reset=signal.null_reset, **extra)
elif isinstance(signal, subsequence.motifs.OSC):
if control.end is None:
self.osc(signal.address, control.start, beat=onset)
else:
self.osc_ramp(signal.address, control.start, control.end, beat_start=onset, beat_end=onset + control.span, shape=control.shape, **extra)
else:
raise TypeError(f"Unknown control signal: {type(signal).__name__}")
[docs]
def phrase (
self,
value: typing.Any,
root: int = 60,
velocity: typing.Optional[typing.Union[int, typing.Tuple[int, int]]] = None,
fit: typing.Optional[float] = None,
resolution: typing.Optional[int] = None,
align: str = "pattern",
offset: float = 0.0,
) -> "PatternBuilder":
"""Place this cycle's window of a Phrase — position computed, never stored.
The playback position is stateless arithmetic over the engine's own
counters: ``pos = (p.cycle * pattern_length + offset) % phrase.length``
— deterministic under live reload, ``form_jump``, and render, with
zero new state. A pattern shorter than the phrase walks through it
cycle by cycle; deliberately mismatched lengths are phase drift
(polymeter against the phrase). When the cycle window crosses the
phrase's end, the phrase loops.
Patterns that should own the phrase's length call
``p.set_length(phrase.length)`` once instead.
Parameters:
value: A Phrase (or any value with ``.length``/``.slice``; a
Motif places its window directly).
root: Register anchor for degree resolution (see ``motif()``).
velocity: Optional override applied to every note.
fit: Passed through to ``motif()`` (active with the melody
engine stage).
resolution: Control-ramp pulse density (see ``motif()``).
align: ``"pattern"`` (default) counts pattern cycles;
``"section"`` uses the bar within the current form section,
so the phrase restarts when the section does.
offset: Beats added to the computed position (a phase shift).
Example:
```python
@comp.pattern(channel=4, bars=2)
def lead (p):
p.phrase(lead_line, root=72)
```
"""
length = getattr(value, "length", None)
if length is None or not hasattr(value, "slice"):
raise TypeError(f"phrase() places Phrase-like values (.length/.slice) — got {type(value).__name__}")
if length <= 0:
raise ValueError("cannot place an empty phrase")
if align == "pattern":
position = (self.cycle * float(self._pattern.length) + offset) % length
elif align == "section":
if self.section is None:
raise ValueError('phrase(align="section") needs a form — call composition.form(...)')
position = (self.section.bar * float(self.time_signature[0]) + offset) % length
else:
raise ValueError(f'align must be "pattern" or "section" — got {align!r}')
window_beats = float(self._pattern.length)
placed = 0.0
while placed < window_beats - 1e-9:
take = min(window_beats - placed, length - position)
piece = value.slice(position, position + take)
fragment = piece.flatten() if hasattr(piece, "flatten") else piece
self.motif(fragment, beat=placed, root=root, velocity=velocity, fit=fit, resolution=resolution)
placed += take
position = 0.0 # crossed the phrase end — loop to its start
return self
[docs]
def section_motif (self, part: typing.Optional[str] = None) -> typing.Optional[typing.Any]:
"""The Motif/Phrase bound to the current section (and part), or ``None``.
Reads the ``composition.section_motifs()`` registry for the section
currently playing. A section with no binding returns ``None`` —
bind material or rest; no fallback guessing::
@comp.pattern(channel=4, bars=2)
def lead (p):
line = p.section_motif("lead")
if line is not None:
p.phrase(line, root=72)
"""
if self.section is None or self._section_motifs is None:
return None
return self._section_motifs.get((self.section.name, part))
[docs]
def capture (self, beat: float = 0.0, span: float = 4.0) -> "subsequence.motifs.Motif":
"""
Read the notes placed so far back out as a :class:`~subsequence.motifs.Motif`.
The captured motif is **absolute MIDI and lossy by design**: relative
specs (degrees, chord tones) do not survive resolution, timing is
pulse-truncated, probabilities have already rolled, and control
gestures are not captured. The round trip is generate → place →
capture → hand-edit → rebind.
Parameters:
beat: Window start within the pattern.
span: Window length in beats (also the captured motif's length).
"""
ppq = subsequence.constants.MIDI_QUARTER_NOTE
lo, hi = int(beat * ppq), int((beat + span) * ppq)
events = []
for pulse in sorted(self._pattern.steps):
if not lo <= pulse < hi:
continue
for placed in self._pattern.steps[pulse].notes:
events.append(subsequence.motifs.MotifEvent(
beat = pulse / ppq - beat,
pitch = placed.pitch,
velocity = placed.velocity,
duration = max(placed.duration, 1) / ppq,
))
return subsequence.motifs.Motif(events=tuple(events), length=span)
[docs]
def sequence (self, steps: typing.List[int], pitches: typing.Union[int, str, typing.List[typing.Union[int, str]]], velocities: typing.Union[int, typing.Tuple[int, int], typing.List[int]] = subsequence.constants.velocity.DEFAULT_VELOCITY, durations: typing.Union[float, typing.List[float]] = 0.1, grid: typing.Optional[int] = None, probability: float = 1.0, seed: typing.Optional[int] = None, rng: typing.Optional[random.Random] = None) -> "PatternBuilder":
"""
A multi-parameter step sequencer.
Define which grid steps fire, and then provide a list of pitches,
velocities, and durations. If you provide a list for any parameter,
Subsequence will step through it as it places each note.
Parameters:
steps: List of grid indices to trigger. An empty list is a
no-op — no notes are placed and the builder is returned
unchanged (handy when probabilistic gating rejects every step).
pitches: Pitch or list of pitches.
velocities: Velocity (default 100), ``(low, high)`` tuple for
a fresh random draw per step, or a list of velocities
cycled per step.
durations: Duration or list of durations (default 0.1).
grid: Grid resolution. Defaults to the pattern's
``default_grid`` (derived from the decorator's ``beats``/``steps``
and ``unit``).
"""
if not steps:
return self
rng = self._rng_from(seed, rng)
if grid is None:
grid = self._default_grid
n = len(steps)
pitches_list = _expand_sequence_param("pitches", pitches, n)
# Treat a (low, high) tuple as a single random-range descriptor
# rather than a 2-element list to cycle through.
if isinstance(velocities, tuple):
velocities_list = [velocities] * n
else:
velocities_list = _expand_sequence_param("velocities", velocities, n)
durations_list = _expand_sequence_param("durations", durations, n)
step_duration = self._pattern.length / grid
for i, step_idx in enumerate(steps):
if probability < 1.0 and rng.random() >= probability:
continue
beat = step_idx * step_duration
self.note(pitch=pitches_list[i], beat=beat, velocity=velocities_list[i], duration=durations_list[i])
return self
[docs]
def seq (self, notation: str, pitch: typing.Union[str, int, None] = None, velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_VELOCITY, seed: typing.Optional[int] = None, rng: typing.Optional[random.Random] = None) -> "PatternBuilder":
"""
Build a pattern using an expressive string-based 'mini-notation'.
The notation distributes events evenly across the current pattern length.
**Syntax:**
- ``x y z``: Items separated by spaces are distributed across the bar.
- ``[a b]``: Groups items into a single subdivided step.
- ``~`` or ``.``: A rest.
- ``_``: Extends the previous note (sustain).
- ``x?0.6``: Probability suffix — fires with the given probability (0.0–1.0).
Parameters:
notation: The mini-notation string.
pitch: If provided, all symbols in the string are triggers for
this specific pitch. If ``None``, symbols are interpreted as
pitches (e.g., "60" or "kick").
velocity: MIDI velocity (default 100), or a ``(low, high)``
tuple for a fresh random draw per event.
Example:
```python
# Simple kick rhythm
p.seq("kick . [kick kick] .")
# Subdivided melody
p.seq("60 [62 64] 67 60")
# Ghost snare: snare on 2 and 4, ghost note 50% of the time
p.seq(". snare?0.5 . snare")
```
"""
rng = self._rng_from(seed, rng)
events = subsequence.mini_notation.parse(notation, total_duration=float(self._pattern.length))
for event in events:
# Apply probability before placing the note.
if event.probability < 1.0 and rng.random() >= event.probability:
continue
current_pitch = pitch
# If no global pitch provided, use the symbol as the pitch
if current_pitch is None:
# Try converting to int if it looks like a number
if event.symbol.isdigit():
current_pitch = int(event.symbol)
else:
current_pitch = event.symbol
self.note(
pitch = current_pitch,
beat = event.time,
duration = event.duration,
velocity = velocity
)
return self
[docs]
def repeat (self, pitch: typing.Union[int, str], spacing: float, velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_VELOCITY, duration: float = 0.25) -> "PatternBuilder":
"""
Repeat a note at a fixed beat interval for the whole pattern.
The classic 'Note Repeat' of MPC, Push, and Maschine fame: one
pitch firing at a steady rate — running hi-hats, a pulsing bass
note, a metronome click.
Parameters:
pitch: MIDI note number or drum name.
spacing: Time between each note in beats (0.25 = sixteenth notes).
velocity: MIDI velocity (default 100), or a ``(low, high)``
tuple for a fresh random draw per note.
duration: Note duration in beats.
Example:
```python
p.repeat("hh", spacing=0.25) # sixteenth notes
p.repeat("hh", spacing=0.25, velocity=(40, 80)) # humanised
```
"""
if spacing <= 0:
raise ValueError("Spacing must be positive")
beat = 0.0
while beat < self._pattern.length:
self.note(pitch=pitch, beat=beat, velocity=velocity, duration=duration)
beat += spacing
return self
[docs]
def arpeggio (
self,
notes: typing.Any,
root: typing.Optional[int] = None,
velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_VELOCITY,
count: typing.Optional[int] = None,
inversion: int = 0,
beat: float = 0.0,
span: typing.Optional[float] = None,
spacing: float = 0.25,
duration: typing.Optional[float] = None,
direction: str = "up",
seed: typing.Optional[int] = None,
rng: typing.Optional[random.Random] = None
) -> "PatternBuilder":
"""
Arpeggiate a chord (or a list of pitches) — cycle the notes one at a time
at regular beat intervals.
Like ``chord()`` and ``strum()``, the first argument can be a chord — the
``chord`` passed to your pattern function, or any chord from
``p.progression()`` — and ``root`` / ``count`` / ``inversion`` voice it
exactly as they do. So "play this as a chord, a strum, or an arpeggio" is a
one-word verb swap::
for chord, start, length in p.progression("phrygian_minor", harmonic_rhythm=...):
p.arpeggio(chord, root=48, beat=start, span=length, spacing=0.25, count=4)
Pass a list of pitches instead to arpeggiate something that isn't a chord (a
scale fragment, a custom voicing). Unlike a held ``chord()``, an arpeggio is
a stream of single notes, so it has no ``sustain`` / ``legato`` / ``detached``
— use ``duration`` for how long each note rings and ``span`` for how much of
the bar the figure fills.
An empty pitch list rests (places nothing), so a live arpeggiator over
``p.held_notes()`` is simply silent when no keys are held::
p.arpeggio(p.held_notes(), direction="up")
Parameters:
notes: A chord to arpeggiate (anything with a ``.tones()`` method — the
pattern's ``chord``, or a chord from ``p.progression()``), or a list
of MIDI note numbers (e.g. ``60``) / drum-name strings when the
pattern has a ``drum_note_map``. For pitched note *names* use the
integer constants in ``subsequence.constants.midi_notes`` (e.g.
``notes.C4``). In the list form, a drum name the map lacks is
dropped (warned once); a string with no map at all still raises.
root: MIDI root note for the chord form (e.g. 48), exactly as ``chord()``.
Required for a chord; not used for a plain pitch list.
velocity: MIDI velocity for all notes (default 100 — arpeggios sit in the
melodic-line velocity bucket, not the softened-chord bucket; pass
``velocity=90`` to match ``chord()``), or a ``(low, high)`` tuple for
a fresh random draw per note.
count: Number of voices for the chord form (cycles tones into higher
octaves if larger than the chord's natural size). Chord form only.
inversion: Chord inversion for the chord form (ignored when voice leading
is on). Chord form only.
beat: Beat to start the figure at (default 0.0 = the start of the
pattern). Use it to place an arpeggio over one progression chord.
span: How many beats the figure fills, starting at ``beat`` (default: to
the end of the pattern). Pass the chord's ``length`` from a
progression loop to confine the arpeggio to its slot.
spacing: Time between each note in beats (default 0.25 = 16th note).
duration: Note duration in beats. Defaults to ``spacing`` (each note
fills its slot exactly).
direction: Order in which the notes are cycled:
- ``"up"`` — lowest to highest, then wrap (default).
- ``"down"`` — highest to lowest, then wrap.
- ``"up_down"`` — ascend then descend (ping-pong), cycling.
- ``"random"`` — shuffled once per call using *rng*.
rng: Random number generator used when ``direction="random"``.
Defaults to ``self.rng`` (the pattern's seeded RNG).
Example:
```python
# Arpeggiate the pattern's current chord, four voices ascending
p.arpeggio(chord, root=60, count=4, spacing=0.25)
# A plain list of pitches — ping-pong: C E G E C E G E ...
p.arpeggio([60, 64, 67], spacing=0.25, direction="up_down")
# One chord of a progression, confined to its slot, humanised
p.arpeggio(chord, root=48, beat=start, span=length, velocity=(60, 95))
```
"""
if beat < 0:
raise ValueError("arpeggio beat must be >= 0 — use a positive start within the pattern")
if spacing <= 0:
raise ValueError("Spacing must be positive")
# Resolve the first argument into a concrete pitch list. A chord-like object
# (it has .tones()) is voiced via root/count/inversion exactly as chord() does;
# anything else is treated as an explicit list of pitches (today's behaviour).
resolved: typing.List[int]
if hasattr(notes, "tones"):
if root is None:
raise ValueError("arpeggio(<chord>, …) needs a root — e.g. arpeggio(chord, root=48); pass a root MIDI note, or hand a list of pitches instead")
resolved = notes.tones(root=root, inversion=inversion, count=count)
else:
if root is not None or count is not None or inversion != 0:
raise ValueError("arpeggio root=, count=, and inversion= only apply to the chord form — arpeggio(chord, root=48, count=4); with a plain pitch list, drop them")
if not notes:
return self # nothing held (e.g. p.arpeggio(p.held_notes()) with no keys down) — rest
resolved = [r for r in (self._resolve_pitch_lenient(p) for p in notes) if r is not None]
if not resolved:
return self # every named voice was dropped (this device lacks them all)
if direction == "up":
pass # already in ascending order as supplied
elif direction == "down":
resolved = list(reversed(resolved))
elif direction == "up_down":
if len(resolved) > 1:
resolved = resolved + list(reversed(resolved[1:-1]))
elif direction == "random":
rng = self._rng_from(seed, rng)
resolved = list(resolved)
rng.shuffle(resolved)
else:
raise ValueError(f"direction must be 'up', 'down', 'up_down', or 'random', got '{direction}'")
if duration is None:
duration = spacing
# Window the figure to [beat, beat + span), clamped to the pattern end so a
# positioned arpeggio (e.g. one chord of a progression) stays in its slot.
pattern_length = float(self._pattern.length)
if span is None:
end = pattern_length
else:
if span <= 0:
raise ValueError(f"span must be positive, got {span:g}")
end = beat + span
end = min(end, pattern_length)
# Place notes one at a time via self.note() so a (low, high)
# velocity tuple produces a fresh random draw per arp note.
position = beat
i = 0
while position < end:
self.note(
pitch = resolved[i % len(resolved)],
beat = position,
velocity = velocity,
duration = duration,
)
position += spacing
i += 1
return self
def _warn_positioned_articulation (self, method: str, beat: float) -> None:
"""Warn (once per pattern) that ``sustain``/``detached`` ring from the pattern
length, not from ``beat``.
``chord``/``strum`` size ``sustain``/``detached`` against the whole pattern (the
one-chord-fills-the-bar model). With a non-zero ``beat`` — e.g. placing several
chords across a progression — that almost always rings the chord far past its
slot, so we flag it. Deduped on the pattern so a hot-reloading builder warns once.
"""
if self._pattern._warned_positioned_articulation:
return
self._pattern._warned_positioned_articulation = True
logger.warning(
"%s(beat=%g, …) was called with sustain= or detached= set — those size the ring "
"from the pattern length, not from beat, so the chord can sustain past its slot. "
"For a positioned chord (e.g. over a progression) set duration= explicitly instead.",
method, beat,
)
[docs]
def chord (self, chord_obj: typing.Any, root: int, velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_CHORD_VELOCITY, sustain: bool = False, duration: float = 1.0, inversion: int = 0, count: typing.Optional[int] = None, legato: typing.Optional[float] = None, detached: typing.Optional[float] = None, beat: float = 0.0) -> "PatternBuilder":
"""
Place a chord at ``beat`` (the start of the pattern by default).
Note: If the pattern was registered with ``voice_leading=True``,
this method automatically chooses the best inversion.
Parameters:
chord_obj: The chord to play (usually the ``chord`` parameter
passed to your pattern function).
root: MIDI root note (e.g., 60 for Middle C).
velocity: MIDI velocity (default 90), or a ``(low, high)``
tuple for a fresh random draw per chord tone (each
voice gets a slightly different velocity — useful for
humanising the "fingers" feel).
sustain: If True, the notes last for the entire pattern duration.
Mutually exclusive with ``legato`` and ``detached``.
duration: Note duration in beats (default 1.0). Ignored when
``legato`` or ``detached`` is set, since those recalculate
durations.
inversion: Specific chord inversion (ignored if voice leading is on).
count: Number of notes to play (cycles tones if higher than
the chord's natural size).
legato: If given, calls ``p.legato(ratio)`` after placing the
chord, stretching each note to fill ``ratio`` of the gap to
the next note. Mutually exclusive with ``sustain`` and
``detached``.
detached: If given, the chord rings until ``detached`` beats
before the next cycle — equivalent to setting
``duration = pattern.length - detached``. Use this for a
declarative polyphony-safety margin so the chord always
releases before the next chord begins. Mutually exclusive
with ``sustain`` and ``legato``.
beat: Beat offset to place the chord at (default 0.0 = the start of the
pattern). ``sustain`` and ``detached`` still measure their ring from the
pattern length, not from ``beat`` — when placing several positioned chords
(e.g. over a progression) set ``duration`` explicitly instead.
Example::
# Shorthand for: p.chord(...) then p.legato(0.9)
p.chord(chord, root=root, velocity=85, count=4, legato=0.9)
# Hold the chord almost the full cycle, releasing 0.25 beats
# before the next chord begins.
p.chord(chord, root=root, velocity=85, count=5, detached=0.25)
"""
set_count = (1 if sustain else 0) + (1 if legato is not None else 0) + (1 if detached is not None else 0)
if set_count > 1:
raise ValueError("sustain=, legato=, and detached= are mutually exclusive — use one or the other")
if beat != 0.0 and (sustain or detached is not None):
self._warn_positioned_articulation("chord", beat)
pitches = chord_obj.tones(root=root, inversion=inversion, count=count)
if sustain:
duration = float(self._pattern.length)
elif detached is not None:
duration = float(self._pattern.length) - detached
if duration <= 0:
raise ValueError(f"detached ({detached}) must be less than the pattern length ({self._pattern.length:g} beats) so the chord keeps a positive duration")
for pitch in pitches:
self._pattern.add_note_beats(
beat_position = beat,
pitch = pitch,
velocity = self._resolve_velocity(velocity),
duration_beats = duration
)
if legato is not None:
self.legato(legato)
return self
[docs]
def strum (self, chord_obj: typing.Any, root: int, velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_CHORD_VELOCITY, sustain: bool = False, duration: float = 1.0, inversion: int = 0, count: typing.Optional[int] = None, spacing: float = 0.05, direction: str = "up", legato: typing.Optional[float] = None, detached: typing.Optional[float] = None, beat: float = 0.0) -> "PatternBuilder":
"""
Play a chord with a small time offset between each note (strum effect).
Works exactly like ``chord()`` but staggers the notes instead of
playing them simultaneously. The first note lands on ``beat`` (0 by default);
subsequent notes are delayed by ``spacing`` beats each.
Parameters:
chord_obj: The chord to play (usually the ``chord`` parameter
passed to your pattern function).
root: MIDI root note (e.g., 60 for Middle C).
velocity: MIDI velocity (default 90), or a ``(low, high)``
tuple for a fresh random draw per strum note.
sustain: If True, the notes last for the entire pattern duration.
Mutually exclusive with ``legato`` and ``detached``.
duration: Note duration in beats (default 1.0). Ignored when
``legato`` or ``detached`` is set, since those recalculate
durations.
inversion: Specific chord inversion (ignored if voice leading is on).
count: Number of notes to play (cycles tones if higher than
the chord's natural size).
spacing: Time in beats between each note onset (default 0.05).
direction: ``"up"`` for low-to-high, ``"down"`` for high-to-low.
beat: Beat offset for the first note (default 0.0); the stagger is added
on top. ``sustain``/``detached`` ring from the pattern length, not from
``beat`` — set ``duration`` explicitly when placing positioned strums.
legato: If given, calls ``p.legato(ratio)`` after placing the
chord, stretching each note to fill ``ratio`` of the gap to
the next note. Mutually exclusive with ``sustain`` and
``detached``.
detached: If given, every strum note rings with a uniform
duration of ``pattern.length - detached - (count - 1) * spacing``.
The last note ends exactly ``detached`` beats before the
next cycle; earlier notes end proportionally sooner, so
releases are staggered in the same shape as the placements
(the hand lifts the way it landed). Polyphony-safe:
guarantees nothing from this strum is still sounding when
the next chord begins. Mutually exclusive with ``sustain``
and ``legato``.
Example::
# Gentle upward strum with legato
p.strum(chord, root=52, velocity=85, spacing=0.06, legato=0.95)
# Fast downward strum
p.strum(chord, root=52, direction="down", spacing=0.03)
# Five-voice strum with a 0.25-beat safety gap before the
# next chord — won't exhaust polyphony on a 5-voice synth.
p.strum(chord, root=48, count=5, spacing=0.1, detached=0.25)
"""
set_count = (1 if sustain else 0) + (1 if legato is not None else 0) + (1 if detached is not None else 0)
if set_count > 1:
raise ValueError("sustain=, legato=, and detached= are mutually exclusive — use one or the other")
if beat != 0.0 and (sustain or detached is not None):
self._warn_positioned_articulation("strum", beat)
if spacing <= 0:
raise ValueError("spacing must be positive")
if direction not in ("up", "down"):
raise ValueError(f"direction must be 'up' or 'down', got '{direction}'")
pitches = chord_obj.tones(root=root, inversion=inversion, count=count)
if direction == "down":
pitches = list(reversed(pitches))
if sustain:
duration = float(self._pattern.length)
elif detached is not None:
duration = float(self._pattern.length) - detached - (len(pitches) - 1) * spacing
if duration <= 0:
raise ValueError(f"detached ({detached}) plus the strum stagger exceeds the pattern length ({self._pattern.length:g} beats) — reduce detached, spacing, or count")
for i, pitch in enumerate(pitches):
self.note(pitch=pitch, beat=beat + i * spacing, velocity=velocity, duration=duration)
if legato is not None:
self.legato(legato)
return self
[docs]
def progression (self, source: subsequence.progressions.ProgressionSource, harmonic_rhythm: subsequence.progressions.HarmonicRhythmSpec, key: typing.Optional[str] = None, seed: typing.Optional[int] = None, rng: typing.Optional[random.Random] = None) -> subsequence.progressions.Progression:
"""Realise a chord progression across the pattern, returning it to place yourself.
Returns a freshly realised :class:`~subsequence.progressions.Progression`
— an iterable of ``(chord, start, length)`` events laying a progression
end-to-end across the pattern's length, each chord given a length drawn
from *harmonic_rhythm* (the musical term for how often the chords
change). You loop over it and play each chord however you like —
block, strummed, or arpeggiated::
for chord, start, length in p.progression("phrygian_minor",
harmonic_rhythm=between(WHOLE, 3 * WHOLE, step=WHOLE), seed=7):
p.strum(chord, root=48, beat=start, duration=length - 0.25, spacing=0.04, count=4)
This is the **part-level** progression seam: it re-realises a fresh
value each rebuild (the breathing behaviour), runs entirely outside
the global harmonic clock — so a part can inhabit its own harmonic
world (polytonality) or move faster than the clock's span floor —
and never advances engine state.
For a one-call block-chord part with no loop, use ``composition.chords()``.
Parameters:
source: A built-in chord-graph style name (e.g. ``"phrygian_minor"``) to
*generate* a progression; an explicit element list — ints where
diatonic, name or roman strings (``["Cm7", 6, "bVII"]``), ``Chord``
objects — cycled to fill the pattern; or a
:class:`~subsequence.progressions.Progression` value (its spans
cycled, decoration preserved).
harmonic_rhythm: How long each chord lasts, in beats. One of: a single
number (static); a list of lengths (a shaped rhythm such as
``[WHOLE, HALF, HALF]``, cycled per chord); or ``between(low, high,
step=...)`` for a bounded, optionally-quantised random length.
key: Key for styles and key-relative elements (degrees/romans);
defaults to the composition's key.
seed: If given, the progression is realised from a fresh ``Random(seed)``
so it is identical on every cycle (a fixed phrase). When omitted, the
pattern's own RNG is used, so it can vary per cycle (still reproducible
under a composition seed).
Returns:
A ``Progression`` you can iterate as ``(chord, start, length)`` tuples
(or read via ``.events()`` / ``print()``).
"""
rng = self._rng_from(seed, rng)
resolved_key = key if key is not None else self.key
return subsequence.progressions.realize(
source = source,
harmonic_rhythm = harmonic_rhythm,
key = resolved_key,
length = float(self._pattern.length),
rng = rng,
scale = self.scale or "ionian",
)
[docs]
def broken_chord (self, chord_obj: typing.Any, root: int, order: typing.List[int], spacing: float = 0.25, velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_CHORD_VELOCITY, duration: typing.Optional[float] = None, inversion: int = 0, beat: float = 0.0, span: typing.Optional[float] = None) -> "PatternBuilder":
"""
Play a chord as an arpeggio in a specific or random order.
This generates the chord tones and maps them according to the provided
``order`` list of indices, then delegates to ``arpeggio()``. It is ideal
for broken chords or random chord-tone melodies.
Because the order is a list of node indices, the number of generated tones
is automatically set to ``max(order) + 1`` to ensure all indices are valid.
Higher indices will cycle into the next octave.
Parameters:
chord_obj: The chord to play (usually from ``p.section.chord``).
root: MIDI root note (e.g., 60 for Middle C).
order: List of indices into the chord tones array, dictating playback order.
spacing: Time between each note in beats (default 0.25 = 16th note).
velocity: MIDI velocity for all notes (default 90 — broken_chord is a
chord voice, so it sits in the softer chord velocity bucket like
``chord()`` and ``strum()``), or a ``(low, high)`` tuple for a
fresh random draw per note.
duration: Note duration in beats. Defaults to ``spacing``.
inversion: Specific chord inversion (ignored if voice leading is on).
beat: Beat to start the broken chord at (default 0.0).
span: How many beats to fill from ``beat`` (default: to the end of the
pattern). Like ``arpeggio()``, use it to place a broken chord over
one chord of a progression.
Example::
# A 5-note broken chord using a predefined pattern
p.broken_chord(chord, root=60, order=[4, 0, 2, 1, 3], spacing=0.25)
# A fully random broken chord using the pattern's deterministic RNG
order = list(range(5))
p.rng.shuffle(order)
p.broken_chord(chord, root=60, order=order)
"""
if not order:
raise ValueError("order list cannot be empty")
for idx in order:
if not isinstance(idx, int) or idx < 0:
raise ValueError("order must contain only non-negative integers")
required_count = max(order) + 1
tones = chord_obj.tones(root=root, inversion=inversion, count=required_count)
pitches = [tones[i] for i in order]
self.arpeggio(notes=pitches, spacing=spacing, velocity=velocity, duration=duration, direction="up", beat=beat, span=span)
return self
[docs]
def swing (self, percent: float = 57.0, grid: float = 0.25, strength: float = 1.0) -> "PatternBuilder":
"""
Apply swing feel to all notes in the pattern.
A shortcut for ``p.groove(Groove.swing(percent, grid), strength)``. Swing is a
groove where every other grid note is delayed - the simplest way to
give a mechanical pattern a pushed, human feel.
50% is perfectly straight (no swing). 57% is the Ableton default
(a gentle shuffle). 67% is classic triplet swing.
Parameters:
percent: Swing amount as a percentage (50-75 is the useful range).
50 = straight, 57 = moderate shuffle, 67 ≈ triplet swing.
grid: Grid size in beats (0.25 = 16th notes, 0.5 = 8th notes).
strength: How much swing to apply (0.0-1.0). 0.0 = no effect,
1.0 = full swing at the given percent. Useful for dialling
back the feel without changing the swing percentage.
Example::
p.hit_steps("hh", range(16), velocity=80)
p.swing(57) # gentle 16th-note shuffle
p.swing(57, strength=0.5) # half-strength — subtler feel
"""
self.groove(subsequence.groove.Groove.swing(percent=percent, grid=grid), strength=strength)
return self
[docs]
def groove (self, template: subsequence.groove.Groove, strength: float = 1.0) -> "PatternBuilder":
"""
Apply a groove template to all notes in the pattern.
A groove is a repeating pattern of per-step timing offsets and
optional velocity adjustments. It gives a pattern its characteristic
rhythmic feel - swing, shuffle, MPC pocket, or any custom shape.
Construct a groove with one of the factory methods:
- ``Groove.swing(percent)`` - simple swing by percentage
(or use the ``p.swing()`` shortcut for common cases)
- ``Groove.from_agr(path)`` - import timing from an Ableton .agr file
- ``Groove(offsets=[...], grid=0.25, velocities=[...])`` - fully custom
``p.groove()`` is a post-build transform - call it after all notes
have been placed. It pairs well with ``p.randomize()`` for
structured feel plus organic micro-variation.
Parameters:
template: A ``Groove`` instance defining the timing/velocity template.
strength: How much of the groove to apply (0.0-1.0). 0.0 = no
effect, 1.0 = full groove. Blends timing offsets and velocity
deviation proportionally - equivalent to Ableton's
TimingAmount and VelocityAmount dials.
Example::
groove = subsequence.Groove.swing(percent=57)
@composition.pattern(channel=10, beats=4)
def drums (p):
p.hit_steps("kick", [0, 8], velocity=100)
p.hit_steps("hh", range(16), velocity=80)
p.groove(groove) # full strength
p.groove(groove, strength=0.5) # half-strength blend
"""
self._pattern.steps = subsequence.groove.apply_groove(
self._pattern.steps, template, strength=strength
)
return self
# These methods transform existing notes after they have been placed.
# Call them at the end of your builder function, after all notes are
# in position. They operate on self._pattern.steps (the pulse-position
# dict) and can be chained in any order.
[docs]
def dropout (self, probability: float, seed: typing.Optional[int] = None, rng: typing.Optional[random.Random] = None) -> "PatternBuilder":
"""
Randomly remove notes from the pattern.
This operates on all notes currently placed in the builder.
Parameters:
probability: The chance (0.0 to 1.0) of each pulse POSITION being
removed — all notes sharing that position (a chord's voices,
layered drums) live or die together.
"""
rng = self._rng_from(seed, rng)
positions_to_remove = []
for position in list(self._pattern.steps.keys()):
if rng.random() < probability:
positions_to_remove.append(position)
for position in positions_to_remove:
del self._pattern.steps[position]
return self
[docs]
def velocity_shape (self, low: int = subsequence.constants.velocity.VELOCITY_SHAPE_LOW, high: int = subsequence.constants.velocity.VELOCITY_SHAPE_HIGH) -> "PatternBuilder":
"""
Apply organic velocity variation to all notes in the pattern.
Uses a van der Corput sequence to distribute velocities evenly
across the specified range, which often sounds more 'human' than
purely random velocity variation.
Parameters:
low: Minimum velocity (default 64).
high: Maximum velocity (default 127).
"""
positions = sorted(self._pattern.steps.keys())
if not positions:
return self
vdc_values = subsequence.sequence_utils.generate_van_der_corput_sequence(len(positions))
for position, vdc_value in zip(positions, vdc_values):
step = self._pattern.steps[position]
for note in step.notes:
note.velocity = int(low + (high - low) * vdc_value)
return self
[docs]
def duck_map (
self,
steps: typing.Iterable[int],
floor: float = 0.0,
grid: typing.Optional[int] = None,
) -> typing.List[float]:
"""
Build a per-step velocity multiplier list for sidechain-style ducking.
Returns a list of floats, one per grid step: ``floor`` at each trigger
step in ``steps``, ``1.0`` everywhere else. Pass the result to
``p.data`` for another pattern to read, then apply with
``p.scale_velocities()``.
Parameters:
steps: Grid indices that trigger ducking (e.g. kick hit positions).
floor: Multiplier written at trigger steps. ``0.0`` = full silence,
``1.0`` = no effect. Values in between give partial ducking.
grid: Grid resolution (defaults to ``p.grid``).
Returns:
``List[float]`` of length ``grid``.
Example::
# Full duck on kick hits
p.data["kick_sc"] = p.duck_map(kick_steps)
# Softer duck
p.data["kick_sc"] = p.duck_map(kick_steps, floor=0.3)
# Velocity-proportional: deeper duck for harder kicks
p.data["kick_sc"] = p.duck_map(kick_steps, floor=1.0 - (velocity / 127))
"""
if grid is None:
grid = self._default_grid
trigger = set(steps)
return [floor if s in trigger else 1.0 for s in range(grid)]
[docs]
def build_velocity_ramp (
self,
low: int,
high: int,
shape: str = "linear",
grid: typing.Optional[int] = None,
) -> typing.List[int]:
"""
Build a per-step velocity list that ramps from *low* to *high*.
A musician-friendly shortcut for the common pattern of generating
a fixed-length velocity sweep using an easing curve. Returns
``List[int]`` ready to pass directly to ``velocities=`` parameters.
Parameters:
low: Velocity at the first step (0–127).
high: Velocity at the last step (0–127).
shape: Easing curve name (see ``subsequence.easing``). Common
values: ``"linear"``, ``"ease_in"``, ``"ease_out"``,
``"ease_in_out"``. Defaults to ``"linear"``.
grid: Number of steps (defaults to ``p.grid``).
Returns:
``List[int]`` of length ``grid``, values clamped to 0–127.
Example::
# Snare roll that swells into a downbeat
p.sequence(
steps=range(16),
pitches="snare_1",
durations=0.1,
velocities=p.build_velocity_ramp(25, 100, "ease_in"),
)
# Fade-out ghost fill
p.ghost_fill("snare_1", 1,
velocity=p.build_velocity_ramp(80, 20, "ease_out"),
bias="sixteenths", no_overlap=True)
"""
if grid is None:
grid = self._default_grid
return [
max(0, min(127, int(v)))
for v in subsequence.easing.ramp(grid, float(low), float(high), shape)
]
[docs]
def scale_velocities (
self,
factors: typing.Sequence[float],
grid: typing.Optional[int] = None,
) -> "PatternBuilder":
"""
Scale note velocities by a per-step multiplier list.
Each note's velocity is multiplied by the factor at the corresponding
grid step index. A factor of ``1.0`` leaves the velocity unchanged;
``0.0`` silences the note; ``0.5`` halves it.
Parameters:
factors: Per-step multipliers, one float per grid step.
Values outside ``[0.0, 1.0]`` are valid — result is clamped to
``[0, 127]`` after scaling.
grid: Grid resolution (defaults to ``p.grid``). Must match the
length of ``factors``.
Returns:
``self`` for fluent chaining.
Example::
# Sidechain ducking: silence bass on kick steps, full volume elsewhere.
kick_steps = {0, 4, 8, 12}
p.data["kick_sc"] = [0.0 if s in kick_steps else 1.0 for s in range(p.grid)]
# In the bass pattern:
p.scale_velocities(p.data.get("kick_sc", [1.0] * p.grid))
"""
if grid is None:
grid = self._default_grid
step_duration = self._pattern.length / grid
pulses_per_step = step_duration * subsequence.constants.MIDI_QUARTER_NOTE
for pulse, step in self._pattern.steps.items():
idx = int(round(pulse / pulses_per_step))
if 0 <= idx < len(factors):
for note in step.notes:
note.velocity = max(0, min(127, int(note.velocity * factors[idx])))
return self
[docs]
def randomize (
self,
timing: float = 0.03,
velocity: float = 0.0,
seed: typing.Optional[int] = None,
rng: typing.Optional[random.Random] = None
) -> "PatternBuilder":
"""
Add random variations to note timing and velocity.
Introduces small imperfections — the micro-variations that distinguish
a played performance from a perfectly quantized sequence.
Called with no arguments, only timing variation is applied
(velocity defaults to 0.0 — no change). Pass a velocity value
to also randomise dynamics:
# Timing only (default)
p.randomize()
# Both axes
p.randomize(timing=0.04, velocity=0.08)
# Stronger feel
p.randomize(timing=0.08, velocity=0.15)
Resolution note: the sequencer runs at 24 PPQN. At 120 BPM, one
pulse ≈ 20ms. Timing shifts smaller than roughly 0.04 beats may
have no audible effect because they round to zero pulses.
Recommended range: timing=0.02–0.08, velocity=0.05–0.15.
When the composition has a seed set, ``p.rng`` is deterministic,
so ``p.randomize()`` produces the same result on every run.
Parameters:
timing: Maximum timing offset in beats (e.g. 0.05 = ±1.2
pulses at 24 PPQN). Notes shift by a random amount
within ``[-timing, +timing]`` beats. Clamped to
pulse 0 at the lower bound.
velocity: Maximum velocity scale factor (0.0 to 1.0). Each
note's velocity is multiplied by a random value in
``[1 - velocity, 1 + velocity]``, clamped to 1–127.
rng: Random instance to use. Defaults to ``self.rng``
(seeded when the composition has a seed).
"""
rng = self._rng_from(seed, rng)
max_timing_pulses = timing * subsequence.constants.MIDI_QUARTER_NOTE
new_steps: typing.Dict[int, subsequence.pattern.Step] = {}
for pulse, step in self._pattern.steps.items():
if timing != 0.0:
offset = rng.uniform(-max_timing_pulses, max_timing_pulses)
new_pulse = max(0, int(round(pulse + offset)))
else:
new_pulse = pulse
if new_pulse not in new_steps:
new_steps[new_pulse] = subsequence.pattern.Step()
# Process notes: randomise velocity once per note, then place in new bucket.
for note in step.notes:
if velocity != 0.0:
scale = rng.uniform(1.0 - velocity, 1.0 + velocity)
note.velocity = max(1, min(127, int(round(note.velocity * scale))))
new_steps[new_pulse].notes.append(note)
self._pattern.steps = new_steps
return self
[docs]
def legato (self, ratio: float = 1.0) -> "PatternBuilder":
"""
Adjust note durations to fill the gap until the next note.
Parameters:
ratio: How much of the gap to fill (0.0 to 1.0).
1.0 is full legato, < 1.0 is staccato.
"""
if not self._pattern.steps:
return self
sorted_positions = sorted(self._pattern.steps.keys())
total_pulses = int(self._pattern.length * subsequence.constants.MIDI_QUARTER_NOTE)
for i, position in enumerate(sorted_positions):
# Calculate gap to next note
if i < len(sorted_positions) - 1:
gap = sorted_positions[i + 1] - position
else:
# Wrap around: gap is distance to end + distance to first note
gap = (total_pulses - position) + sorted_positions[0]
# Apply ratio and enforce minimum duration
new_duration = max(1, int(gap * ratio))
step = self._pattern.steps[position]
for note in step.notes:
note.duration = new_duration
return self
[docs]
def duration (self, beats: float) -> "PatternBuilder":
"""
Set every note's duration to a fixed length in beats.
This overrides any existing note durations, acting as a global
'gate time' relative to the beat (1.0 = a quarter note). Short
values clip notes tight; long values let them ring. For a
guaranteed gap before each next onset regardless of note spacing,
use :meth:`detached`; for a classic staccato articulation, either
a short fixed value (``p.duration(0.1)``) or ``p.detached()`` works.
Parameters:
beats: Fixed note duration in beats (relative to a quarter note).
0.5 = eighth-note length, 0.25 = sixteenth-note length. Must be positive.
"""
if beats <= 0:
raise ValueError("Note duration (beats) must be positive")
duration_pulses = int(beats * subsequence.constants.MIDI_QUARTER_NOTE)
duration_pulses = max(1, duration_pulses)
for step in self._pattern.steps.values():
for note in step.notes:
note.duration = duration_pulses
return self
[docs]
def detached (self, beats: float = 0.05) -> "PatternBuilder":
"""
Shorten note durations so a guaranteed silence precedes the next onset.
The complement of :meth:`legato`. For every placed note, the duration
is shrunk so that at least ``beats`` beats of silence remain before
the next note begins (wrapping around to the first note for the last
one). Use this when you want a clean detached articulation, or as a
polyphony-safety margin between chord transitions on a monophonic or
voice-limited synth.
Parameters:
beats: Minimum gap in beats before the next onset (default 0.05
— roughly 25 ms at 120 BPM). Must be positive.
Example::
# Bassline on a mono synth: each 16th note ends 0.05 beats
# before the next, so the synth never retriggers mid-note.
p.arpeggio(chord.tones(36, count=4), spacing=0.25).detached()
# Explicit larger gap for a longer release tail.
p.melody(state, spacing=0.25).detached(0.1)
"""
if beats <= 0:
raise ValueError("detached beats must be positive")
if not self._pattern.steps:
return self
sorted_positions = sorted(self._pattern.steps.keys())
total_pulses = int(self._pattern.length * subsequence.constants.MIDI_QUARTER_NOTE)
detached_pulses = int(beats * subsequence.constants.MIDI_QUARTER_NOTE)
for i, position in enumerate(sorted_positions):
# Calculate gap to next note (wrap-around for the last one)
if i < len(sorted_positions) - 1:
gap = sorted_positions[i + 1] - position
else:
gap = (total_pulses - position) + sorted_positions[0]
new_duration = max(1, gap - detached_pulses)
for note in self._pattern.steps[position].notes:
note.duration = new_duration
return self
[docs]
def snap_to_scale (self, key: str, mode: str = "ionian", strength: float = 1.0, seed: typing.Optional[int] = None, rng: typing.Optional[random.Random] = None) -> "PatternBuilder":
"""
Snap all notes in the pattern to the nearest pitch in a scale.
Useful after generative or sensor-driven pitch work (random walks,
mapping data values to note numbers, etc.) to ensure every note lands
on a musically valid scale degree. The snap is applied in
place; notes already on a scale degree are left unchanged.
When a note falls equidistant between two scale tones, the upward
direction is preferred.
Parameters:
key: Root note name (e.g. ``"C"``, ``"F#"``, ``"Bb"``).
mode: Scale mode. Any key in :data:`subsequence.intervals.DIATONIC_MODE_MAP`
is accepted: ``"ionian"`` (default), ``"dorian"``, ``"minor"``,
``"harmonic_minor"``, etc.
strength: Probability that each note is snapped (0.0–1.0).
At 1.0 (default), every note snaps to the scale.
At 0.0, no notes are affected.
Values in between create melodies that are mostly in key
with occasional chromatic passing tones. Uses the
pattern's seeded RNG for reproducibility.
Example:
```python
@composition.pattern(channel=1, beats=4)
def melody (p):
for beat in range(16):
pitch = 60 + random.randint(-5, 5)
p.note(pitch, beat=beat * 0.25)
p.snap_to_scale("G", "dorian", strength=0.8)
```
"""
rng = self._rng_from(seed, rng)
key_pc = subsequence.chords.key_name_to_pc(key)
scale_pcs = subsequence.intervals.scale_pitch_classes(key_pc, mode)
for step in self._pattern.steps.values():
for note in step.notes:
if strength >= 1.0 or rng.random() < strength:
note.pitch = subsequence.intervals.quantize_pitch(note.pitch, scale_pcs)
return self
[docs]
def apply_tuning (
self,
tuning: "subsequence.tuning.Tuning",
bend_range: float = 2.0,
channels: typing.Optional[typing.List[int]] = None,
reference_note: int = 60,
) -> "PatternBuilder":
"""Apply a microtonal tuning to this pattern via pitch bend injection.
For each note in the pattern, the nearest 12-TET MIDI pitch is
computed and a pitchwheel ``CcEvent`` is injected at the note's onset
to shift the synthesiser to the exact tuned frequency. Existing pitch
bend events (from ``p.portamento()``, ``p.slide()``, etc.) are shifted
additively so they still work correctly within the tuned pitch space.
For polyphonic patterns, supply a ``channels`` pool. Notes will be
spread across those channels so each can carry an independent pitch
bend. For monophonic patterns, leave ``channels=None``.
The synthesiser's pitch-bend range must match ``bend_range``. Most
synths default to ±2 semitones. For tunings that deviate more than
one semitone from 12-TET, increase ``bend_range`` (e.g., 12 or 24)
and configure the synth to match.
Parameters:
tuning: The :class:`~subsequence.tuning.Tuning` to apply.
bend_range: Synth pitch-bend range in semitones (default ±2).
channels: Channel pool for polyphonic rotation. ``None`` keeps
all notes on the pattern's own channel.
reference_note: MIDI note number that maps to scale degree 0.
Default 60 (middle C).
Example:
```python
from subsequence import Tuning
meantone = Tuning.from_scl("meanquar.scl")
@composition.pattern(channel=1, beats=4)
def melody (p):
p.seq("x x x x", pitch=60)
p.apply_tuning(meantone, bend_range=2.0)
```
"""
import subsequence.tuning
subsequence.tuning.apply_tuning_to_pattern(
self._pattern,
tuning,
bend_range=bend_range,
channels=channels,
reference_note=reference_note,
)
self._tuning_applied = True
return self
[docs]
def reverse (self) -> "PatternBuilder":
"""
Flip the pattern backwards in time (retrograde).
"""
total_pulses = int(self._pattern.length * subsequence.constants.MIDI_QUARTER_NOTE)
old_steps = self._pattern.steps
new_steps: typing.Dict[int, subsequence.pattern.Step] = {}
for position, step in old_steps.items():
# Reflect around the bar so onsets stay on the grid and the downbeat
# is fixed — a true retrograde reverses the inter-onset intervals
# (e.g. [0, 24] → [0, 72] in a 96-pulse bar, not the off-grid
# [71, 95] the old (total-1)-position produced).
new_position = (total_pulses - position) % total_pulses
if new_position not in new_steps:
new_steps[new_position] = subsequence.pattern.Step()
new_steps[new_position].notes.extend(step.notes)
self._pattern.steps = new_steps
return self
[docs]
def stretch (self, factor: float) -> "PatternBuilder":
"""
Stretch the pattern in time, scaling note positions and durations.
``stretch(2.0)`` makes everything twice as long (half speed) — what
theorists call *augmentation*; ``stretch(0.5)`` squeezes the pattern
into half the time (double speed) — *diminution*. Any positive
factor works: ``stretch(2/3)`` compresses a dotted feel into
straight time, for example.
Notes whose start lands past the end of the pattern are dropped,
and compression leaves the freed space empty — the pattern is not
tiled to fill it. Durations scale without clipping, so a stretched
note may ring past the pattern's end exactly like a legato note,
and ``stretch(1.0)`` is a true no-op. Positions and durations
truncate to the pulse grid (matching ``note()``'s beat-to-pulse
truncation).
Parameters:
factor: Time multiplier. Greater than 1.0 slows the pattern
down, less than 1.0 speeds it up. Must be positive.
"""
if factor <= 0:
raise ValueError("Stretch factor must be positive")
total_pulses = int(self._pattern.length * subsequence.constants.MIDI_QUARTER_NOTE)
old_steps = self._pattern.steps
new_steps: typing.Dict[int, subsequence.pattern.Step] = {}
for position, step in old_steps.items():
new_position = int(position * factor)
if new_position >= total_pulses:
continue
if new_position not in new_steps:
new_steps[new_position] = subsequence.pattern.Step()
new_steps[new_position].notes.extend(
dataclasses.replace(
note,
duration = max(1, int(note.duration * factor)),
)
for note in step.notes
)
self._pattern.steps = new_steps
return self
[docs]
def rotate (self, steps: int, grid: typing.Optional[int] = None) -> "PatternBuilder":
"""
Rotate the pattern by a number of grid steps, wrapping around.
Notes pushed past the end of the pattern re-enter at the start
(and vice versa for negative values) — the step-sequencer rotation
familiar from Euclidean rhythm tools.
Parameters:
steps: Positive values rotate later in time, negative values earlier.
grid: The grid resolution. Defaults to the pattern's
``default_grid`` (derived from the decorator's ``beats``/``steps``
and ``step_duration``).
"""
if grid is None:
grid = self._default_grid
total_pulses = int(self._pattern.length * subsequence.constants.MIDI_QUARTER_NOTE)
pulses_per_step = total_pulses / grid
shift_pulses = int(steps * pulses_per_step)
old_steps = self._pattern.steps
new_steps: typing.Dict[int, subsequence.pattern.Step] = {}
for position, step in old_steps.items():
new_position = (position + shift_pulses) % total_pulses
if new_position not in new_steps:
new_steps[new_position] = subsequence.pattern.Step()
new_steps[new_position].notes.extend(step.notes)
self._pattern.steps = new_steps
return self
[docs]
def transpose (self, semitones: int) -> "PatternBuilder":
"""
Shift all note pitches up or down.
Parameters:
semitones: Positive for up, negative for down.
"""
for step in self._pattern.steps.values():
for note in step.notes:
note.pitch = max(0, min(127, note.pitch + semitones))
return self
[docs]
def invert (self, pivot: int = 60) -> "PatternBuilder":
"""
Invert all pitches around a pivot note.
"""
for step in self._pattern.steps.values():
for note in step.notes:
note.pitch = max(0, min(127, pivot + (pivot - note.pitch)))
return self
[docs]
def every (self, n: int, fn: typing.Callable[["PatternBuilder"], None]) -> "PatternBuilder":
"""
Apply a transformation every Nth cycle.
Parameters:
n: The cycle frequency (e.g., 4 = every 4th bar).
fn: A function (often a lambda) that receives the builder and
calls further methods.
Example:
```python
# Reverse every 4th bar
p.every(4, lambda p: p.reverse())
```
"""
if self.cycle % n == 0:
fn(self)
return self
[docs]
def bar_cycle (self, length: int) -> BarCycle:
"""Return the current bar's position within a repeating cycle of bars.
A thin wrapper around ``p.bar % length`` that replaces opaque modulo
arithmetic with readable, musician-friendly properties.
Parameters:
length: The cycle length in bars (e.g., 4, 8, 16).
Returns:
A :class:`BarCycle` with ``.bar``, ``.first``, ``.last``,
and ``.progress`` properties.
Example:
```python
# Every 4 bars (replaces: if p.bar % 4 == 0)
if p.bar_cycle(4).first:
p.hit_steps("snare_1", [0, 8], velocity=110)
# Last bar of every 16-bar cycle (replaces: if p.bar % 16 == 15)
if p.bar_cycle(16).last:
p.euclidean("hi_hat_open", 3)
# Build intensity over an 8-bar arc
intensity = p.bar_cycle(8).progress # 0.0 → 0.875
p.velocity_shape(low=int(40 + 40 * intensity), high=100)
```
"""
return BarCycle(bar=self.bar % length, length=length)