subsequence 0.6.4__py3-none-any.whl

subsequence/forms.py

@@ -0,0 +1,257 @@
+"""Forms — the governing values for compositional structure.
+
+:class:`Section` is the payload home: a frozen ``(name, bars, energy, key)``
+leaf.  :class:`Form` is a frozen tuple of Sections — constructible from
+Sections or plain ``(name, bars)`` tuples (lists coerce), editable by slot
+(:meth:`Form.replace` / :meth:`Form.insert` / :meth:`Form.with_energy`),
+and concatenable with ``+``.  Repetition is Python:
+``[verse, verse, chorus] == [verse] * 2 + [chorus]`` — no letters DSL.
+
+Bind a Form with ``composition.form(form, at_end="stop"|"hold"|"loop")``;
+generate one from a graph form with ``composition.form_freeze()``.
+
+Sections compose as plain Python lists that Form coerces — ``Section`` is a
+leaf, not an operator algebra.
+"""
+
+import dataclasses
+import typing
+
+
+@dataclasses.dataclass(frozen=True)
+class Section:
+
+	"""One section of a form — the payload home.
+
+	Attributes:
+		name: The section name (``"verse"``).
+		bars: Length in bars (≥ 1).
+		energy: The section's energy level (0.0–1.0; the arranging dial).
+			Read by ``p.energy`` and ``min_energy=`` gating; a
+			``composition.energy()`` dict overrides it (the dict is the
+			later, performance-level dial).
+		key: Optional key override — re-anchors *key-relative* content
+			(degrees, romans, generated material, and key-relative section
+			progressions bound with ``section_chords``) to this section's
+			tonic.  *Absolute* content (note names, MIDI pitches, frozen
+			chords) is never moved, and *chord-relative* content
+			(``ChordTone``, ``Approach``) tracks the sounding chord rather
+			than the key — see the three-intent model in the docs.  The
+			live graph engine (``harmony(style=...)``) stays in the
+			composition key by design (a stateful walk does not transpose
+			mid-stream).
+		scale: Optional scale/mode override (e.g. ``"minor"``) — moves the
+			mode as well as the tonic, so a section can genuinely change
+			to the relative or parallel minor.  Falls back to the form's
+			scale, then the composition's.
+	"""
+
+	name: str
+	bars: int
+	energy: float = 0.5
+	key: typing.Optional[str] = None
+	scale: typing.Optional[str] = None
+
+	def __post_init__ (self) -> None:
+
+		"""Validate the payload loudly."""
+
+		if not isinstance(self.name, str) or not self.name:
+			raise ValueError(f"a section needs a non-empty string name, got {self.name!r}")
+
+		if not isinstance(self.bars, int) or isinstance(self.bars, bool) or self.bars < 1:
+			raise ValueError(f"Section {self.name!r} must last at least 1 bar, got {self.bars!r}")
+
+		if not 0.0 <= float(self.energy) <= 1.0:
+			raise ValueError(f"Section {self.name!r} energy must be 0.0–1.0, got {self.energy!r}")
+
+
+def _coerce_section (element: typing.Any) -> Section:
+
+	"""Coerce a Form element — a Section passes through, a (name, bars) tuple converts."""
+
+	if isinstance(element, Section):
+		return element
+
+	if isinstance(element, tuple) and len(element) == 2:
+		name, bars = element
+		return Section(name = name, bars = bars)
+
+	raise TypeError(
+		f"Form elements are Sections or (name, bars) tuples — got {element!r}"
+	)
+
+
+@dataclasses.dataclass(frozen=True)
+class Form:
+
+	"""A frozen sequence of Sections — the editable, bindable form value.
+
+	List-friendly: the constructor coerces ``("name", bars)`` tuples, so
+	``Form([("verse", 8), ("chorus", 8)])`` and
+	``Form([Section("verse", 8), Section("chorus", 8)])`` are the same value.
+	Repetition is Python list arithmetic before construction.
+
+	A form may carry its own ``key``/``scale`` — the **form tier** of the
+	key-source chain (``Section.key`` overrides it; it overrides the
+	composition key).  A whole AABA in one key with one section borrowing
+	another is ``Form([...], key="A")`` plus a ``Section(..., key="F")``.
+	"""
+
+	sections: typing.Tuple[Section, ...]
+	key: typing.Optional[str] = None
+	scale: typing.Optional[str] = None
+
+	def __init__ (
+		self,
+		sections: typing.Iterable[typing.Any],
+		key: typing.Optional[str] = None,
+		scale: typing.Optional[str] = None,
+	) -> None:
+
+		"""Coerce any iterable of Sections / (name, bars) tuples."""
+
+		coerced = tuple(_coerce_section(element) for element in sections)
+
+		if not coerced:
+			raise ValueError("a Form needs at least one section")
+
+		object.__setattr__(self, "sections", coerced)
+		object.__setattr__(self, "key", key)
+		object.__setattr__(self, "scale", scale)
+
+	@property
+	def bars (self) -> int:
+
+		"""Total length in bars."""
+
+		return sum(section.bars for section in self.sections)
+
+	def __len__ (self) -> int:
+
+		"""Number of sections."""
+
+		return len(self.sections)
+
+	def __iter__ (self) -> typing.Iterator[Section]:
+
+		"""Iterate the sections in order."""
+
+		return iter(self.sections)
+
+	def __add__ (self, other: "Form") -> "Form":
+
+		"""Sequential concatenation: ``intro_form + body_form``.
+
+		The **left** operand's form-tier ``key``/``scale`` survives (a single
+		value cannot hold two form keys); the right form's form-tier key is
+		dropped.  Per-section ``Section.key``/``scale`` on either side is
+		preserved — the sections concatenate intact.
+		"""
+
+		if not isinstance(other, Form):
+			return NotImplemented
+
+		return Form(self.sections + other.sections, key = self.key, scale = self.scale)
+
+	def replace (
+		self,
+		slot: int,
+		section: typing.Optional[Section] = None,
+		**changes: typing.Any,
+	) -> "Form":
+
+		"""Replace the section at a 1-based slot — whole, or by field.
+
+		``form.replace(3, bars=16)`` stretches slot 3;
+		``form.replace(3, Section("drop", 16, energy=1.0))`` swaps it out.
+		"""
+
+		index = _check_slot(slot, len(self.sections))
+
+		if section is not None and changes:
+			raise ValueError("pass either a Section or field changes, not both")
+
+		if section is None:
+			if not changes:
+				raise ValueError("replace() needs a Section or field changes (bars=, energy=, key=, name=)")
+			section = dataclasses.replace(self.sections[index], **changes)
+
+		return Form(self.sections[:index] + (_coerce_section(section),) + self.sections[index + 1:], key = self.key, scale = self.scale)
+
+	def insert (self, slot: int, section: typing.Any) -> "Form":
+
+		"""Insert a section *at* a 1-based slot (existing sections shift right).
+
+		``slot`` may be ``len(form) + 1`` to append.
+		"""
+
+		if not isinstance(slot, int) or isinstance(slot, bool) or not 1 <= slot <= len(self.sections) + 1:
+			raise ValueError(f"slot {slot!r} is out of range (1–{len(self.sections) + 1})")
+
+		index = slot - 1
+
+		return Form(self.sections[:index] + (_coerce_section(section),) + self.sections[index:], key = self.key, scale = self.scale)
+
+	def with_energy (self, energies: typing.Dict[str, float]) -> "Form":
+
+		"""Set the energy payload on named sections — ``{"chorus": 0.9}``.
+
+		Every section whose name appears in the mapping takes the new value;
+		naming a section the form does not contain raises.  Energy *ramps*
+		(``(start, end)`` tuples) live in ``composition.energy()``, not in
+		the payload — a Section carries one number.
+		"""
+
+		names = {section.name for section in self.sections}
+
+		for name in energies:
+			if name not in names:
+				known = ", ".join(sorted(names))
+				raise ValueError(f"with_energy: no section named {name!r} in this form (sections: {known})")
+
+		return Form(tuple(
+			dataclasses.replace(section, energy = energies[section.name])
+			if section.name in energies else section
+			for section in self.sections
+		), key = self.key, scale = self.scale)
+
+	def describe (self) -> str:
+
+		"""A readable one-section-per-line summary."""
+
+		lines = [f"Form — {len(self.sections)} sections over {self.bars} bars"]
+
+		if self.key is not None or self.scale is not None:
+			lines.append(f"  (form key={self.key or '–'} scale={self.scale or '–'})")
+
+		bar = 1
+
+		for slot, section in enumerate(self.sections, start = 1):
+			extras = f"  energy={section.energy:g}"
+			if section.key is not None:
+				extras += f"  key={section.key}"
+			if section.scale is not None:
+				extras += f"  scale={section.scale}"
+			lines.append(f"  {slot}. bars {bar}–{bar + section.bars - 1}  {section.name:<10} ({section.bars} bars){extras}")
+			bar += section.bars
+
+		return "\n".join(lines)
+
+	def __str__ (self) -> str:
+
+		"""Same as :meth:`describe`."""
+
+		return self.describe()
+
+
+def _check_slot (slot: int, count: int) -> int:
+
+	"""Validate a 1-based section slot and return its 0-based index."""
+
+	if not isinstance(slot, int) or isinstance(slot, bool):
+		raise TypeError(f"section slots are 1-based ints, got {slot!r}")
+	if slot < 1 or slot > count:
+		raise ValueError(f"section slot {slot} is out of range (1–{count})")
+
+	return slot - 1

