subsequence.harmonic_rhythm

 1import dataclasses
 2import math
 3import random
 4import typing
 5
 6
 7@dataclasses.dataclass(frozen=True)
 8class HarmonicRhythm:
 9
10	"""A bounded, optionally-quantised *harmonic rhythm* — how long each chord lasts.
11
12	Harmonic rhythm is the rate at which the chords change.  It can be regular,
13	irregular, or static; this spec describes the **irregular** case — each chord
14	lasts a fresh random length somewhere between ``low`` and ``high`` beats.  When
15	``step`` is given, those lengths snap to whole multiples of it, so the result
16	is irregular but still lands on a musical grid (e.g. always a whole-note
17	boundary).
18
19	Build one with :func:`between` rather than constructing it directly::
20
21		harmonic_rhythm = between(WHOLE, 3 * WHOLE, step=WHOLE)   # 1, 2, or 3 whole notes
22
23	The other two harmonic-rhythm shapes are expressed without this class:
24	a single ``float`` (static — every chord the same length) and a ``list`` of
25	floats (a *shaped* rhythm such as ``[WHOLE, HALF, HALF]``, cycled per chord).
26	``p.progression()`` / ``comp.chords()`` accept all three.
27	"""
28
29	low: float
30	high: float
31	step: typing.Optional[float] = None
32
33	def __post_init__ (self) -> None:
34
35		"""Validate the bounds at construction so a typo surfaces at the call site."""
36
37		if self.low <= 0:
38			raise ValueError(f"harmonic rhythm low ({self.low:g}) must be positive — lengths are in beats")
39		if self.high < self.low:
40			raise ValueError(f"harmonic rhythm high ({self.high:g}) must be at least low ({self.low:g})")
41		if self.step is not None and self.step <= 0:
42			raise ValueError(f"harmonic rhythm step ({self.step:g}) must be positive")
43
44	def resolve (self, rng: random.Random) -> float:
45
46		"""Draw one chord length in beats from this spec.
47
48		With a ``step``, the length is a whole multiple of it snapped *inside*
49		``[low, high]`` (so a quantised rhythm never strays past its bounds).  If
50		no whole multiple fits within the bounds, the nearest in-range length is
51		used.  Without a ``step``, the draw is continuous and uniform.
52		"""
53
54		if self.step:
55			# Smallest/largest step-multiples that still sit within the bounds.
56			# The epsilon absorbs float dust so e.g. 12 / 4 floors to 3, not 2.
57			lo = max(1, math.ceil(self.low / self.step - 1e-9))
58			hi = math.floor(self.high / self.step + 1e-9)
59			if hi < lo:
60				hi = lo
61			length = rng.randint(lo, hi) * self.step
62
63			# Honour the bounds over the grid: when no whole multiple fits inside
64			# [low, high] (e.g. between(2, 3, step=4)), clamp to the nearest edge so
65			# the result never strays past the bounds the musician asked for.
66			return float(min(self.high, max(self.low, length)))
67
68		return float(rng.uniform(self.low, self.high))
69
70
71def between (low: float, high: float, step: typing.Optional[float] = None) -> HarmonicRhythm:
72
73	"""A harmonic rhythm that varies *between* two lengths (in beats).
74
75	Each chord lasts a random length in ``[low, high]``.  Pass ``step`` to snap
76	those lengths to a grid — e.g. ``between(WHOLE, 3 * WHOLE, step=WHOLE)`` gives
77	one, two, or three whole notes, never anything in between.
78
79	Reads aloud the way you'd describe it: "between one and three whole notes,
80	in whole-note steps."
81	"""
82
83	return HarmonicRhythm(low=low, high=high, step=step)