subsequence/groove.py

@@ -0,0 +1,323 @@
+"""
+Groove templates — repeating timing and velocity feels applied to quantized patterns.
+
+Exports the public Groove class: build one by hand, from a swing percentage,
+or from an Ableton ``.agr`` file, then apply it with ``p.groove(template)``.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import typing
+import xml.etree.ElementTree
+
+import subsequence.constants
+
+if typing.TYPE_CHECKING:
+	import subsequence.pattern
+
+
+@dataclasses.dataclass
+class Groove:
+
+	"""
+	A timing/velocity template applied to quantized grid positions.
+
+	A groove is a repeating pattern of per-step timing offsets and optional
+	velocity adjustments aligned to a rhythmic grid. Apply it as a post-build
+	transform with ``p.groove(template)`` to give a pattern its characteristic
+	feel — swing, shuffle, MPC-style pocket, or anything extracted from an
+	Ableton ``.agr`` file.
+
+	Parameters:
+		offsets: Timing offset per grid slot, in beats. Repeats cyclically.
+			Positive values delay the note; negative values push it earlier.
+		grid: Grid size in beats (0.25 = 16th notes, 0.5 = 8th notes).
+		velocities: Optional velocity scale per grid slot (1.0 = unchanged).
+			Repeats cyclically alongside offsets.
+
+	Example::
+
+		# Ableton-style 57% swing on 16th notes
+		groove = Groove.swing(percent=57)
+
+		# Custom groove with timing and velocity
+		groove = Groove(
+			grid=0.25,
+			offsets=[0.0, +0.02, 0.0, -0.01],
+			velocities=[1.0, 0.7, 0.9, 0.6],
+		)
+	"""
+
+	offsets: typing.List[float]
+	grid: float = 0.25
+	velocities: typing.Optional[typing.List[float]] = None
+
+	def __post_init__ (self) -> None:
+		if not self.offsets:
+			raise ValueError("offsets must not be empty")
+		if self.grid <= 0:
+			raise ValueError("grid must be positive")
+		if self.velocities is not None and not self.velocities:
+			raise ValueError("velocities must not be empty (use None for no velocity adjustment)")
+
+	@staticmethod
+	def swing (percent: float = 57.0, grid: float = 0.25) -> "Groove":
+
+		"""
+		Create a swing groove from a percentage.
+
+		50% is straight (no swing). 67% is approximately triplet swing.
+		57% is a moderate shuffle — the Ableton default.
+
+		Parameters:
+			percent: Swing amount (50–75 is the useful range).
+			grid: Grid size in beats (0.25 = 16ths, 0.5 = 8ths).
+		"""
+
+		if percent < 50.0 or percent > 99.0:
+			raise ValueError("swing percent must be between 50 and 99")
+		pair_duration = grid * 2
+		offset = (percent / 100.0 - 0.5) * pair_duration
+		return Groove(offsets=[0.0, offset], grid=grid)
+
+	@staticmethod
+	def from_agr (path: str, grid: typing.Optional[float] = None) -> "Groove":
+
+		"""
+		Import timing and velocity data from an Ableton .agr groove file.
+
+		An ``.agr`` file is an XML document containing a MIDI clip whose
+		note positions encode the groove's rhythmic feel. This method reads
+		those note start times and velocities and converts them into the
+		``Groove`` dataclass format (per-step offsets and velocity scales).
+
+		Without ``grid=``, the grid is inferred as ``clip length / note
+		count`` — which assumes the clip plays **exactly one note per grid
+		cell** (the standard shape for a groove clip). A clip with rests or
+		chords breaks that assumption: pass ``grid=`` explicitly (e.g.
+		``grid=0.25`` for a 16th-note groove) and empty cells keep a neutral
+		offset. A clip whose notes cannot be assigned one-per-cell raises
+		rather than importing a wrong feel.
+
+		**What is extracted:**
+
+		- ``Time`` attribute of each ``MidiNoteEvent`` → timing offsets
+		  relative to ideal grid positions.
+		- ``Velocity`` attribute of each ``MidiNoteEvent`` → velocity
+		  scaling (normalised to the highest velocity in the file).
+		- ``TimingAmount`` from the Groove element → pre-scales the timing
+		  offsets (100 = full, 70 = 70% of the groove's timing).
+		- ``VelocityAmount`` from the Groove element → pre-scales velocity
+		  deviation (100 = full groove velocity, 0 = no velocity changes).
+
+		The resulting ``Groove`` reflects the file author's intended
+		strength. Use ``strength=`` when applying to further adjust.
+
+		**What is NOT imported:**
+
+		``RandomAmount`` (use ``p.randomize()`` separately for random
+		jitter) and ``QuantizationAmount`` (not applicable - Subsequence
+		notes are already grid-quantized by construction).
+
+		Other ``MidiNoteEvent`` fields (``Duration``, ``VelocityDeviation``,
+		``OffVelocity``, ``Probability``) are also ignored.
+
+		Parameters:
+			path: Path to the .agr file.
+			grid: Grid size in beats (0.25 = 16th notes). ``None`` (default)
+				infers it from the clip, assuming one note per cell.
+		"""
+
+		tree = xml.etree.ElementTree.parse(path)
+		root = tree.getroot()
+
+		# Find the MIDI clip
+		clip = root.find(".//MidiClip")
+		if clip is None:
+			raise ValueError(f"No MidiClip found in {path}")
+
+		# Get clip length
+		current_end = clip.find("CurrentEnd")
+		if current_end is None:
+			raise ValueError(f"No CurrentEnd found in {path}")
+		clip_length = float(current_end.get("Value", "4"))
+
+		# Read Groove Pool blend parameters
+		groove_elem = root.find(".//Groove")
+		timing_amount = 100.0
+		velocity_amount = 100.0
+		if groove_elem is not None:
+			timing_el = groove_elem.find("TimingAmount")
+			if timing_el is not None:
+				timing_amount = float(timing_el.get("Value", "100"))
+			velocity_el = groove_elem.find("VelocityAmount")
+			if velocity_el is not None:
+				velocity_amount = float(velocity_el.get("Value", "100"))
+
+		timing_scale = timing_amount / 100.0
+		velocity_scale = velocity_amount / 100.0
+
+		# Extract note events sorted by time
+		events = clip.findall(".//MidiNoteEvent")
+		if not events:
+			raise ValueError(f"No MidiNoteEvent elements found in {path}")
+
+		times: typing.List[float] = []
+		velocities_raw: typing.List[float] = []
+		for event in events:
+			times.append(float(event.get("Time", "0")))
+			velocities_raw.append(float(event.get("Velocity", "127")))
+
+		# Sort as PAIRS - sorting times alone desynced each offset from its
+		# note's velocity whenever the XML listed events out of time order.
+		paired = sorted(zip(times, velocities_raw))
+		times = [t for t, _ in paired]
+		velocities_raw = [v for _, v in paired]
+
+		note_count = len(times)
+
+		# Infer grid from clip length and note count — valid only for the
+		# one-note-per-cell clip shape (see docstring); grid= overrides.
+		if grid is None:
+			grid = clip_length / note_count
+
+		if grid <= 0:
+			raise ValueError(f"grid must be positive — got {grid}")
+
+		slot_count = max(1, int(round(clip_length / grid)))
+
+		# Bind each note to its NEAREST grid line (robust to rests under an
+		# explicit grid — empty cells keep a neutral offset), refusing
+		# ambiguous clips instead of importing a garbage feel.
+		slot_offsets = [0.0] * slot_count
+		slot_velocities: typing.List[typing.Optional[float]] = [None] * slot_count
+
+		for time, velocity in zip(times, velocities_raw):
+
+			slot = int(round(time / grid))
+
+			if not 0 <= slot < slot_count:
+				raise ValueError(
+					f"{path}: note at beat {time:g} falls outside the {slot_count}-cell "
+					f"grid (grid={grid:g}, clip length {clip_length:g}) — pass grid= "
+					"matching the clip's note spacing"
+				)
+
+			if slot_velocities[slot] is not None:
+				raise ValueError(
+					f"{path}: two notes share grid cell {slot} (a chord, or a grid "
+					"coarser than the clip's note spacing) — pass grid= matching the "
+					"clip (e.g. grid=0.25 for 16ths)"
+				)
+
+			slot_offsets[slot] = (time - slot * grid) * timing_scale
+			slot_velocities[slot] = velocity
+
+		# Calculate velocity scales (relative to max velocity in the file),
+		# blended toward 1.0 by VelocityAmount; empty cells stay neutral (1.0).
+		filled = [v for v in slot_velocities if v is not None]
+		max_vel = max(filled)
+		has_velocity_variation = any(v != max_vel for v in filled)
+		groove_velocities: typing.Optional[typing.List[float]] = None
+		if has_velocity_variation and max_vel > 0:
+			raw_scales = [(v / max_vel) if v is not None else 1.0 for v in slot_velocities]
+			# velocity_scale=1.0 → full groove velocity; 0.0 → all 1.0 (no change)
+			groove_velocities = [1.0 + (s - 1.0) * velocity_scale for s in raw_scales]
+			# If blending has removed all variation, set to None
+			if all(abs(v - 1.0) < 1e-9 for v in groove_velocities):
+				groove_velocities = None
+
+		return Groove(offsets=slot_offsets, grid=grid, velocities=groove_velocities)
+
+
+def apply_groove (
+	steps: typing.Dict[int, "subsequence.pattern.Step"],
+	groove: Groove,
+	pulses_per_quarter: int = subsequence.constants.MIDI_QUARTER_NOTE,
+	strength: float = 1.0,
+) -> typing.Dict[int, "subsequence.pattern.Step"]:
+
+	"""
+	Apply a groove template to a step dictionary keyed by pulse positions.
+
+	Notes close to a grid position are shifted by the groove's offset for
+	that slot. Notes between grid positions are left untouched.
+
+	Parameters:
+		steps: Step dictionary (pulse → Step).
+		groove: The groove template to apply.
+		pulses_per_quarter: Internal MIDI clock resolution (default 24).
+		strength: How much of the groove to apply (0.0–1.0).
+			0.0 leaves all timing and velocity unchanged; 1.0 applies
+			the full groove. Intermediate values blend between the two,
+			equivalent to Ableton’s TimingAmount / VelocityAmount dials.
+	"""
+
+	if not 0.0 <= strength <= 1.0:
+		raise ValueError("strength must be between 0.0 and 1.0")
+
+	grid_pulses = groove.grid * pulses_per_quarter
+	if grid_pulses <= 0:
+		return dict(steps)
+
+	half_grid = grid_pulses / 2.0
+	num_offsets = len(groove.offsets)
+	num_velocities = len(groove.velocities) if groove.velocities else 0
+
+	new_steps: typing.Dict[int, subsequence.pattern.Step] = {}
+
+	for old_pulse, step in steps.items():
+
+		# Find nearest grid position
+		grid_index = round(old_pulse / grid_pulses)
+		ideal_pulse = grid_index * grid_pulses
+
+		# Only groove notes that sit close to a grid position; notes deliberately
+		# placed between grid lines (flams, pushes) keep both their timing AND
+		# velocity.  The window is ±25% of a cell (half_grid * 0.5) — narrow on
+		# purpose, so off-grid expression survives a quantised groove.
+		if abs(old_pulse - ideal_pulse) > half_grid * 0.5:
+			new_pulse = old_pulse
+		else:
+			slot = grid_index % num_offsets
+
+			# Blend from the note's OWN pulse toward the groove target so
+			# strength=0.0 truly leaves timing untouched.  (Blending from
+			# ideal_pulse quantised away in-window micro-timing — e.g. from
+			# randomize() — at every strength, including 0.)
+			groove_target = ideal_pulse + groove.offsets[slot] * pulses_per_quarter
+			new_pulse = int(round(old_pulse + (groove_target - old_pulse) * strength))
+			new_pulse = max(0, new_pulse)
+
+			# Velocity scaling applies only to grooved (on-grid) notes, for the
+			# same reason — an off-grid note shouldn't pick up a slot's accent.
+			if groove.velocities and num_velocities > 0:
+				vel_slot = grid_index % num_velocities
+				# Blend between 1.0 (no effect) and the groove's scale (full effect)
+				vel_scale = 1.0 + (groove.velocities[vel_slot] - 1.0) * strength
+				step = _scale_step_velocity(step, vel_scale)
+
+		if new_pulse not in new_steps:
+			new_steps[new_pulse] = subsequence.pattern.Step()
+
+		new_steps[new_pulse].notes.extend(step.notes)
+
+	return new_steps
+
+
+def _scale_step_velocity (step: "subsequence.pattern.Step", scale: float) -> "subsequence.pattern.Step":
+
+	"""
+	Return a copy of the step with scaled velocities.
+	"""
+
+	import subsequence.pattern
+
+	new_notes = []
+	for note in step.notes:
+		new_notes.append(dataclasses.replace(
+			note,
+			velocity=max(1, min(127, int(round(note.velocity * scale))))
+		))
+	return subsequence.pattern.Step(notes=new_notes)

subsequence/harmonic_rhythm.py

@@ -0,0 +1,83 @@
+import dataclasses
+import math
+import random
+import typing
+
+
+@dataclasses.dataclass(frozen=True)
+class HarmonicRhythm:
+
+	"""A bounded, optionally-quantised *harmonic rhythm* — how long each chord lasts.
+
+	Harmonic rhythm is the rate at which the chords change.  It can be regular,
+	irregular, or static; this spec describes the **irregular** case — each chord
+	lasts a fresh random length somewhere between ``low`` and ``high`` beats.  When
+	``step`` is given, those lengths snap to whole multiples of it, so the result
+	is irregular but still lands on a musical grid (e.g. always a whole-note
+	boundary).
+
+	Build one with :func:`between` rather than constructing it directly::
+
+		harmonic_rhythm = between(WHOLE, 3 * WHOLE, step=WHOLE)   # 1, 2, or 3 whole notes
+
+	The other two harmonic-rhythm shapes are expressed without this class:
+	a single ``float`` (static — every chord the same length) and a ``list`` of
+	floats (a *shaped* rhythm such as ``[WHOLE, HALF, HALF]``, cycled per chord).
+	``p.progression()`` / ``comp.chords()`` accept all three.
+	"""
+
+	low: float
+	high: float
+	step: typing.Optional[float] = None
+
+	def __post_init__ (self) -> None:
+
+		"""Validate the bounds at construction so a typo surfaces at the call site."""
+
+		if self.low <= 0:
+			raise ValueError(f"harmonic rhythm low ({self.low:g}) must be positive — lengths are in beats")
+		if self.high < self.low:
+			raise ValueError(f"harmonic rhythm high ({self.high:g}) must be at least low ({self.low:g})")
+		if self.step is not None and self.step <= 0:
+			raise ValueError(f"harmonic rhythm step ({self.step:g}) must be positive")
+
+	def resolve (self, rng: random.Random) -> float:
+
+		"""Draw one chord length in beats from this spec.
+
+		With a ``step``, the length is a whole multiple of it snapped *inside*
+		``[low, high]`` (so a quantised rhythm never strays past its bounds).  If
+		no whole multiple fits within the bounds, the nearest in-range length is
+		used.  Without a ``step``, the draw is continuous and uniform.
+		"""
+
+		if self.step:
+			# Smallest/largest step-multiples that still sit within the bounds.
+			# The epsilon absorbs float dust so e.g. 12 / 4 floors to 3, not 2.
+			lo = max(1, math.ceil(self.low / self.step - 1e-9))
+			hi = math.floor(self.high / self.step + 1e-9)
+			if hi < lo:
+				hi = lo
+			length = rng.randint(lo, hi) * self.step
+
+			# Honour the bounds over the grid: when no whole multiple fits inside
+			# [low, high] (e.g. between(2, 3, step=4)), clamp to the nearest edge so
+			# the result never strays past the bounds the musician asked for.
+			return float(min(self.high, max(self.low, length)))
+
+		return float(rng.uniform(self.low, self.high))
+
+
+def between (low: float, high: float, step: typing.Optional[float] = None) -> HarmonicRhythm:
+
+	"""A harmonic rhythm that varies *between* two lengths (in beats).
+
+	Each chord lasts a random length in ``[low, high]``.  Pass ``step`` to snap
+	those lengths to a grid — e.g. ``between(WHOLE, 3 * WHOLE, step=WHOLE)`` gives
+	one, two, or three whole notes, never anything in between.
+
+	Reads aloud the way you'd describe it: "between one and three whole notes,
+	in whole-note steps."
+	"""
+
+	return HarmonicRhythm(low=low, high=high, step=step)