subsequence

1264class Composition:
1265
1266	"""
1267	The top-level controller for a musical piece.
1268	
1269	The ``Composition`` object manages the global clock (Sequencer), the harmonic
1270	progression (HarmonicState), the song structure (subsequence.form_state.FormState), and all MIDI patterns.
1271	It serves as the main entry point for defining your music.
1272	
1273	Typical workflow:
1274
1275	1. Initialize ``Composition`` with BPM and Key.
1276	2. Define harmony and form (optional).
1277	3. Register patterns using the ``@composition.pattern`` decorator.
1278	4. Call ``composition.play()`` to start the music.
1279	"""
1280
1281	def __init__ (
1282		self,
1283		output_device: typing.Optional[str] = None,
1284		bpm: float = 120,
1285		time_signature: typing.Tuple[int, int] = (4, 4),
1286		key: typing.Optional[str] = None,
1287		scale: typing.Optional[str] = None,
1288		seed: typing.Optional[int] = None,
1289		record: bool = False,
1290		record_filename: typing.Optional[str] = None,
1291		zero_indexed_channels: bool = False,
1292		latency_ms: float = 0.0
1293	) -> None:
1294
1295		"""
1296		Initialize a new composition.
1297
1298		Parameters:
1299			output_device: Which MIDI output port to use, matched against
1300				``mido.get_output_names()``.  The name is treated as a
1301				pattern: ``*`` stands for any run of characters and ``?``
1302				for exactly one, matching is case-insensitive, and a name
1303				with no wildcards is simply a substring — so a plain
1304				``"Scarlett"`` finds the port without typing the rest.
1305				An exact name always wins outright.
1306
1307				Wildcards matter on Linux/ALSA, where names carry the
1308				client and port ids (e.g.
1309				``"Scarlett 2i4 USB:Scarlett 2i4 USB MIDI 1 16:0"``).  The
1310				client id — ``16`` here — is handed out in connection order
1311				and moves between reboots or when a virtual port is
1312				recreated, while the port index after it (``0``) stays put.
1313				Wildcard the one that moves and keep the one that does not::
1314
1315				    "*Scarlett 2i4 USB *:0"
1316
1317				Keep that trailing port index.  A multi-port interface
1318				reports one name per port, so ``"*U6MIDI Pro*"`` matches
1319				all three ports of a 3-port unit and asks which you meant
1320				at every launch, while ``"*U6MIDI Pro *:0"`` names one for
1321				good.  Prefer ``*`` to ``?`` — ``?`` matches a single
1322				character, so a pattern written for ``16:0`` quietly stops
1323				matching once ids reach three digits.  To look up the
1324				current names::
1325
1326				    import mido
1327				    for n in mido.get_output_names(): print(n)
1328
1329				If ``None``, Subsequence auto-discovers — uses the only
1330				available device, or prompts to choose if several exist.
1331			bpm: Initial tempo in beats per minute (default 120).
1332			time_signature: The metre as ``(beats, unit)``, default ``(4, 4)``.
1333				Sets the bar length everywhere bars matter: ``bars=`` pattern
1334				lengths, ``p.bar``/``p.signal()``, form advancement and
1335				transitions, and pinned-chord bar numbers.
1336			key: The root key of the piece (e.g., "C", "F#", "Bb").
1337				Required if you plan to use ``harmony()``.
1338			scale: The scale/mode of the piece (e.g. "minor", "dorian",
1339				or any registered scale name).  Used to resolve scale
1340				degrees in motifs; defaults to major (ionian) when unset.
1341			seed: An optional integer for deterministic randomness. When set,
1342				every random decision (chord choices, drum probability, etc.)
1343				will be identical on every run.
1344			record: When True, record all MIDI events to a file.
1345			record_filename: Optional filename for the recording (defaults to timestamp).
1346			zero_indexed_channels: When False (default), MIDI channels use
1347				1-based numbering (1-16) matching instrument labelling.
1348				Channel 10 is drums, the way musicians and hardware panels
1349				show it. When True, channels use 0-based numbering (0-15)
1350				matching the raw MIDI protocol.
1351			latency_ms: Physical output latency of the primary device in
1352				milliseconds, for delay compensation (default 0.0, must be
1353				non-negative). Set this when the primary output sounds late
1354				(e.g. a software sampler) so Subsequence delays faster
1355				devices to line everything up. See ``midi_output()`` for
1356				additional devices.
1357
1358		Example:
1359			```python
1360			comp = subsequence.Composition(bpm=128, key="Eb", seed=123)
1361			```
1362		"""
1363
1364		if latency_ms < 0:
1365			raise ValueError(f"latency_ms must be non-negative — got {latency_ms}")
1366
1367		self.output_device = output_device
1368		self.bpm = bpm
1369		self.time_signature = time_signature
1370		self.key = key
1371		self.scale = scale
1372		self._seed: typing.Optional[int] = seed
1373		self._zero_indexed_channels: bool = zero_indexed_channels
1374		self._output_latency_ms: float = latency_ms
1375
1376		# Determinism plumbing: named-stream derivation state.  Build-time
1377		# consumers draw per-call-salted streams (freeze:1, harmony:2, ...) so
1378		# adding one call never shifts another's stream; play-time pattern
1379		# streams are name-keyed in _build_pattern_from_pending.
1380		self._freeze_count: int = 0
1381		self._harmony_count: int = 0
1382		self._form_count: int = 0
1383		self._reroll_nonces: typing.Dict[str, int] = {}
1384		self._locked_names: typing.Set[str] = set()
1385
1386		self._sequencer = subsequence.sequencer.Sequencer(
1387			output_device_name = output_device,
1388			initial_bpm = bpm,
1389			time_signature = time_signature,
1390			record = record,
1391			record_filename = record_filename
1392		)
1393
1394		self._harmonic_state: typing.Optional[subsequence.harmonic_state.HarmonicState] = None
1395		self._harmony_cycle_beats: typing.Optional[int] = None
1396		self._harmony_style: typing.Optional[str] = None
1397		# The style (name or ChordGraph) from the most recent style-configuring
1398		# harmony() call — reused by parameter-only re-calls.
1399		self._last_harmony_style: typing.Optional[typing.Union[str, subsequence.chord_graphs.ChordGraph]] = None
1400		self._harmony_reschedule_lookahead: float = 1
1401		self._section_progressions: typing.Dict[str, Progression] = {}
1402		self._bound_progression: typing.Optional[Progression] = None
1403		self._pinned_chords: typing.Dict[int, typing.Any] = {}
1404		self._cadence_requests: typing.Dict[int, str] = {}
1405		self._section_cadences: typing.Dict[str, str] = {}
1406		self._harmony_horizon = _HarmonyHorizon()
1407		# True once the span-walking clock is registered for this playback —
1408		# lets a first mid-playback harmony() call start it exactly once.
1409		self._harmonic_clock_started: bool = False
1410		self._section_motifs: typing.Dict[typing.Tuple[str, typing.Optional[str]], typing.Any] = {}
1411		self._energy_map: typing.Dict[str, typing.Union[float, typing.Tuple[float, float]]] = {}
1412		self._form_has_payload: bool = False
1413		self._form_key: typing.Optional[str] = None
1414		self._form_scale: typing.Optional[str] = None
1415		# Cache of section progressions resolved against an effective key/scale
1416		# (key-relative section harmony re-keys per occurrence; resolution is a
1417		# pure function of (content, key, scale), so this is just memoisation).
1418		self._resolved_section_cache: typing.Dict[typing.Tuple[str, typing.Optional[str], typing.Optional[str]], Progression] = {}
1419		self._transitions: typing.List[_Transition] = []
1420		self._transition_muted: typing.Set[str] = set()
1421		self._pending_patterns: typing.List[_PendingPattern] = []
1422		# Names of patterns declared by the most recent live-reload exec (added by
1423		# pattern()/layer() as they run); the deletion diff in _apply_source_async
1424		# compares this against the same source's PREVIOUS exec.
1425		self._declared_names: typing.Set[str] = set()
1426		# Per-source declaration history: source label/path → the names it
1427		# declared last time it was exec'd.  The deletion diff unregisters only
1428		# names a source used to declare and no longer does — never patterns
1429		# registered by the wrapper script or by another watched source.
1430		self._source_declared: typing.Dict[str, typing.Set[str]] = {}
1431		self._pending_scheduled: typing.List[_PendingScheduled] = []
1432		self._form_state: typing.Optional[subsequence.form_state.FormState] = None
1433		self._builder_bar: int = 0
1434		self._display: typing.Optional[subsequence.display.Display] = None
1435		self._live_server: typing.Optional[subsequence.live_server.LiveServer] = None
1436		self._live_reloader: typing.Optional[subsequence.live_reloader.LiveReloader] = None
1437		self._is_live: bool = False
1438		self._running_patterns: typing.Dict[str, typing.Any] = {}
1439		self._input_device: typing.Optional[str] = None
1440		self._input_device_alias: typing.Optional[str] = None
1441		self._clock_follow: bool = False
1442		self._clock_output: bool = False
1443		self._cc_mappings: typing.List[typing.Dict[str, typing.Any]] = []
1444		self._cc_forwards: typing.List[typing.Dict[str, typing.Any]] = []
1445		# Held-note input config from note_input() (None = not declared).
1446		self._note_input: typing.Optional[typing.Dict[str, typing.Any]] = None
1447		# Additional output devices registered with midi_output() after construction.
1448		self._additional_outputs: typing.List[_AdditionalOutput] = []
1449		# Additional input devices: (device_name: str, alias: Optional[str], clock_follow: bool)
1450		self._additional_inputs: typing.List[typing.Tuple[str, typing.Optional[str], bool]] = []
1451		# Maps alias/name → output device index (populated in _run after all devices are opened).
1452		self._output_device_names: typing.Dict[str, int] = {}
1453		# Maps alias/name → input device index (populated in _run after all input devices are opened).
1454		self._input_device_names: typing.Dict[str, int] = {}
1455		self.data: typing.Dict[str, typing.Any] = {}
1456		self._osc_server: typing.Optional[subsequence.osc.OscServer] = None
1457		self.conductor = subsequence.conductor.Conductor()
1458		self._web_ui_enabled: bool = False
1459		self._web_ui_http_host: str = "127.0.0.1"
1460		self._web_ui_ws_host: str = "127.0.0.1"
1461		self._web_ui_server: typing.Optional[subsequence.web_ui.WebUI] = None
1462		self._link_quantum: typing.Optional[float] = None
1463
1464		# Hotkey state — populated by hotkeys() and hotkey().
1465		self._hotkeys_enabled: bool = False
1466		self._hotkey_bindings: typing.Dict[str, HotkeyBinding] = {}
1467		self._pending_hotkey_actions: typing.List[_PendingHotkeyAction] = []
1468		self._keystroke_listener: typing.Optional[subsequence.keystroke.KeystrokeListener] = None
1469
1470		# Tuning state — populated by tuning().
1471		self._tuning: typing.Optional[typing.Any] = None       # subsequence.tuning.Tuning
1472		self._tuning_bend_range: float = 2.0
1473		self._tuning_channels: typing.Optional[typing.List[int]] = None
1474		self._tuning_reference_note: int = 60
1475		self._tuning_exclude_drums: bool = True
1476
1477	def _resolve_device_id (self, device: subsequence.midi_utils.DeviceId) -> int:
1478		"""Resolve an output device id (None/int/str) to an integer index.
1479
1480		``None`` → 0 (primary device).  ``int`` → returned as-is.
1481		``str`` → looked up in ``_output_device_names``; logs a warning and
1482		returns 0 if the name is unknown (called after all devices are opened
1483		in ``_run()``).
1484		"""
1485		if device is None:
1486			return 0
1487		if isinstance(device, int):
1488			return device
1489		idx = self._output_device_names.get(device)
1490		if idx is None:
1491			logger.warning(
1492				f"Unknown output device name '{device}' — routing to device 0. "
1493				f"Available names: {list(self._output_device_names.keys())}"
1494			)
1495			return 0
1496		return idx
1497
1498	def _resolve_input_device_id (self, device: subsequence.midi_utils.DeviceId) -> typing.Optional[int]:
1499		"""Resolve an input device id (None/int/str) to an integer index.
1500
1501		``None`` → ``None`` (matches any input device — existing behaviour).
1502		``int`` → returned as-is.  ``str`` → looked up in ``_input_device_names``;
1503		logs a warning and returns ``-1`` if the name is unknown — an index no
1504		real device carries, so the mapping matches NOTHING (returning None
1505		here would silently fail OPEN and listen to every device).
1506		Called after all input devices are opened in ``_run()``.
1507		"""
1508		if device is None:
1509			return None
1510		if isinstance(device, int):
1511			return device
1512		idx = self._input_device_names.get(device)
1513		if idx is None:
1514			logger.warning(
1515				f"Unknown input device name '{device}' — mapping will be ignored. "
1516				f"Available names: {list(self._input_device_names.keys())}"
1517			)
1518			return -1
1519		return idx
1520
1521	def _resolve_pending_devices (self) -> None:
1522		"""Resolve name-based device ids on pending patterns now that all output devices are open."""
1523		for pending in self._pending_patterns:
1524			if isinstance(pending.raw_device, str):
1525				pending.device = self._resolve_device_id(pending.raw_device)
1526
1527	async def _activate_new_pending_patterns (self) -> None:
1528
1529		"""Build and schedule any pending patterns whose names are not yet running.
1530
1531		Used by ``LiveReloader._reload_async`` to bring NEW patterns added
1532		in a live reload into rotation mid-flight.  Existing patterns
1533		hot-swap via the decorator (their ``_builder_fn`` is replaced in
1534		place); only patterns whose names are not yet in ``_running_patterns``
1535		need this graduation step.
1536
1537		Newly-scheduled patterns start at the current sequencer pulse —
1538		they'll generate events from now onward, and the next reschedule
1539		will fire at the same offset as their primary cycle.
1540		"""
1541
1542		# Resolve any deferred string-device names against the now-open
1543		# device registry (no-op for int/None devices).
1544		self._resolve_pending_devices()
1545
1546		# Dedupe by name, last declaration wins — re-declaring a pattern in a
1547		# reloaded source must not schedule two copies.
1548		new_by_name: typing.Dict[str, _PendingPattern] = {}
1549
1550		for pending in self._pending_patterns:
1551			if pending.builder_fn.__name__ not in self._running_patterns:
1552				new_by_name[pending.builder_fn.__name__] = pending
1553
1554		new_pending = list(new_by_name.values())
1555
1556		if not new_pending:
1557			return
1558
1559		current_pulse = self._sequencer.pulse_count
1560
1561		for pending in new_pending:
1562
1563			pattern = self._build_pattern_from_pending(pending, start_pulse = current_pulse)
1564			await self._sequencer.schedule_pattern_repeating(pattern, start_pulse = current_pulse)
1565			self._running_patterns[pending.builder_fn.__name__] = pattern
1566
1567			logger.info(f"Live-reload: scheduled new pattern '{pending.builder_fn.__name__}'")
1568
1569		# Prune graduated (and stale duplicate) declarations: leaving them in
1570		# _pending_patterns resurrected deleted patterns on every later reload.
1571		self._pending_patterns = [
1572			pending for pending in self._pending_patterns
1573			if pending.builder_fn.__name__ not in self._running_patterns
1574		]
1575
1576	def _resolve_channel (self, channel: int) -> int:
1577
1578		"""
1579		Convert a user-supplied MIDI channel to the 0-indexed value used internally.
1580
1581		When ``zero_indexed_channels`` is False (default), the channel is
1582		validated as 1-16 and decremented by one. When True (0-indexed), the
1583		channel is validated as 0-15 and returned unchanged.
1584		"""
1585
1586		if self._zero_indexed_channels:
1587			if not 0 <= channel <= 15:
1588				raise ValueError(f"MIDI channel must be 0-15 (zero_indexed_channels=True), got {channel}")
1589			return channel
1590		else:
1591			if not 1 <= channel <= 16:
1592				raise ValueError(f"MIDI channel must be 1-16, got {channel}")
1593			return channel - 1
1594
1595	def _resolve_mirrors (
1596		self,
1597		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]],
1598		primary: typing.Optional[typing.Tuple[int, int]] = None,
1599	) -> typing.List[subsequence.pattern.MirrorSpec]:
1600
1601		"""
1602		Validate and normalise a list of mirror destinations.
1603
1604		Each entry is a 2- or 3-element sequence — ``(device_idx, channel)`` or
1605		``(device_idx, channel, drum_note_map)`` — as a tuple, list, or any such
1606		iterable.  ``channel`` is expressed in the user's channel-numbering
1607		convention (1-16 by default, 0-15 when ``zero_indexed_channels=True``);
1608		this method converts it to canonical 0-indexed form and rejects
1609		malformed entries.  The optional ``drum_note_map`` is preserved verbatim
1610		so the sequencer can re-resolve mirrored drum names per device.
1611
1612		String device names are NOT supported here; users wanting a named
1613		device should pass the integer index returned from ``midi_output()``.
1614
1615		If ``primary=(device, channel)`` is supplied (canonical 0-indexed
1616		form), a mirror entry whose ``(device, channel)`` matches it triggers a
1617		``logger.warning`` — this is almost always a user error (every event
1618		would double-fire on the same destination).  The optional map is ignored
1619		for this comparison.  Skipped when ``primary`` is ``None``, since the
1620		runtime API call site supplies its own check.
1621		"""
1622
1623		if mirrors is None:
1624			return []
1625
1626		resolved: typing.List[subsequence.pattern.MirrorSpec] = []
1627
1628		for entry in mirrors:
1629
1630			# Accept any 2- or 3-element iterable (tuple, list, etc.) — config
1631			# files and JSON sources naturally produce lists.  Validate shape at
1632			# decoration time so bad inputs surface here instead of producing
1633			# inscrutable failures inside the sequencer.
1634			try:
1635				items = list(entry)
1636			except TypeError:
1637				raise ValueError(f"Mirror entry must be a (device, channel[, drum_note_map]) tuple — got {entry!r}")
1638
1639			if len(items) not in (2, 3):
1640				raise ValueError(f"Mirror entry must have 2 or 3 elements (device, channel[, drum_note_map]) — got {entry!r}")
1641
1642			device = items[0]
1643			channel = items[1]
1644			drum_map = items[2] if len(items) == 3 else None
1645
1646			if not isinstance(device, int) or isinstance(device, bool):
1647				raise ValueError(f"Mirror device must be an integer index — got {type(device).__name__} ({device!r})")
1648
1649			if not isinstance(channel, int) or isinstance(channel, bool):
1650				raise ValueError(f"Mirror channel must be an integer — got {type(channel).__name__} ({channel!r})")
1651
1652			if drum_map is not None and not isinstance(drum_map, dict):
1653				raise ValueError(f"Mirror drum_note_map must be a dict or None — got {type(drum_map).__name__} ({drum_map!r})")
1654
1655			resolved_channel = self._resolve_channel(channel)
1656
1657			if primary is not None and (device, resolved_channel) == primary:
1658				logger.warning(
1659					f"Mirror destination {(device, resolved_channel)} matches the pattern's primary destination "
1660					f"— every event will double-fire on this (device, channel).  This is almost "
1661					f"certainly unintended."
1662				)
1663
1664			resolved_entry: subsequence.pattern.MirrorSpec = (
1665				(device, resolved_channel)
1666				if drum_map is None
1667				else (device, resolved_channel, drum_map)
1668			)
1669			resolved.append(resolved_entry)
1670
1671		return resolved
1672
1673	@property
1674	def harmonic_state (self) -> typing.Optional[subsequence.harmonic_state.HarmonicState]:
1675		"""The active ``HarmonicState``, or ``None`` if ``harmony()`` has not been called."""
1676		return self._harmonic_state
1677
1678	def current_chord (self) -> typing.Optional[typing.Any]:
1679
1680		"""The chord sounding at the playhead, or ``None`` without harmony.
1681
1682		Reads the harmony window at the current pulse, so it stays accurate
1683		under variable harmonic rhythm and clock lookahead (the engine's
1684		``current_chord`` flips *lookahead* beats early — this does not).
1685		Falls back to the engine's chord before playback starts.  The chord
1686		may be a decorated wrapper (``Am9``, ``C/G``) when the sounding span
1687		is spiced; it duck-types the ``Chord`` voicing protocol either way.
1688		"""
1689
1690		if not self._harmony_horizon.is_empty:
1691			beat = self._sequencer.pulse_count / self._sequencer.pulses_per_beat
1692			chord = self._harmony_horizon.chord_at(beat)
1693			if chord is not None:
1694				return chord
1695
1696		if self._harmonic_state is not None:
1697			return self._harmonic_state.get_current_chord()
1698
1699		return None
1700
1701	def _effective_key_scale (
1702		self,
1703		section_info: typing.Optional["subsequence.form_state.SectionInfo"],
1704	) -> typing.Tuple[typing.Optional[str], typing.Optional[str]]:
1705
1706		"""Resolve the key and scale in force, by the key-source precedence.
1707
1708		The layered chain, key and scale resolved **independently** so a
1709		section can move the tonic, the mode, or both:
1710		``Section.key`` > form key (``form(key=)`` / ``Form(key=)``) >
1711		``Composition.key``, and likewise for scale.  This is the one place
1712		the tier order lives; every placement site routes through it so the
1713		section key reaches every compositional element uniformly (the
1714		three-intent model: only *key-relative* content reads this — absolute
1715		content ignores it, chord-relative content tracks the chord).
1716		"""
1717
1718		key: typing.Optional[str] = None
1719		scale: typing.Optional[str] = None
1720
1721		if section_info is not None:
1722			key = section_info.key
1723			scale = section_info.scale
1724
1725		if key is None:
1726			key = self._form_key
1727		if key is None:
1728			key = self.key
1729
1730		if scale is None:
1731			scale = self._form_scale
1732		if scale is None:
1733			scale = self.scale
1734
1735		return key, scale
1736
1737	def _resolve_section_progression (
1738		self,
1739		info: "subsequence.form_state.SectionInfo",
1740	) -> typing.Optional[Progression]:
1741
1742		"""Resolve a section's bound progression against its effective key/scale.
1743
1744		Concrete progressions (names, ``PitchSet``, frozen captures) are
1745		returned unchanged.  Key-relative ones resolve against the section's
1746		effective key+scale — memoised per ``(name, key, scale)`` so a stable
1747		section reuses one realisation and span identity is stable across
1748		ticks.  If no key is resolvable at this moment the section is skipped
1749		(returns ``None`` → falls through to the bound/live source) with a
1750		warning; the authoritative check runs at :meth:`play`/:meth:`render`.
1751		"""
1752
1753		raw = self._section_progressions.get(info.name)
1754
1755		if raw is None or raw.is_concrete:
1756			return raw
1757
1758		key, scale = self._effective_key_scale(info)
1759
1760		if key is None:
1761			logger.warning(
1762				"section_chords(%r) is key-relative but no key resolves for this section — "
1763				"skipping (the chords fall through to the live/bound source)",
1764				info.name,
1765			)
1766			return None
1767
1768		cache_key = (info.name, key, scale)
1769		cached = self._resolved_section_cache.get(cache_key)
1770
1771		if cached is not None:
1772			return cached
1773
1774		try:
1775			resolved = raw.resolve(key, scale or "ionian")
1776		except ValueError as error:
1777			# A degree out of range for the effective scale, or an unknown
1778			# scale — never let it escape the clock callback (that would kill
1779			# harmony for the rest of playback).  Skip the section; the _run
1780			# pre-flight catches the common case far earlier.
1781			logger.warning(
1782				"section_chords(%r) cannot resolve against %s %s (%s) — skipping; "
1783				"the chords fall through to the live/bound source",
1784				info.name, key, scale or "ionian", error,
1785			)
1786			return None
1787
1788		self._resolved_section_cache[cache_key] = resolved
1789		return resolved
1790
1791	@property
1792	def form_state (self) -> typing.Optional["subsequence.form_state.FormState"]:
1793		"""The active ``subsequence.form_state.FormState``, or ``None`` if ``form()`` has not been called."""
1794		return self._form_state
1795
1796	@property
1797	def sequencer (self) -> subsequence.sequencer.Sequencer:
1798		"""The underlying ``Sequencer`` instance."""
1799		return self._sequencer
1800
1801	@property
1802	def running_patterns (self) -> typing.Dict[str, typing.Any]:
1803		"""The currently active patterns, keyed by name."""
1804		return self._running_patterns
1805
1806	@property
1807	def builder_bar (self) -> int:
1808		"""Current bar index used by pattern builders."""
1809		return self._builder_bar
1810
1811	def _require_harmonic_state (self) -> subsequence.harmonic_state.HarmonicState:
1812		"""Return the active HarmonicState, raising ValueError if none is configured."""
1813		if self._harmonic_state is None:
1814			raise ValueError(
1815				"harmony() must be called before this action — "
1816				"no harmonic state has been configured."
1817			)
1818		return self._harmonic_state
1819
1820	def _coerce_progression (self, source: typing.Any, what: str) -> Progression:
1821
1822		"""Coerce a Progression / element list / preset name and resolve it against the key.
1823
1824		Binding freezes one realisation (the value type's identity), so
1825		key-relative content resolves here, at bind time, against the
1826		composition's key and scale.  Used by the *global* bound progression
1827		(``harmony(progression=)``) — which is not section-scoped, so it has
1828		nothing to re-key against.
1829		"""
1830
1831		value = source if isinstance(source, Progression) else subsequence.progressions.progression(source)
1832
1833		if not value.is_concrete:
1834			if self.key is None:
1835				raise ValueError(
1836					f"{what} contains key-relative chords (degrees/romans) — "
1837					"set key= on the Composition so they can resolve"
1838				)
1839			value = value.resolve(self.key, self.scale or "ionian")
1840
1841		return value
1842
1843	def _coerce_section_progression (self, source: typing.Any) -> Progression:
1844
1845		"""Coerce a section progression, keeping key-relative content UNRESOLVED.
1846
1847		Section harmony re-keys per occurrence (the section/form/composition
1848		key in force when the section plays), so a key-relative progression is
1849		stored relative and resolved late, in the clock, against the section's
1850		effective key+scale — unlike the global bound progression, which
1851		freezes at bind.  Concrete content (chord names, frozen captures,
1852		``PitchSet``) is already absolute and never moves.
1853		"""
1854
1855		return source if isinstance(source, Progression) else subsequence.progressions.progression(source)
1856
1857	def harmony (
1858		self,
1859		style: typing.Optional[typing.Union[str, subsequence.chord_graphs.ChordGraph]] = None,
1860		cycle_beats: int = 4,
1861		dominant_7th: bool = True,
1862		gravity: float = 1.0,
1863		nir_strength: float = 0.5,
1864		minor_turnaround_weight: float = 0.0,
1865		root_diversity: float = subsequence.harmonic_state.DEFAULT_ROOT_DIVERSITY,
1866		reschedule_lookahead: float = 1,
1867		progression: typing.Optional[typing.Any] = None,
1868	) -> None:
1869
1870		"""
1871		Configure the harmonic logic and chord change intervals.
1872
1873		Two sources, combinable: a **bound progression** (``progression=`` — a
1874		:class:`Progression` value, an element list like ``[1, 6, 3, "bVII7"]``,
1875		or chord names) walked span by span on the global clock; and/or a
1876		**graph style** stepping live chords.  With only a progression bound,
1877		it loops on exhaustion; with a style configured too, exhaustion falls
1878		through to live stepping (the frozen-replay bridge).  Calling with
1879		neither argument keeps today's default live engine
1880		(``style="functional_major"``).
1881
1882		Parameters:
1883			style: The harmonic style to use. Built-in: "functional_major"
1884				(alias "diatonic_major"), "hooktheory_major" (alias
1885				"pop_major"), "turnaround", "aeolian_minor",
1886				"phrygian_minor", "lydian_major", "dorian_minor",
1887				"chromatic_mediant", "suspended", "mixolydian", "whole_tone",
1888				"diminished". See README for full descriptions.
1889			cycle_beats: How many beats each live chord lasts (default 4).
1890				Bound progressions carry their own harmonic rhythm in their
1891				spans, so this applies to live stepping only.  A re-call
1892				during playback takes effect from the next chord boundary;
1893				a FIRST harmony() call mid-playback starts the clock itself.
1894			dominant_7th: Whether to include V7 chords (default True).
1895			gravity: Key gravity (0.0 to 1.0). High values stay closer to the root chord.
1896			nir_strength: Melodic inertia (0.0 to 1.0). Influences chord movement
1897				expectations.
1898			minor_turnaround_weight: For "turnaround" style, influences major vs minor feel.
1899			root_diversity: Root-repetition damping (0.0 to 1.0). Each recent
1900				chord sharing a candidate's root reduces the weight to 40% at
1901				the default (0.4). Set to 1.0 to disable.
1902			reschedule_lookahead: How many beats in advance to calculate the
1903				next chord.
1904			progression: A progression to bind to the global clock.  Key-
1905				relative content resolves now, against the composition key
1906				and scale (binding freezes one realisation).
1907
1908		Example:
1909			```python
1910			# A moody minor progression that changes every 8 beats
1911			comp.harmony(style="aeolian_minor", cycle_beats=8, gravity=0.4)
1912
1913			# Manual harmony driving everything — loops forever
1914			comp.harmony(progression=subsequence.progression([1, 6, 3, 7]))
1915			```
1916		"""
1917
1918		if style is None and progression is None:
1919			# A parameter-only re-call (gravity=, cycle_beats=, ...) keeps the
1920			# configured style — defaulting unconditionally here would silently
1921			# replace e.g. aeolian_minor with functional_major.
1922			style = self._last_harmony_style if self._last_harmony_style is not None else "functional_major"
1923
1924		if style is not None:
1925
1926			if self.key is None:
1927				raise ValueError("Cannot configure harmony without a key - set key in the Composition constructor")
1928
1929			preserved_history: typing.List[subsequence.chords.Chord] = []
1930			preserved_current: typing.Optional[subsequence.chords.Chord] = None
1931
1932			if self._harmonic_state is not None:
1933				preserved_history = self._harmonic_state.history.copy()
1934				preserved_current = self._harmonic_state.current_chord
1935
1936			# Per-call salted build stream (harmony:1, harmony:2, ...): a re-call
1937			# gets its own deterministic stream while history and current chord
1938			# are preserved above, and adding a re-call never shifts any other
1939			# consumer's stream.
1940			self._harmony_count += 1
1941
1942			self._harmonic_state = subsequence.harmonic_state.HarmonicState(
1943				key_name = self.key,
1944				graph_style = style,
1945				include_dominant_7th = dominant_7th,
1946				key_gravity_blend = gravity,
1947				nir_strength = nir_strength,
1948				minor_turnaround_weight = minor_turnaround_weight,
1949				root_diversity = root_diversity,
1950				rng = self._stream(f"harmony:{self._harmony_count}")
1951			)
1952
1953			if preserved_history:
1954				self._harmonic_state.history = preserved_history
1955			if preserved_current is not None and self._harmonic_state.graph.get_transitions(preserved_current):
1956				self._harmonic_state.current_chord = preserved_current
1957
1958			self._harmony_style = style if isinstance(style, str) else None
1959			self._last_harmony_style = style
1960
1961		if progression is not None:
1962			self._bound_progression = self._coerce_progression(progression, "harmony(progression=)")
1963
1964		self._harmony_cycle_beats = cycle_beats
1965		self._harmony_reschedule_lookahead = reschedule_lookahead
1966
1967		# A re-call invalidates whatever the horizon had planned.
1968		self._harmony_horizon.invalidate_future()
1969
1970		# A FIRST harmony() call mid-playback must start the clock itself —
1971		# _run() only schedules clocks for sources it can see at play() time.
1972		# (Re-calls need nothing here: the clock reads its sources through
1973		# getters on every tick.)
1974		loop = self._sequencer._event_loop
1975
1976		if loop is not None and loop.is_running() and not self._harmonic_clock_started:
1977			try:
1978				on_loop = asyncio.get_running_loop() is loop
1979			except RuntimeError:
1980				on_loop = False
1981
1982			if on_loop:
1983				loop.create_task(self._start_harmonic_clock())
1984			else:
1985				asyncio.run_coroutine_threadsafe(self._start_harmonic_clock(), loop)
1986
1987	async def _start_harmonic_clock (self, bar_beats: typing.Optional[float] = None, clock_lookahead: typing.Optional[float] = None) -> None:
1988
1989		"""Register the span-walking harmonic clock (idempotent per playback).
1990
1991		Called from ``_run()`` when a harmony source exists at play time, and
1992		from ``harmony()`` when the FIRST source arrives mid-playback.
1993		``bar_beats``/``clock_lookahead`` default to a fresh computation for
1994		the mid-playback path; ``_run()`` passes the values it validated.
1995		"""
1996
1997		if self._harmonic_clock_started:
1998			return
1999
2000		self._harmonic_clock_started = True
2001
2002		if bar_beats is None:
2003			bar_beats = float(self.time_signature[0])
2004
2005		if clock_lookahead is None:
2006			lookaheads = [pattern.reschedule_lookahead for pattern in self._running_patterns.values()]
2007			clock_lookahead = min(bar_beats, max(1.0, float(self._harmony_reschedule_lookahead), float(max(lookaheads, default = 1))))
2008
2009		def _get_section_progression () -> typing.Optional[typing.Tuple[str, int, int, typing.Optional[Progression]]]:
2010			"""Return (section_name, section_index, bars, Progression|None) for the current section, or None.
2011
2012			The progression is resolved against the section's effective
2013			key/scale here (key-relative section harmony re-keys per
2014			occurrence); concrete content passes through unchanged.
2015			"""
2016			if self._form_state is None:
2017				return None
2018			info = self._form_state.get_section_info()
2019			if info is None:
2020				return None
2021			prog = self._resolve_section_progression(info)
2022			return (info.name, info.index, info.bars, prog)
2023
2024		def _resolve_cadence_formula (name: str) -> typing.List[subsequence.chords.Chord]:
2025			"""Resolve a cadence formula against the composition key and scale, at plan time."""
2026			hs = self._harmonic_state
2027			key_pc = subsequence.chords.key_name_to_pc(self.key) if self.key is not None else (hs.key_root_pc if hs is not None else 0)
2028			spec = subsequence.cadences.cadence_formula(name)
2029			return [
2030				subsequence.progressions.resolve_constraint(element, key_pc, self._constraint_scale(), f"cadence {name!r}")
2031				for element in spec.formula
2032			]
2033
2034		await schedule_harmonic_clock(
2035			sequencer = self._sequencer,
2036			get_harmonic_state = lambda: self._harmonic_state,
2037			horizon = self._harmony_horizon,
2038			bar_beats = bar_beats,
2039			cycle_beats = self._harmony_cycle_beats or 4,
2040			get_cycle_beats = lambda: self._harmony_cycle_beats or 4,
2041			get_bound_progression = lambda: self._bound_progression,
2042			get_section_progression = _get_section_progression,
2043			get_pinned = self._resolve_pin,
2044			cadence_requests = self._cadence_requests,
2045			resolve_cadence = _resolve_cadence_formula,
2046			get_section_cadence = self._section_cadences.get,
2047			reschedule_lookahead = clock_lookahead,
2048		)
2049
2050	def _constraint_scale (self) -> str:
2051
2052		"""The scale that hybrid-constraint ints resolve against.
2053
2054		The composition's own scale when set; otherwise inferred from the
2055		harmony style (``aeolian_minor`` → minor, matching
2056		:meth:`Progression.generate`'s documented inference), falling back
2057		to ionian.  Roman strings carry their quality and never need it.
2058		"""
2059
2060		if self.scale is not None:
2061			return self.scale
2062
2063		return subsequence.progressions._STYLE_SCALES.get(self._harmony_style or "", "ionian")
2064
2065	def freeze (
2066		self,
2067		bars: int,
2068		end: typing.Optional[typing.Any] = None,
2069		pins: typing.Optional[typing.Dict[int, typing.Any]] = None,
2070		avoid: typing.Optional[typing.Sequence[typing.Any]] = None,
2071		cadence: typing.Optional[str] = None,
2072	) -> "Progression":
2073
2074		"""Capture a chord progression from the live harmony engine.
2075
2076		Runs the harmony engine forward by *bars* chord changes, records each
2077		chord, and returns it as a :class:`Progression` that can be bound to a
2078		form section with :meth:`section_chords`.
2079
2080		The engine state **advances** — successive ``freeze()`` calls produce a
2081		continuing compositional journey so section progressions feel like parts
2082		of a whole rather than isolated islands.
2083
2084		The hybrid constraints compile into the walk: ``end=`` fixes the last
2085		bar ("end on V at bar 8"), ``pins=`` fix any 1-based bar, ``avoid=``
2086		excludes chords throughout.  Specs follow the progression-element
2087		grammar (ints where diatonic, roman/name strings where chromatic) and
2088		resolve against the composition key and scale.  A backward
2089		feasibility pass guarantees satisfiability before any chord is drawn;
2090		the forward walk keeps the engine's real history-dependent weighting.
2091		Bar 1 is always the engine's current chord — the journey continues —
2092		so ``pins={1: ...}`` may only name it redundantly.
2093
2094		Parameters:
2095			bars: Number of chords to capture (one per harmony cycle).
2096			end: The chord at the final bar — ``end="V"`` is the cadential
2097				major dominant in minor.
2098			pins: ``{bar: chord}`` — 1-based fiat positions.
2099			avoid: Chords excluded from the walk.
2100			cadence: A cadence name (``"strong"``/``"soft"``/``"open"``/
2101				``"fakeout"``, theory aliases accepted) — its formula pins
2102				the final bars, so the walk approaches the close.
2103				Conflicts with ``end=`` or pins on those bars.
2104
2105		Returns:
2106			A :class:`Progression` with the captured chords and trailing
2107			history for NIR continuity.
2108
2109		Raises:
2110			ValueError: If :meth:`harmony` has not been called first, or the
2111				constraints are contradictory or unsatisfiable.
2112
2113		Example::
2114
2115			composition.harmony(style="functional_major", cycle_beats=4)
2116			verse  = composition.freeze(8, end="V")   # the verse sets up the chorus
2117			chorus = composition.freeze(4)            # next 4 chords, continuing on
2118			composition.section_chords("verse",  verse)
2119			composition.section_chords("chorus", chorus)
2120		"""
2121
2122		hs = self._require_harmonic_state()
2123
2124		if bars < 1:
2125			raise ValueError("bars must be at least 1")
2126
2127		if cadence is not None:
2128			pins = subsequence.progressions.cadence_pins(cadence, bars, pins, end)
2129			end = None
2130
2131		scale = self._constraint_scale()
2132		key_pc = subsequence.chords.key_name_to_pc(self.key) if self.key is not None else hs.key_root_pc
2133
2134		resolved_pins = {
2135			position: subsequence.progressions.resolve_constraint(spec, key_pc, scale, f"pins[{position}]")
2136			for position, spec in (pins or {}).items()
2137		}
2138		resolved_end = subsequence.progressions.resolve_constraint(end, key_pc, scale, "end") if end is not None else None
2139		resolved_avoid = [subsequence.progressions.resolve_constraint(spec, key_pc, scale, "avoid") for spec in (avoid or [])]
2140
2141		if 1 in resolved_pins and resolved_pins[1] != hs.current_chord:
2142			raise ValueError(
2143				f"pins[1]={resolved_pins[1].name()} conflicts with the engine's current chord "
2144				f"({hs.current_chord.name()}) — bar 1 of a freeze continues the journey; "
2145				"pin a later bar, or use pin_chord() for playback fiat"
2146			)
2147
2148		# Per-call salted stream (freeze:1, freeze:2, ...): each call's draws
2149		# are independent of every other consumer, so frozen progressions are
2150		# reproducible WITHOUT play() and adding a call cannot shift a
2151		# neighbour's output.  Engine state still advances normally — chord
2152		# continuity comes from current_chord/history, randomness from the
2153		# salted stream (swap-and-restore keeps hs.rng for play untouched).
2154		self._freeze_count += 1
2155		stream = self._stream(f"freeze:{self._freeze_count}")
2156		saved_rng = hs.rng
2157
2158		if stream is not None:
2159			hs.rng = stream
2160
2161		try:
2162			# The kernel with the engine's own hooks is draw-for-draw the old
2163			# step() loop when unconstrained — one walk path for both.
2164			def _commit (chosen: subsequence.chords.Chord) -> None:
2165				hs.current_chord = chosen
2166
2167			collected = subsequence.sequence_utils.constrained_walk(
2168				hs.graph,
2169				hs.current_chord,
2170				bars,
2171				rng = hs.rng,
2172				pins = resolved_pins,
2173				end = resolved_end,
2174				avoid = resolved_avoid,
2175				weight_modifier = hs._transition_weight,
2176				before_choice = hs._record_transition_source,
2177				after_choice = _commit,
2178			)
2179
2180			# Advance past the last captured chord so the next freeze() call or
2181			# live playback does not duplicate it.
2182			hs.step()
2183
2184		finally:
2185			hs.rng = saved_rng
2186
2187		span_beats = float(self._harmony_cycle_beats or 4)
2188
2189		return Progression(
2190			spans = tuple(
2191				subsequence.progressions.ChordSpan(chord = chord, beats = span_beats)
2192				for chord in collected
2193			),
2194			trailing_history = tuple(hs.history),
2195		)
2196
2197	def section_chords (self, section_name: str, progression: typing.Any) -> None:
2198
2199		"""Bind a :class:`Progression` to a named form section.
2200
2201		Every time *section_name* plays, the harmonic clock walks the
2202		progression's spans instead of calling the live engine.  Sections
2203		without a bound progression continue generating live chords.
2204
2205		Accepts a :class:`Progression` value (from :meth:`freeze`, the
2206		``progression()`` factory, or hand-built) or anything the factory
2207		accepts — an element list like ``[1, 6, 3, "bVII7"]`` or chord
2208		names.
2209
2210		**Key-relative content re-keys per occurrence.**  A progression
2211		written in degrees or romans is *key-relative* content: it resolves
2212		late, each time the section plays, against that section's effective
2213		key and scale (``Section.key`` > form key > composition key, with
2214		mode following the same chain).  So a ``Section(key="A")`` plays the
2215		same numbered progression a tone higher — its chords and its degrees
2216		share one tonic.  *Absolute* content — chord names (``"Am"``),
2217		:class:`~subsequence.progressions.PitchSet`, and frozen captures from
2218		:meth:`freeze` — names exact chords and is never transposed by a key.
2219
2220		On exhaustion mid-section the progression loops when no graph style
2221		is configured (and always when it contains a ``PitchSet``); with a
2222		live engine, exhaustion **falls through to live stepping in the
2223		COMPOSITION key** — the live graph engine does not transpose for a
2224		section (a stateful walk does not modulate mid-stream), so a
2225		re-keyed section that runs out of written chords hands off to
2226		composition-key harmony.  Bind a full-length progression (or set
2227		``at_end``/loop intent) if you need the whole section in its key.
2228
2229		Parameters:
2230			section_name: Name of the section as defined in :meth:`form`.
2231			progression: The progression to bind.
2232
2233		Raises:
2234			ValueError: If a graph-based form has been configured and
2235				*section_name* is not one of its sections.  List and generator
2236				forms yield names lazily, so they cannot be validated here.
2237				(A key-relative progression with no resolvable key for the
2238				section is caught at :meth:`play`/:meth:`render`, once the
2239				form's keys are known.)
2240
2241		Example::
2242
2243			composition.section_chords("verse",  verse_progression)
2244			composition.section_chords("chorus", [1, 6, 3, 7])
2245			# "bridge" is not bound — it generates live chords
2246		"""
2247
2248		if (
2249			self._form_state is not None
2250			and self._form_state._section_bars is not None
2251			and section_name not in self._form_state._section_bars
2252		):
2253			known = ", ".join(sorted(self._form_state._section_bars))
2254			raise ValueError(
2255				f"Section '{section_name}' not found in form. "
2256				f"Known sections: {known}"
2257			)
2258
2259		self._section_progressions[section_name] = self._coerce_section_progression(progression)
2260		self._resolved_section_cache = {}
2261		self._harmony_horizon.invalidate_future()
2262
2263	def pin_chord (self, bar: int, chord: typing.Optional[typing.Any]) -> None:
2264
2265		"""Force the chord sounding at a bar — fiat over live generation.
2266
2267		Whatever the harmonic source (live walk, bound progression, section
2268		progression) produces for *bar*, the pinned chord overrides it.
2269		Pass ``None`` to remove a pin.
2270
2271		Parameters:
2272			bar: 1-based bar number (the musician count).
2273			chord: A chord name, int degree, roman string, ``Chord``,
2274				``PitchSet``, or ``None`` to unpin.  A **key-relative** spec
2275				(int degree, roman) re-keys like section harmony: it resolves
2276				late, against the effective key of the section sounding at
2277				that bar (so ``pin_chord(8, "V")`` is the dominant of
2278				wherever bar 8 lands).  A **concrete** spec (name, ``Chord``,
2279				``PitchSet``) is absolute and never moves.
2280
2281		Example::
2282
2283			composition.pin_chord(8, "E7")    # the turnaround lands on E7
2284			composition.pin_chord(8, "V")     # the dominant of bar 8's section
2285			composition.pin_chord(8, None)    # let it walk again
2286		"""
2287
2288		if not isinstance(bar, int) or isinstance(bar, bool) or bar < 1:
2289			raise ValueError(f"bars are 1-based ints, got {bar!r}")
2290
2291		if chord is None:
2292			self._pinned_chords.pop(bar, None)
2293		else:
2294			# Store the parsed span — relative pins resolve late (per section)
2295			# at the clock; concrete pins are absolute.
2296			span = subsequence.progressions.parse_element(chord, beats = float(self.time_signature[0]))
2297
2298			if not span.is_concrete:
2299				# Raise early only when no key is resolvable for this bar — the
2300				# bar's own section (sequence forms) may supply one even with no
2301				# composition/form key.
2302				probe_info = self._form_state.section_info_at_bar(bar) if self._form_state is not None else None
2303				probe_key, _ = self._effective_key_scale(probe_info)
2304				if probe_key is None:
2305					raise ValueError(
2306						"pin_chord with a key-relative spec (degree/roman) needs a key — set key= on "
2307						"the Composition, a form key, or a Section.key for that bar (the pin re-keys "
2308						"to the section's effective key)"
2309					)
2310
2311			self._pinned_chords[bar] = span
2312
2313		self._harmony_horizon.invalidate_future()
2314
2315	def _resolve_pin (self, bar: int) -> typing.Optional[typing.Any]:
2316
2317		"""Resolve a stored pin to a chord-like, re-keying relative pins per section.
2318
2319		Concrete pins return their chord directly; key-relative pins resolve
2320		against the effective key of the section sounding now (the clock
2321		reads this as it reaches each bar).  Returns ``None`` (no pin / a
2322		relative pin with no resolvable key, warned) so the clock falls
2323		through to its normal source.
2324		"""
2325
2326		span = self._pinned_chords.get(bar)
2327
2328		if span is None:
2329			return None
2330
2331		if span.is_concrete:
2332			return _span_chord(span)
2333
2334		# Key the pin to the section that OWNS this bar (the clock's lookahead
2335		# can project a pin into a later, differently-keyed section while the
2336		# playhead is still earlier) — fall back to the playhead section where
2337		# a per-bar section is not computable (graph/generator forms).
2338		info: typing.Optional["subsequence.form_state.SectionInfo"] = None
2339		if self._form_state is not None:
2340			info = self._form_state.section_info_at_bar(bar)
2341			if info is None:
2342				info = self._form_state.get_section_info()
2343
2344		key, scale = self._effective_key_scale(info)
2345
2346		if key is None:
2347			logger.warning(
2348				"pin_chord(%d, ...) is key-relative but no key resolves for that bar — ignoring the pin",
2349				bar,
2350			)
2351			return None
2352
2353		return _span_chord(span.resolve(subsequence.chords.key_name_to_pc(key), scale or "ionian"))
2354
2355	def request_cadence (self, cadence: str = "strong", bar: typing.Optional[int] = None) -> None:
2356
2357		"""Ask the live engine to approach a cadence arriving at a bar.
2358
2359		The request hook: where :meth:`pin_chord` is fiat, this is a
2360		*steered approach* — at the next chord boundary the clock plans the
2361		remaining changes up to *bar* as a constrained walk through the
2362		engine's real weights, pinned to the cadence formula at the tail
2363		(``"strong"`` arrives V→I, ``"soft"`` IV→I, ``"open"`` IV→V,
2364		``"fakeout"`` V→vi; theory aliases accepted).  The chords still
2365		commit one boundary at a time, so the journey continues through the
2366		close.
2367
2368		One-shot: the request is consumed when planned.  Live harmony only —
2369		bound/section progressions are data and cannot be steered; a request
2370		whose bar passes unserved expires with a warning.  If the formula is
2371		not walkable from where the harmony stands, the arrival lands by
2372		fiat (loudly).  Ask at least a pattern-lookahead ahead: patterns may
2373		already have rendered against the previously planned chord.
2374
2375		Parameters:
2376			cadence: The cadence name.
2377			bar: The 1-based bar the cadence's final chord arrives at
2378				(required; in practice ≥ 2 — bar 1 cannot be approached).
2379
2380		Example::
2381
2382			composition.request_cadence("open", bar=16)    # hang on V at bar 16
2383		"""
2384
2385		spec = subsequence.cadences.cadence_formula(cadence)
2386
2387		if bar is None or not isinstance(bar, int) or isinstance(bar, bool) or bar < 1:
2388			raise ValueError(f"request_cadence needs bar= — the 1-based bar the cadence arrives at (got {bar!r})")
2389
2390		self._cadence_requests[bar] = spec.name
2391		self._harmony_horizon.invalidate_future()
2392
2393	def section_cadence (self, section_name: str, cadence: typing.Optional[str] = "strong") -> None:
2394
2395		"""Close every pass of a section with a cadence — the standing request.
2396
2397		Each time *section_name* is entered, the clock registers a
2398		:meth:`request_cadence` arriving at the section's final bar, so the
2399		harmony approaches the close as the section ends.  Live harmony
2400		only: a section with bound chords (:meth:`section_chords`) is data
2401		and ignores the registration — its closes are written, not steered.
2402		Pass ``None`` to unregister.
2403
2404		Example::
2405
2406			composition.form([("verse", 8), ("chorus", 8)])
2407			composition.section_cadence("verse", "open")     # every verse hangs on V
2408			composition.section_cadence("chorus", "strong")  # every chorus lands home
2409		"""
2410
2411		if cadence is None:
2412			self._section_cadences.pop(section_name, None)
2413			return
2414
2415		spec = subsequence.cadences.cadence_formula(cadence)
2416		self._section_cadences[section_name] = spec.name
2417
2418	def section_motifs (self, section_name: str, value: typing.Any, part: typing.Optional[str] = None) -> None:
2419
2420		"""Bind a Motif or Phrase to a named form section (per optional part).
2421
2422		Patterns read the binding back with ``p.section_motif(part)`` (or use
2423		the one-call :meth:`phrase_part`); a section with no binding for the
2424		part is silent for that part — bind material or don't, no fallback
2425		guessing.  Re-binding is idempotent, so the call is safe in a live
2426		file: re-executing on save is the desired rebind.
2427
2428		Parameters:
2429			section_name: Name of the section as defined in :meth:`form`.
2430			value: A ``Motif`` or ``Phrase`` (anything exposing
2431				``.length``/``.slice`` places).
2432			part: Optional part label, so one section can carry several
2433				bindings (``"lead"``, ``"bass"``, ...).
2434
2435		Raises:
2436			ValueError: If a graph-based form has been configured and
2437				*section_name* is not one of its sections.
2438
2439		Example::
2440
2441			composition.section_motifs("verse",  verse_line,  part="lead")
2442			composition.section_motifs("chorus", chorus_line, part="lead")
2443		"""
2444
2445		if not hasattr(value, "length") or not hasattr(value, "slice"):
2446			raise TypeError(
2447				f"section_motifs() binds Motif/Phrase values (.length/.slice) — got {type(value).__name__}"
2448			)
2449
2450		if (
2451			self._form_state is not None
2452			and self._form_state._section_bars is not None
2453			and section_name not in self._form_state._section_bars
2454		):
2455			known = ", ".join(sorted(self._form_state._section_bars))
2456			raise ValueError(
2457				f"Section '{section_name}' not found in form. "
2458				f"Known sections: {known}"
2459			)
2460
2461		self._section_motifs[(section_name, part)] = value
2462
2463	def on_event (self, event_name: str, callback: typing.Callable[..., typing.Any]) -> None:
2464
2465		"""
2466		Register a callback for a sequencer event (e.g., "bar", "start", "stop").
2467		"""
2468
2469		self._sequencer.on_event(event_name, callback)
2470
2471
2472	# -----------------------------------------------------------------------
2473	# Hotkey API
2474	# -----------------------------------------------------------------------
2475
2476	def hotkeys (self, enabled: bool = True) -> None:
2477
2478		"""Enable or disable the global hotkey listener.
2479
2480		Must be called **before** :meth:`play` to take effect.  When enabled, a
2481		background thread reads single keystrokes from stdin without requiring
2482		Enter.  The ``?`` key is always reserved and lists all active bindings.
2483
2484		Hotkeys have zero impact on playback when disabled — the listener
2485		thread is never started.
2486
2487		Args:
2488		    enabled: ``True`` (default) to enable hotkeys; ``False`` to disable.
2489
2490		Example::
2491
2492		    composition.hotkeys()
2493		    composition.hotkey("a", lambda: composition.form_jump("chorus"))
2494		    composition.play()
2495		"""
2496
2497		self._hotkeys_enabled = enabled
2498
2499
2500	def hotkey (
2501		self,
2502		key:      str,
2503		action:   typing.Callable[[], None],
2504		quantize: int = 0,
2505		label:    typing.Optional[str] = None,
2506	) -> None:
2507
2508		"""Register a single-key shortcut that fires during playback.
2509
2510		The listener must be enabled first with :meth:`hotkeys`.
2511
2512		Most actions — form jumps, ``composition.data`` writes, and
2513		:meth:`tweak` calls — should use ``quantize=0`` (the default).  Their
2514		musical effect is naturally delayed to the next pattern rebuild cycle,
2515		which provides automatic musical quantization without extra configuration.
2516
2517		Use ``quantize=N`` for actions where you want an explicit bar-boundary
2518		guarantee, such as :meth:`mute` / :meth:`unmute`.
2519
2520		The ``?`` key is reserved and cannot be overridden.
2521
2522		Args:
2523		    key: A single character trigger (e.g. ``"a"``, ``"1"``, ``" "``).
2524		    action: Zero-argument callable to execute.
2525		    quantize: ``0`` = execute immediately (default).  ``N`` = execute
2526		        on the next global bar number divisible by *N*.
2527		    label: Display name for the ``?`` help listing.  Auto-derived from
2528		        the function name or lambda body if omitted.
2529
2530		Raises:
2531		    ValueError: If ``key`` is the reserved ``?`` character, or if
2532		        ``key`` is not exactly one character.
2533
2534		Example::
2535
2536		    composition.hotkeys()
2537
2538		    # Immediate — musical effect happens at next pattern rebuild
2539		    composition.hotkey("a", lambda: composition.form_jump("chorus"))
2540		    composition.hotkey("1", lambda: composition.data.update({"mode": "chill"}))
2541
2542		    # Explicit 4-bar phrase boundary
2543		    composition.hotkey("s", lambda: composition.mute("drums"), quantize=4)
2544
2545		    # Named function — label is derived automatically
2546		    def drop_to_breakdown ():
2547		        composition.form_jump("breakdown")
2548		        composition.mute("lead")
2549
2550		    composition.hotkey("d", drop_to_breakdown)
2551
2552		    composition.play()
2553		"""
2554
2555		if len(key) != 1:
2556			raise ValueError(f"hotkey key must be a single character, got {key!r}")
2557
2558		if key == _HOTKEY_RESERVED:
2559			raise ValueError(f"'{_HOTKEY_RESERVED}' is reserved for listing active hotkeys.")
2560
2561		derived = label if label is not None else _derive_label(action)
2562
2563		self._hotkey_bindings[key] = HotkeyBinding(
2564			key      = key,
2565			action   = action,
2566			quantize = quantize,
2567			label    = derived,
2568		)
2569
2570
2571	def form_jump (self, section_name: str) -> None:
2572
2573		"""Jump the form to a named section immediately.
2574
2575		Delegates to :meth:`subsequence.form_state.FormState.jump_to`.  Only works when the
2576		composition uses graph-mode form (a dict passed to :meth:`form`).
2577
2578		The musical effect is heard at the *next pattern rebuild cycle* — already-
2579		queued MIDI notes are unaffected.  This natural delay means ``form_jump``
2580		is effective without needing explicit quantization.
2581
2582		Args:
2583		    section_name: The section to jump to.
2584
2585		Raises:
2586		    ValueError: If no form is configured, or the form is not in graph
2587		        mode, or *section_name* is unknown.
2588
2589		Example::
2590
2591		    composition.hotkey("c", lambda: composition.form_jump("chorus"))
2592		"""
2593
2594		if self._form_state is None:
2595			raise ValueError("form_jump() requires a form to be configured via composition.form().")
2596
2597		self._form_state.jump_to(section_name)
2598
2599		# The harmony horizon planned against the old section — revoke it.
2600		self._harmony_horizon.invalidate_future()
2601
2602
2603	def form_next (self, section_name: str) -> None:
2604
2605		"""Queue the next section — takes effect when the current section ends.
2606
2607		Unlike :meth:`form_jump`, this does not interrupt the current section.
2608		The queued section replaces the automatically pre-decided next section
2609		and takes effect at the natural section boundary.  The performer can
2610		change their mind by calling ``form_next`` again before the boundary.
2611
2612		Delegates to :meth:`subsequence.form_state.FormState.queue_next`.  Only works when the
2613		composition uses graph-mode form (a dict passed to :meth:`form`).
2614
2615		Args:
2616		    section_name: The section to queue.
2617
2618		Raises:
2619		    ValueError: If no form is configured, or the form is not in graph
2620		        mode, or *section_name* is unknown.
2621
2622		Example::
2623
2624		    composition.hotkey("c", lambda: composition.form_next("chorus"))
2625		"""
2626
2627		if self._form_state is None:
2628			raise ValueError("form_next() requires a form to be configured via composition.form().")
2629
2630		self._form_state.queue_next(section_name)
2631
2632		# The harmony horizon planned against the old continuation — revoke it.
2633		self._harmony_horizon.invalidate_future()
2634
2635
2636	def _list_hotkeys (self) -> None:
2637
2638		"""Log all active hotkey bindings (triggered by the ``?`` key).
2639
2640		Output appears via the standard logger so it scrolls cleanly above
2641		the :class:`~subsequence.display.Display` status line.
2642		"""
2643
2644		lines = ["Active hotkeys:"]
2645		for key in sorted(self._hotkey_bindings):
2646			b = self._hotkey_bindings[key]
2647			quant_str = "immediate" if b.quantize == 0 else f"quantize={b.quantize}"
2648			lines.append(f"  {key}  \u2192  {b.label}  ({quant_str})")
2649		lines.append(f"  ?  \u2192  list hotkeys")
2650		logger.info("\n".join(lines))
2651
2652
2653	def _process_hotkeys (self, bar: int) -> None:
2654
2655		"""Drain pending keystrokes and execute due actions.
2656
2657		Called on every ``"bar"`` event by the sequencer when hotkeys are
2658		enabled.  Handles both immediate (``quantize=0``) and quantized actions.
2659
2660		Both kinds run here, on the bar-event callback (the event loop): the
2661		keystroke listener thread only enqueues keypresses (``drain()``), it
2662		never executes actions.  Immediate (``quantize=0``) bindings fire as soon
2663		as the key is drained; quantized ones wait for their next boundary.
2664
2665		Args:
2666		    bar: The current global bar number from the sequencer.
2667		"""
2668
2669		if self._keystroke_listener is None:
2670			return
2671
2672		# Process newly arrived keys.
2673		for key in self._keystroke_listener.drain():
2674
2675			if key == _HOTKEY_RESERVED:
2676				self._list_hotkeys()
2677				continue
2678
2679			binding = self._hotkey_bindings.get(key)
2680			if binding is None:
2681				continue
2682
2683			if binding.quantize == 0:
2684				# Immediate — execute now (we're on the bar-event callback,
2685				# which is safe for all mutation methods).
2686				try:
2687					binding.action()
2688					logger.info(f"Hotkey '{key}' \u2192 {binding.label}")
2689				except Exception as exc:
2690					logger.warning(f"Hotkey '{key}' action raised: {exc}")
2691			else:
2692				# Defer until the next quantize boundary.
2693				self._pending_hotkey_actions.append(
2694					_PendingHotkeyAction(binding=binding)
2695				)
2696
2697		# Fire any pending actions whose bar boundary has arrived.
2698		still_pending: typing.List[_PendingHotkeyAction] = []
2699
2700		for pending in self._pending_hotkey_actions:
2701			if bar % pending.binding.quantize == 0:
2702				try:
2703					pending.binding.action()
2704					logger.info(
2705						f"Hotkey '{pending.binding.key}' \u2192 {pending.binding.label} "
2706						f"(bar {bar})"
2707					)
2708				except Exception as exc:
2709					logger.warning(
2710						f"Hotkey '{pending.binding.key}' action raised: {exc}"
2711					)
2712			else:
2713				still_pending.append(pending)
2714
2715		self._pending_hotkey_actions = still_pending
2716
2717	@property
2718	def seed (self) -> typing.Optional[int]:
2719
2720		"""
2721		The composition's random seed, or None when unseeded.
2722
2723		When set, every random decision derives deterministically from this
2724		value through named streams (see ``seed_for()``), so the same script
2725		produces the same music on every run.  Assign to set it::
2726
2727			comp.seed = 42
2728
2729		(Formerly the method ``comp.seed(42)`` — the call form is a hard
2730		break per the pre-1.0 rename policy.)
2731		"""
2732
2733		return self._seed
2734
2735	@seed.setter
2736	def seed (self, value: typing.Optional[int]) -> None:
2737
2738		"""Set the composition seed (``comp.seed = 42``)."""
2739
2740		self._seed = value
2741
2742	def _stream_seed (self, name: str) -> typing.Optional[int]:
2743
2744		"""
2745		Derive the effective integer seed for a named random stream.
2746
2747		The derivation is ``zlib.crc32(f"{seed}:{name}")`` — crc32 rather
2748		than ``hash()`` because it is stable across processes — plus the
2749		per-name nonce when ``reroll()`` has been called.  Returns None when
2750		the composition is unseeded.
2751		"""
2752
2753		if self._seed is None:
2754			return None
2755
2756		nonce = self._reroll_nonces.get(name, 0)
2757		key = f"{self._seed}:{name}" if nonce == 0 else f"{self._seed}:{name}:{nonce}"
2758		return zlib.crc32(key.encode())
2759
2760	def _stream (self, name: str) -> typing.Optional[random.Random]:
2761
2762		"""A fresh ``random.Random`` for a named stream, or None when unseeded."""
2763
2764		stream_seed = self._stream_seed(name)
2765		return None if stream_seed is None else random.Random(stream_seed)
2766
2767	def seed_for (self, name: str) -> typing.Optional[int]:
2768
2769		"""
2770		Surface the effective derived seed for a named stream.
2771
2772		Works for pattern names and equally for any name you invent for a
2773		standalone value generator (``seed=composition.seed_for("hook")``),
2774		so its randomness keys off the composition seed without sharing any
2775		other consumer's stream.  Reflects ``reroll()`` nonces.  Returns None
2776		when the composition is unseeded.
2777
2778		Example:
2779			```python
2780			hook_seed = composition.seed_for("hook")
2781			```
2782		"""
2783
2784		return self._stream_seed(name)
2785
2786	def reroll (self, name: str) -> None:
2787
2788		"""
2789		Deal a named stream a fresh deterministic seed — try a new variation.
2790
2791		Bumps the per-name nonce and prints the new effective seed.  The
2792		nonce lives only in this process, so the printed seed is what lets a
2793		variation you like survive a restart: note it down, or ``lock()`` the
2794		name to pin it for the session.  Refuses on locked names.
2795
2796		Parameters:
2797			name: The stream name — usually a pattern name.
2798
2799		Example:
2800			```python
2801			comp.reroll("lead")    # prints: reroll('lead') -> effective seed ...
2802			```
2803		"""
2804
2805		if name in self._locked_names:
2806			print(f"reroll('{name}') refused: '{name}' is locked - call unlock('{name}') first")
2807			return
2808
2809		self._reroll_nonces[name] = self._reroll_nonces.get(name, 0) + 1
2810		effective = self._stream_seed(name)
2811
2812		if effective is None:
2813			print(f"reroll('{name}'): composition has no seed - randomness is unseeded")
2814			return
2815
2816		running = self._running_patterns.get(name)
2817
2818		if running is not None and hasattr(running, "_rng"):
2819			running._rng = random.Random(effective)
2820
2821		print(f"reroll('{name}') -> effective seed {effective} (nonce {self._reroll_nonces[name]})")
2822
2823	def lock (self, name: str) -> None:
2824
2825		"""
2826		Pin a named stream: keep its current effective seed and realization.
2827
2828		Engine-side state, so it survives live reload (it is never a builder
2829		swap): a locked pattern re-deals its stream from the same effective
2830		seed on every rebuild, so every cycle realizes identically, and
2831		``reroll()`` refuses with a message until ``unlock()``.
2832
2833		Parameters:
2834			name: The stream name — usually a pattern name.
2835		"""
2836
2837		self._locked_names.add(name)
2838
2839	def unlock (self, name: str) -> None:
2840
2841		"""Release a ``lock()``: the stream runs free and ``reroll()`` works again."""
2842
2843		self._locked_names.discard(name)
2844
2845	def tuning (
2846		self,
2847		source: typing.Optional[typing.Union[str, "os.PathLike"]] = None,
2848		*,
2849		cents: typing.Optional[typing.List[float]] = None,
2850		ratios: typing.Optional[typing.List[float]] = None,
2851		equal: typing.Optional[int] = None,
2852		bend_range: float = 2.0,
2853		channels: typing.Optional[typing.List[int]] = None,
2854		reference_note: int = 60,
2855		exclude_drums: bool = True,
2856	) -> None:
2857
2858		"""Set a global microtonal tuning for the composition.
2859
2860		The tuning is applied automatically after each pattern rebuild (before
2861		the pattern is scheduled).  Drum patterns (those registered with a
2862		``drum_note_map``) are excluded by default.
2863
2864		Supply exactly one of the source parameters:
2865
2866		- ``source``: path to a Scala ``.scl`` file.
2867		- ``cents``: list of cent offsets for degrees 1..N (degree 0 = 0.0 is implicit).
2868		- ``ratios``: list of frequency ratios (e.g., ``[9/8, 5/4, 4/3, 3/2, 2]``).
2869		- ``equal``: integer for N-tone equal temperament (e.g., ``equal=19``).
2870
2871		For polyphonic parts, supply a ``channels`` pool.  Notes are spread
2872		across those MIDI channels so each can carry an independent pitch bend.
2873		The synth must be configured to match ``bend_range`` (its pitch-bend range
2874		setting in semitones).
2875
2876		Parameters:
2877			source: Path to a ``.scl`` file.
2878			cents: Cent offsets for scale degrees 1..N.
2879			ratios: Frequency ratios for scale degrees 1..N.
2880			equal: Number of equal divisions of the period.
2881			bend_range: Synth pitch-bend range in semitones (default ±2).
2882			channels: Channel pool for polyphonic rotation.
2883			reference_note: MIDI note mapped to scale degree 0 (default 60 = C4).
2884			exclude_drums: When True (default), skip patterns that have a
2885			    ``drum_note_map`` (they use fixed GM pitches, not tuned ones).
2886
2887		Example:
2888			```python
2889			# Quarter-comma meantone from a Scala file
2890			comp.tuning("meanquar.scl")
2891
2892			# Just intonation from ratios
2893			comp.tuning(ratios=[9/8, 5/4, 4/3, 3/2, 5/3, 15/8, 2])
2894
2895			# 19-TET, monophonic
2896			comp.tuning(equal=19, bend_range=2.0)
2897
2898			# 31-TET with channel rotation for polyphony (channels 1-6)
2899			comp.tuning("31tet.scl", channels=[0, 1, 2, 3, 4, 5])
2900			```
2901		"""
2902		import subsequence.tuning as _tuning_mod
2903
2904		given = sum(x is not None for x in [source, cents, ratios, equal])
2905		if given == 0:
2906			raise ValueError("composition.tuning() requires one of: source, cents, ratios, or equal")
2907		if given > 1:
2908			raise ValueError("composition.tuning() accepts only one source parameter")
2909
2910		if source is not None:
2911			t = _tuning_mod.Tuning.from_scl(source)
2912		elif cents is not None:
2913			t = _tuning_mod.Tuning.from_cents(cents)
2914		elif ratios is not None:
2915			t = _tuning_mod.Tuning.from_ratios(ratios)
2916		else:
2917			t = _tuning_mod.Tuning.equal(equal)  # type: ignore[arg-type]
2918
2919		self._tuning = t
2920		self._tuning_bend_range = bend_range
2921		self._tuning_channels = channels
2922		self._tuning_reference_note = reference_note
2923		self._tuning_exclude_drums = exclude_drums
2924
2925	def display (self, enabled: bool = True, grid: bool = False, grid_scale: float = 1.0) -> None:
2926
2927		"""
2928		Enable or disable the live terminal dashboard.
2929
2930		When enabled, Subsequence uses a safe logging handler that allows a
2931		persistent status line (BPM, Key, Bar, Section, Chord) to stay at
2932		the bottom of the terminal while logs scroll above it.
2933
2934		Parameters:
2935			enabled: Whether to show the display (default True).
2936			grid: When True, render an ASCII grid visualisation of all
2937				running patterns above the status line. The grid updates
2938				once per bar, showing which steps have notes and at what
2939				velocity.
2940			grid_scale: Horizontal zoom factor for the grid (default
2941				``1.0``).  Higher values add visual columns between
2942				grid steps, revealing micro-timing from swing and groove.
2943				Snapped to the nearest integer internally for uniform
2944				marker spacing.
2945		"""
2946
2947		if enabled:
2948			self._display = subsequence.display.Display(self, grid=grid, grid_scale=grid_scale)
2949		else:
2950			self._display = None
2951
2952	def web_ui (self, http_host: str = "127.0.0.1", ws_host: str = "127.0.0.1") -> None:
2953
2954		"""
2955		Enable the realtime Web UI Dashboard.
2956
2957		When enabled, Subsequence instantiates a WebSocket server that broadcasts
2958		the current state, signals, and active patterns (with high-res timing and
2959		note data) to any connected browser clients.
2960
2961		Both servers bind to localhost by default.  Pass ``http_host`` / ``ws_host``
2962		(e.g. "0.0.0.0") to opt into LAN exposure — the dashboard is read-only but
2963		broadcasts full composition state, so only do so on a trusted network.
2964		"""
2965
2966		self._web_ui_enabled = True
2967		self._web_ui_http_host = http_host
2968		self._web_ui_ws_host = ws_host
2969
2970	def midi_input (self, device: str, clock_follow: bool = False, name: typing.Optional[str] = None) -> None:
2971
2972		"""
2973		Configure a MIDI input device for external sync and MIDI messages.
2974
2975		May be called multiple times to register additional input devices.
2976		The first call sets the primary input (device 0).  Subsequent calls
2977		add additional input devices (device 1, 2, …).  Only one device may
2978		have ``clock_follow=True``.
2979
2980		Parameters:
2981			device: Which MIDI input port to use, matched against
2982				``mido.get_input_names()``.  Treated as a pattern — ``*``
2983				and ``?`` are wildcards, matching is case-insensitive, and a
2984				name without wildcards is a substring.  See
2985				``Composition.__init__`` for why a pattern like
2986				``"*Launchpad *:0"`` survives an ALSA client id changing
2987				between runs.  Because a wrong input would desynchronise or
2988				mis-record a performance, a pattern matching nothing raises,
2989				and one matching several asks which you meant rather than
2990				guessing.
2991			clock_follow: If True, Subsequence will slave its clock to incoming
2992				MIDI Ticks. It will also follow MIDI Start/Stop/Continue
2993				commands. Only one device can have this enabled at a time.
2994			name: Optional alias for use with ``cc_map(input_device=…)`` and
2995				``cc_forward(input_device=…)``.  When omitted, the raw device
2996				name is used.
2997
2998		Example:
2999			```python
3000			# Single controller (unchanged usage)
3001			comp.midi_input("Scarlett 2i4", clock_follow=True)
3002
3003			# Multiple controllers
3004			comp.midi_input("Arturia KeyStep", name="keys")
3005			comp.midi_input("Faderfox EC4", name="faders")
3006			```
3007		"""
3008
3009		if clock_follow:
3010			if self.is_clock_following:
3011				raise ValueError("Only one input device can be configured to follow external clock (clock_follow=True)")
3012
3013		if self._input_device is None:
3014			# First call: set primary input device (device 0)
3015			self._input_device = device
3016			self._input_device_alias = name
3017			self._clock_follow = clock_follow
3018		else:
3019			# Subsequent calls: register additional input devices
3020			self._additional_inputs.append((device, name, clock_follow))
3021
3022	def midi_output (self, device: str, name: typing.Optional[str] = None, latency_ms: float = 0.0) -> int:
3023
3024		"""
3025		Register an additional MIDI output device.
3026
3027		The first output device is always the one passed to
3028		``Composition(output_device=…)`` — that is device 0.
3029		Each call to ``midi_output()`` adds the next device (1, 2, …).
3030
3031		Parameters:
3032			device: Which MIDI output port to add, matched against
3033				``mido.get_output_names()``.  Treated as a pattern —
3034				``*`` and ``?`` are wildcards, matching is
3035				case-insensitive, and a name without wildcards is a
3036				substring.  See ``Composition.__init__`` for the lookup
3037				snippet and why a pattern like ``"*U6MIDI Pro *:0"``
3038				survives an ALSA client id changing between runs.
3039			name: Optional alias for use with ``pattern(device=…)``,
3040				``cc_forward(output_device=…)``, etc.  When omitted, the raw
3041				device name is used.
3042			latency_ms: Physical output latency of this device in
3043				milliseconds, for delay compensation (default 0.0, must be
3044				non-negative). Set this when the device sounds late (e.g. a
3045				software sampler) so Subsequence delays faster devices to
3046				line everything up.
3047
3048		Returns:
3049			The integer device index assigned (1, 2, 3, …).
3050
3051		Example:
3052			```python
3053			comp = subsequence.Composition(bpm=120, output_device="MOTU Express")
3054
3055			# Returns 1 — use as device=1 or device="integra"
3056			comp.midi_output("Roland Integra", name="integra")
3057
3058			# A software sampler that sounds 20ms late
3059			comp.midi_output("Subsample", name="sampler", latency_ms=20)
3060
3061			@comp.pattern(channel=1, beats=4, device="integra")
3062			def strings (p):
3063				p.note(60, beat=0)
3064			```
3065		"""
3066
3067		if latency_ms < 0:
3068			raise ValueError(f"latency_ms must be non-negative — got {latency_ms}")
3069
3070		idx = 1 + len(self._additional_outputs)  # device 0 is always the primary
3071		self._additional_outputs.append(_AdditionalOutput(device=device, alias=name, latency_ms=latency_ms))
3072		return idx
3073
3074	def _warn_if_high_latency (self) -> None:
3075
3076		"""Warn if delay compensation adds a large whole-rig latency.
3077
3078		The slowest device defines the alignment point — every faster device is
3079		delayed up to that amount — so a large maximum means the whole rig
3080		responds late to live input.  Emitted once at startup.
3081		"""
3082
3083		candidates: typing.List[typing.Tuple[str, float]] = [("primary output", self._output_latency_ms)]
3084		candidates += [(out.alias or out.device, out.latency_ms) for out in self._additional_outputs]
3085
3086		slow_name, max_ms = max(candidates, key=lambda c: c[1])
3087
3088		if max_ms > _LATENCY_WARN_THRESHOLD_MS:
3089			logger.warning(
3090				"Device latency compensation: '%s' is the slowest at %.0fms, so faster "
3091				"devices are delayed up to %.0fms to stay aligned — live-input feel may suffer.",
3092				slow_name, max_ms, max_ms,
3093			)
3094
3095	def clock_output (self, enabled: bool = True) -> None:
3096
3097		"""
3098		Send MIDI timing clock to connected hardware.
3099
3100		When enabled, Subsequence acts as a MIDI clock master and sends
3101		standard clock messages on the output port: a Start message (0xFA)
3102		when playback begins, a Clock tick (0xF8) on every pulse (24 PPQN),
3103		and a Stop message (0xFC) when playback ends.
3104
3105		This allows hardware synthesizers, drum machines, and effect units to
3106		slave their tempo to Subsequence automatically.
3107
3108		**Note:** Clock output is automatically disabled when ``midi_input()``
3109		is called with ``clock_follow=True``, to prevent a clock feedback loop.
3110
3111		Parameters:
3112			enabled: Whether to send MIDI clock (default True).
3113
3114		Example:
3115			```python
3116			comp = subsequence.Composition(bpm=120, output_device="...")
3117			comp.clock_output()   # hardware will follow Subsequence tempo
3118			```
3119		"""
3120
3121		self._clock_output = enabled
3122
3123
3124	def link (self, quantum: float = 4.0) -> "Composition":
3125
3126		"""
3127		Enable Ableton Link tempo and phase synchronisation.
3128
3129		When enabled, Subsequence joins the local Link session and slaves its
3130		clock to the shared network tempo and beat phase.  All other Link-enabled
3131		apps on the same LAN — Ableton Live, iOS synths, other Subsequence
3132		instances — will automatically stay in time.
3133
3134		Playback starts on the next bar boundary aligned to the Link quantum,
3135		so downbeats stay in sync across all participants.
3136
3137		Requires the ``link`` optional extra::
3138
3139		    pip install subsequence[link]
3140
3141		Parameters:
3142			quantum: Beat cycle length.  ``4.0`` (default) = one bar in 4/4 time.
3143			         Change this if your composition uses a different meter.
3144
3145		Example::
3146
3147		    comp = subsequence.Composition(bpm=120, key="C")
3148		    comp.link()          # join the Link session
3149		    comp.play()
3150
3151		    # On another machine / instance:
3152		    comp2 = subsequence.Composition(bpm=120)
3153		    comp2.link()         # tempo and phase will lock to comp
3154		    comp2.play()
3155
3156		Note:
3157		    ``set_bpm()`` proposes the new tempo to the Link network when Link
3158		    is active.  The network-authoritative tempo is applied on the next
3159		    pulse, so there may be a brief lag before the change is visible.
3160		"""
3161
3162		# Eagerly check that aalink is installed — fail early with a clear message.
3163		subsequence.link_clock._require_aalink()
3164
3165		self._link_quantum = quantum
3166		return self
3167
3168
3169	def cc_map (
3170		self,
3171		cc: int,
3172		data_key: str,
3173		channel: typing.Optional[int] = None,
3174		min_val: float = 0.0,
3175		max_val: float = 1.0,
3176		input_device: subsequence.midi_utils.DeviceId = None,
3177	) -> None:
3178
3179		"""
3180		Map an incoming MIDI CC to a ``composition.data`` key.
3181
3182		When the composition receives a CC message on the configured MIDI
3183		input port, the value is scaled from the CC range (0–127) to
3184		*[min_val, max_val]* and stored in ``composition.data[data_key]``.
3185
3186		This lets hardware knobs, faders, and expression pedals control live
3187		parameters without writing any callback code.
3188
3189		**Requires** ``midi_input()`` to be called first to open an input port.
3190
3191		Parameters:
3192			cc: MIDI Control Change number (0–127).
3193			data_key: The ``composition.data`` key to write.
3194			channel: If given, only respond to CC messages on this channel.
3195				Uses the same numbering convention as ``pattern()`` (1-16
3196				by default, or 0-15 with ``zero_indexed_channels=True``).
3197				``None`` matches any channel (default).
3198			min_val: Scaled minimum — written when CC value is 0 (default 0.0).
3199			max_val: Scaled maximum — written when CC value is 127 (default 1.0).
3200			input_device: Only respond to CC messages from this input device
3201				(index or name).  ``None`` responds to any input device (default).
3202
3203		Example:
3204			```python
3205			comp.midi_input("Arturia KeyStep")
3206			comp.cc_map(74, "filter_cutoff")           # knob → 0.0–1.0
3207			comp.cc_map(7, "volume", min_val=0, max_val=127)  # volume fader
3208
3209			# Multi-device: only listen to CC 74 from the "faders" controller
3210			comp.cc_map(74, "filter", input_device="faders")
3211			```
3212		"""
3213
3214		resolved_channel = self._resolve_channel(channel) if channel is not None else None
3215
3216		self._cc_mappings.append({
3217			'cc': cc,
3218			'data_key': data_key,
3219			'channel': resolved_channel,
3220			'min_val': min_val,
3221			'max_val': max_val,
3222			'input_device': input_device,  # resolved to int index in _run()
3223		})
3224
3225
3226	def note_input (
3227		self,
3228		channel: typing.Optional[int] = None,
3229		release_ms: float = 30.0,
3230		latch: bool = False,
3231		input_device: subsequence.midi_utils.DeviceId = None,
3232	) -> None:
3233
3234		"""Track notes held on a MIDI keyboard for live arpeggiation.
3235
3236		Incoming note-on/note-off messages build a live "currently held" set
3237		that any pattern reads via ``p.held_notes()`` — typically fed straight
3238		to ``p.arpeggio()``.  The composition still authors the rhythm and
3239		motion; the player's hands supply the pitch set.  This is a live
3240		*performance* layer over the deterministic, seeded composition: when
3241		rendering headlessly there is no input, so ``p.held_notes()`` is empty
3242		and seeded output is unchanged.
3243
3244		**Requires** ``midi_input()`` to be called first to open an input port.
3245
3246		Parameters:
3247			channel: If given, only track notes on this channel.  Uses the same
3248				numbering convention as ``pattern()`` (1-16 by default, or 0-15
3249				with ``zero_indexed_channels=True``).  ``None`` tracks any
3250				channel (default).
3251			release_ms: How long (milliseconds) a released note keeps counting
3252				as held.  This smooths the momentary all-keys-up gap during a
3253				hand-position change so the arp does not drop to silence.
3254				Default 30.0; set 0.0 to release instantly.  Ignored when
3255				``latch`` is True.
3256			latch: When True, the held set persists after you lift your hands
3257				until you play a new chord (the first key after every key is up
3258				replaces it) — like a hardware arp's latch.
3259			input_device: Only track notes from this input device (index or
3260				name).  ``None`` tracks any input device (default).
3261
3262		Example:
3263			```python
3264			comp.midi_input("Arturia KeyStep")
3265			comp.note_input(channel=1, release_ms=30)
3266
3267			@comp.pattern(channel=6, beats=4)
3268			def arp (p):
3269			    p.arpeggio(p.held_notes(), direction="up")  # rests when silent
3270			```
3271		"""
3272
3273		if self._note_input is not None:
3274			raise RuntimeError("only one note_input source is supported — named multi-source is not yet available")
3275
3276		resolved_channel = self._resolve_channel(channel) if channel is not None else None
3277
3278		self._note_input = {
3279			'channel': resolved_channel,
3280			'release_ms': release_ms,
3281			'latch': latch,
3282			'input_device': input_device,  # resolved to int index in _run()
3283		}
3284
3285
3286	@staticmethod
3287	def _make_cc_forward_transform (
3288		output: typing.Union[str, typing.Callable],
3289		cc: int,
3290		output_channel: typing.Optional[int],
3291	) -> typing.Callable:
3292
3293		"""Build a transform callable from a preset string or user-supplied callable.
3294
3295		The returned callable has signature ``(value: int, channel: int) -> Optional[mido.Message]``
3296		where ``channel`` is the 0-indexed incoming channel.
3297		"""
3298
3299		import mido as _mido
3300
3301		def _out_ch (incoming: int) -> int:
3302			return output_channel if output_channel is not None else incoming
3303
3304		if callable(output):
3305			if output_channel is None:
3306				return output
3307			def _wrapped (value: int, channel: int) -> typing.Optional[typing.Any]:
3308				msg = output(value, channel)
3309
3310				if msg is None:
3311					return None
3312
3313				# copy() re-channels without rebuilding: reconstructing from
3314				# __dict__ passed 'type' twice and raised TypeError on every
3315				# message, so callable+output_channel never forwarded anything.
3316				return msg.copy(channel=output_channel)
3317			return _wrapped
3318
3319		if output == 'cc':
3320			def _cc_identity (value: int, channel: int) -> typing.Any:
3321				return _mido.Message('control_change', channel=_out_ch(channel), control=cc, value=value)
3322			return _cc_identity
3323
3324		if output.startswith('cc:'):
3325			try:
3326				target_cc = int(output[3:])
3327			except ValueError:
3328				raise ValueError(f"cc_forward(): invalid preset '{output}' — expected 'cc:N' where N is 0–127")
3329			if not 0 <= target_cc <= 127:
3330				raise ValueError(f"cc_forward(): CC number {target_cc} out of range 0–127")
3331			def _cc_remap (value: int, channel: int) -> typing.Any:
3332				return _mido.Message('control_change', channel=_out_ch(channel), control=target_cc, value=value)
3333			return _cc_remap
3334
3335		if output == 'pitchwheel':
3336			def _pitchwheel (value: int, channel: int) -> typing.Any:
3337				pitch = int(value / 127 * 16383) - 8192
3338				return _mido.Message('pitchwheel', channel=_out_ch(channel), pitch=pitch)
3339			return _pitchwheel
3340
3341		raise ValueError(
3342			f"cc_forward(): unknown preset '{output}'. "
3343			"Use 'cc', 'cc:N' (e.g. 'cc:74'), 'pitchwheel', or a callable."
3344		)
3345
3346
3347	def cc_forward (
3348		self,
3349		cc: int,
3350		output: typing.Union[str, typing.Callable],
3351		*,
3352		channel: typing.Optional[int] = None,
3353		output_channel: typing.Optional[int] = None,
3354		mode: str = "instant",
3355		input_device: subsequence.midi_utils.DeviceId = None,
3356		output_device: subsequence.midi_utils.DeviceId = None,
3357	) -> None:
3358
3359		"""
3360		Forward an incoming MIDI CC to the MIDI output in real-time.
3361
3362		Unlike ``cc_map()`` which writes incoming CC values to ``composition.data``
3363		for use at pattern rebuild time, ``cc_forward()`` routes the signal
3364		directly to the MIDI output — bypassing the pattern cycle entirely.
3365
3366		Both ``cc_map()`` and ``cc_forward()`` may be registered for the same CC
3367		number; they operate independently.
3368
3369		Parameters:
3370			cc: Incoming CC number to listen for (0–127).
3371			output: What to send. Either a **preset string**:
3372
3373				- ``"cc"`` — identity forward, same CC number and value.
3374				- ``"cc:N"`` — forward as CC number N (e.g. ``"cc:74"``).
3375				- ``"pitchwheel"`` — scale 0–127 to -8192..8191 and send as pitch bend.
3376
3377				Or a **callable** with signature
3378				``(value: int, channel: int) -> Optional[mido.Message]``.
3379				Return a fully formed ``mido.Message`` to send, or ``None`` to suppress.
3380				``channel`` is 0-indexed (the incoming channel).
3381			channel: If given, only respond to CC messages on this channel.
3382				Uses the same numbering convention as ``cc_map()``.
3383				``None`` matches any channel (default).
3384			output_channel: Override the output channel. ``None`` uses the
3385				incoming channel. Uses the same numbering convention as ``pattern()``.
3386			input_device: Only respond to CC from this input device — an index,
3387				a registered name, or ``None`` for any input (default), the
3388				same convention as ``cc_map()``.
3389			output_device: Send to this output device — an index, a registered
3390				name, or ``None`` for the primary output (default).
3391			mode: Dispatch mode:
3392
3393				- ``"instant"`` *(default)* — send immediately on the MIDI input
3394				  callback thread. Lowest latency (~1–5 ms). Instant forwards are
3395				  **not** recorded when recording is enabled.
3396				- ``"queued"`` — inject into the sequencer event queue and send at
3397				  the next pulse boundary (~0–20 ms at 120 BPM). Queued forwards
3398				  **are** recorded when recording is enabled.
3399
3400		Example:
3401			```python
3402			comp.midi_input("Arturia KeyStep")
3403
3404			# CC 1 → CC 1 (identity, instant)
3405			comp.cc_forward(1, "cc")
3406
3407			# CC 1 → pitch bend on channel 1, queued (recordable)
3408			comp.cc_forward(1, "pitchwheel", output_channel=1, mode="queued")
3409
3410			# CC 1 → CC 74, custom channel
3411			comp.cc_forward(1, "cc:74", output_channel=2)
3412
3413			# Custom transform — remap CC range 0–127 to CC 74 range 40–100
3414			import subsequence.midi as midi
3415			comp.cc_forward(1, lambda v, ch: midi.cc(74, int(v / 127 * 60) + 40, channel=ch))
3416
3417			# Forward AND map to data simultaneously — both active on the same CC
3418			comp.cc_map(1, "mod_wheel")
3419			comp.cc_forward(1, "cc:74")
3420			```
3421		"""
3422
3423		if not 0 <= cc <= 127:
3424			raise ValueError(f"cc_forward(): cc {cc} out of range 0–127")
3425
3426		if mode not in ('instant', 'queued'):
3427			raise ValueError(f"cc_forward(): mode must be 'instant' or 'queued', got '{mode}'")
3428
3429		resolved_in_channel = self._resolve_channel(channel) if channel is not None else None
3430		resolved_out_channel = self._resolve_channel(output_channel) if output_channel is not None else None
3431
3432		transform = self._make_cc_forward_transform(output, cc, resolved_out_channel)
3433
3434		self._cc_forwards.append({
3435			'cc': cc,
3436			'channel': resolved_in_channel,
3437			'output_channel': resolved_out_channel,
3438			'mode': mode,
3439			'transform': transform,
3440			'input_device': input_device,   # resolved to int index in _run()
3441			'output_device': output_device, # resolved to int index in _run()
3442		})
3443
3444
3445	def live (self, port: int = 5555) -> None:
3446
3447		"""
3448		Enable the live coding eval server.
3449
3450		This allows you to connect to a running composition using the
3451		``subsequence.live_client`` REPL and hot-swap pattern code or
3452		modify variables in real-time.
3453
3454		Security:
3455			The server executes arbitrary Python in this process — it is **not** a
3456			sandbox.  It binds to localhost only and is opt-in, but any process on
3457			the same machine that can reach the port gains full code execution here.
3458			Do not enable it on shared or multi-user hosts, and never expose the
3459			port to a network.
3460
3461		Parameters:
3462			port: The TCP port to listen on (default 5555).
3463		"""
3464
3465		self._live_server = subsequence.live_server.LiveServer(self, port=port)
3466		self._is_live = True
3467
3468	def watch (self, path: typing.Union[str, pathlib.Path], poll_interval: float = 0.25) -> None:
3469
3470		"""Watch a Python file and reload it into the composition on every save.
3471
3472		The watched file is exec'd into a namespace with ``composition`` and
3473		``subsequence`` available.  ``@composition.pattern`` decorators inside
3474		the file hot-swap their corresponding running patterns in place;
3475		patterns whose function bodies have been deleted from the file are
3476		unregistered automatically on the next reload (notes stopped,
3477		removed from the running-pattern set).
3478
3479		An **initial synchronous load** happens here — if the file has a
3480		``SyntaxError`` or doesn't exist at this moment, the exception
3481		propagates so the user knows immediately.  Subsequent reloads
3482		happen on the composition's event loop and tolerate transient
3483		errors (logged, skipped).
3484
3485		Call BEFORE ``composition.play()``.  Reloads happen on the
3486		composition's event loop, so all mutations are thread-safe.
3487
3488		See the "Live coding via file watching" section of the README for
3489		the recommended wrapper-script + live-file split.
3490
3491		Parameters:
3492			path: Path to the Python file to watch.
3493			poll_interval: Seconds between ``mtime`` polls (default 0.25 s).
3494
3495		Example::
3496
3497			# live_init.py — runs once
3498			composition = subsequence.Composition(bpm=120, key="E")
3499			composition.harmony(style="aeolian_minor")
3500			composition.watch("live_patterns.py")
3501			composition.play()
3502		"""
3503
3504		# Required for the decorator hot-swap path to fire on re-decoration.
3505		self._is_live = True
3506
3507		# Detect the single-file workflow: if watch() is called from inside
3508		# the very file being watched, the outer Python script execution will
3509		# already register the patterns (the decorators sit at module level
3510		# below ``watch(__file__)``).  In that case, _load_initial's re-exec
3511		# would double-register every pattern, so skip it.  For the two-file
3512		# workflow (path != caller's __file__) the initial exec is essential
3513		# — it's the only way the watched file's patterns ever reach the
3514		# composition.
3515		caller_file = self._caller_module_file()
3516		self_watch = False
3517		if caller_file is not None:
3518			try:
3519				self_watch = pathlib.Path(caller_file).resolve() == pathlib.Path(path).resolve()
3520			except OSError:
3521				self_watch = False
3522
3523		self._live_reloader = subsequence.live_reloader.LiveReloader(
3524			composition = self,
3525			path = path,
3526			poll_interval = poll_interval,
3527			skip_initial_exec = self_watch,
3528		)
3529		self._live_reloader.start()
3530
3531	@staticmethod
3532	def _caller_module_file () -> typing.Optional[str]:
3533
3534		"""Return ``__file__`` of the module that invoked the caller, if available.
3535
3536		Walks one frame up the call stack — the immediate caller is
3537		``watch()``, so ``f_back`` is the user's code.  Returns the
3538		module-level ``__file__`` of that frame's globals; ``None`` when
3539		the caller has no ``__file__`` (REPL, exec'd context, etc.).
3540		"""
3541
3542		frame = inspect.currentframe()
3543		if frame is None or frame.f_back is None or frame.f_back.f_back is None:
3544			return None
3545		# f_back = watch(); f_back.f_back = user code calling watch().
3546		return frame.f_back.f_back.f_globals.get("__file__")
3547
3548	def load_patterns (
3549		self,
3550		source:       str,
3551		source_label: str = "<string>",
3552	) -> None:
3553
3554		"""Compile and apply a pattern-source string to the composition.
3555
3556		Equivalent to one ``watch()`` reload triggered by save, but with the
3557		source presented in-memory rather than on disk.  Useful for web /
3558		REST handlers that accept pattern uploads from a trusted contributor,
3559		or for one-shot session loads with no file backing.
3560
3561		Behaviour mirrors ``watch()``:
3562
3563		* The source is exec'd into a fresh namespace with ``composition``
3564		  and ``subsequence`` in scope.
3565		* ``@composition.pattern`` decorators in the source hot-swap their
3566		  corresponding running patterns in place.
3567		* Patterns currently running but **not** declared in the source are
3568		  unregistered — the source is treated as the full new truth.
3569		* If the composition is already playing, the swap happens on the
3570		  event loop thread; the call blocks until it completes.
3571		* If the composition has not yet called ``play()``, the source runs
3572		  on the caller's thread; decorators populate ``_pending_patterns``
3573		  and ``play()`` picks them up in the usual way.
3574
3575		Errors are raised so the caller can act on them:
3576
3577		* ``SyntaxError`` if ``source`` fails to compile.
3578		* The exception raised inside ``exec()`` for any runtime error.
3579		* ``RuntimeError`` if called from inside the composition's own
3580		  event loop thread (would deadlock — see Threading below).
3581
3582		In either failure case, existing composition state is preserved —
3583		the diff-and-unregister phase is skipped if exec raised, so a
3584		half-broken upload cannot tear down working patterns.
3585
3586		Threading:
3587			Designed to be called from a thread DIFFERENT from the
3588			composition's event loop — typically a web-handler worker.
3589			Cannot be called from inside the loop itself (a pattern
3590			callback, an asyncio task spawned by the composition).  From
3591			there, ``await composition._apply_source_async(...)`` directly.
3592
3593		SECURITY WARNING: ``exec()`` is not sandboxed.  The source has full
3594		Python access in this process.  Only pass source from trusted
3595		senders.  The built-in blocklist (``help``, ``input``, ``breakpoint``,
3596		``exit``, ``quit``) prevents calls that would stall the event loop;
3597		it is not a security boundary.
3598
3599		Parameters:
3600			source:       Python source declaring ``@composition.pattern``
3601				functions.
3602			source_label: Identifier used in compile errors and tracebacks
3603				(appears as the filename in ``SyntaxError`` and ``__file__``-
3604				style traceback lines).  Default ``"<string>"``.
3605		"""
3606
3607		# Required for the decorator hot-swap path to fire on re-decoration.
3608		self._is_live = True
3609
3610		# Compile on the caller's thread so SyntaxError comes back fast,
3611		# before any cross-thread scheduling.
3612		compiled = compile(source, source_label, "exec")
3613		namespace = self._build_live_namespace(source_label = source_label)
3614
3615		loop = self._sequencer._event_loop
3616
3617		if loop is not None and loop.is_running():
3618
3619			# Refuse to deadlock: calling load_patterns() from inside the
3620			# composition's own event loop (e.g. from a pattern callback or
3621			# an asyncio task spawned by the composition) would have us
3622			# block waiting for a coroutine that can only run when this
3623			# thread yields.  Tell the caller exactly what to do instead.
3624			try:
3625				current_loop: typing.Optional[asyncio.AbstractEventLoop] = asyncio.get_running_loop()
3626			except RuntimeError:
3627				current_loop = None
3628
3629			if current_loop is loop:
3630				raise RuntimeError(
3631					"load_patterns() cannot be called from inside the composition's "
3632					"event loop thread — it would deadlock waiting for the "
3633					"scheduled coroutine to run on the very thread that's blocked. "
3634					"From a worker thread, call it normally.  From an async "
3635					"coroutine already on the loop, "
3636					"`await composition._apply_source_async(compile(source, label, 'exec'), "
3637					"composition._build_live_namespace())` instead."
3638				)
3639
3640			# Composition is playing — mutation must happen on the loop thread.
3641			# future.result() blocks the caller until the coroutine finishes
3642			# and re-raises any exception it threw.
3643			future = asyncio.run_coroutine_threadsafe(
3644				self._apply_source_async(compiled, namespace, source_key = source_label),
3645				loop = loop,
3646			)
3647			future.result()
3648
3649		else:
3650			# Pre-play: no event loop yet.  Decorators populate
3651			# _pending_patterns; play() graduates them in the usual way.
3652			# Diff-and-unregister is unnecessary here — nothing is running,
3653			# but RECORD what this source declares so a later post-play
3654			# reload under the same label can tear down its deletions.
3655			self._declared_names = set()
3656			exec(compiled, namespace)
3657			self._source_declared[source_label] = set(self._declared_names)
3658
3659	async def _apply_source_async (
3660		self,
3661		compiled:  types.CodeType,
3662		namespace: typing.Dict[str, typing.Any],
3663		source_key: str = "<live>",
3664	) -> None:
3665
3666		"""Execute pre-compiled live source against the running composition.
3667
3668		Runs on the event loop thread.  Performs ``exec()``, graduates any
3669		newly-decorated patterns into ``_running_patterns``, then unregisters
3670		any patterns that *this source* declared on its previous exec but no
3671		longer declares (keyed by ``source_key`` — a watched file's path or a
3672		``load_patterns`` label).  Patterns registered by the wrapper script
3673		or by another source are never this source's to tear down.
3674
3675		Raises whatever ``exec()`` raises.  When that happens, the diff-and-
3676		unregister phase is skipped — the namespace is incomplete, so any
3677		patterns the source failed to reach would be misinterpreted as
3678		deletions and torn down.
3679
3680		Called from two places:
3681
3682		* ``Composition.load_patterns()`` via ``run_coroutine_threadsafe``.
3683		* ``LiveReloader._reload_async`` directly (already on the loop).
3684		"""
3685
3686		# Track which patterns the source declares this exec.  pattern() and
3687		# layer() add their (resolved) names to _declared_names as they run, so
3688		# this covers decorated patterns AND layer()/merged patterns — the latter
3689		# have no module-level callable to match against by name, which is why the
3690		# old namespace-based diff tore layers down on every reload.
3691		self._declared_names = set()
3692
3693		# Bail before any state mutation if exec raises — propagates to
3694		# the caller (load_patterns re-raises; LiveReloader catches + logs).
3695		exec(compiled, namespace)
3696
3697		# Graduate newly-decorated patterns from _pending_patterns into
3698		# _running_patterns so they start firing on the next reschedule.
3699		# Patterns that hot-swapped via the decorator/layer path don't appear
3700		# in _pending_patterns and don't need this step.
3701		await self._activate_new_pending_patterns()
3702
3703		# Detect deletions: a name THIS source declared last time but not this
3704		# time has been removed by the user and should be torn down.  (An
3705		# unknown source — first exec — tears down nothing: patterns running
3706		# from the wrapper script or another source are not ours to remove.)
3707		# Decorators/layer() do NOT remove from _running_patterns when a
3708		# definition disappears from the source.
3709		previous = self._source_declared.get(source_key)
3710
3711		if previous is not None:
3712			for name in previous - self._declared_names:
3713				if name in self._running_patterns:
3714					self.unregister(name)
3715
3716		self._source_declared[source_key] = set(self._declared_names)
3717
3718	def _build_live_namespace (self, source_label: str = "<live>") -> typing.Dict[str, typing.Any]:
3719
3720		"""Build a fresh namespace dict for exec'ing live source.
3721
3722		Provides ``composition`` (this Composition), ``subsequence`` (the
3723		package), and a safe builtins set with ``help``, ``input``,
3724		``breakpoint``, ``exit``, ``quit`` blocked.
3725
3726		Also injects two dunder globals that make the single-file live-coding
3727		workflow ergonomic:
3728
3729		* ``__name__ = "__live_reload__"`` — so ``if __name__ == "__main__":``
3730		  blocks in the watched file are *skipped* during live reload.  The
3731		  same file run directly with ``python my_session.py`` sees
3732		  ``__name__ == "__main__"`` and runs setup; saves trigger reload
3733		  with ``__name__ == "__live_reload__"``, skipping setup and only
3734		  re-running pattern definitions.
3735		* ``__file__ = source_label`` — so ``composition.watch(__file__)``
3736		  and any user code referencing ``__file__`` works inside the live
3737		  namespace.  Set to the file path for ``LiveReloader``, the
3738		  user-supplied ``source_label`` for ``Composition.load_patterns``,
3739		  and ``"<live>"`` for ``LiveServer``.
3740
3741		Single source of truth: ``live_reloader`` (file watching),
3742		``live_server`` (TCP REPL), and ``load_patterns`` (string source)
3743		all call this so live source sees the same environment from any
3744		entry point.
3745
3746		The blocklist prevents calls that would stall the async event loop
3747		running the sequencer.  It is **not** a security sandbox — exec'd
3748		code can still do anything Python allows.
3749
3750		Parameters:
3751			source_label: Value to bind to ``__file__`` in the namespace.
3752				Defaults to ``"<live>"``.
3753		"""
3754
3755		import subsequence  # local import: this module is imported during subsequence init
3756
3757		safe_builtins = {name: getattr(builtins, name) for name in dir(builtins)}
3758
3759		blocked = {"help", "input", "breakpoint", "exit", "quit"}
3760
3761		for name in blocked:
3762			safe_builtins[name] = _live_blocked(name)
3763
3764		return {
3765			"__builtins__": safe_builtins,
3766			"__name__":     "__live_reload__",
3767			"__file__":     source_label,
3768			"composition":  self,
3769			"subsequence":  subsequence,
3770		}
3771
3772	def osc (self, receive_port: int = 9000, send_port: int = 9001, send_host: str = "127.0.0.1", receive_host: str = "0.0.0.0") -> None:
3773
3774		"""
3775		Enable bi-directional Open Sound Control (OSC).
3776
3777		Subsequence will listen for commands (like ``/bpm`` or ``/mute``) and
3778		broadcast its internal state (like ``/chord`` or ``/bar``) over UDP.
3779
3780		Parameters:
3781			receive_port: Port to listen for incoming OSC messages (default 9000).
3782			send_port: Port to send state updates to (default 9001).
3783			send_host: The IP address to send updates to (default "127.0.0.1").
3784			receive_host: Interface to listen on (default "0.0.0.0" — all
3785				interfaces, so external OSC controllers on the LAN can reach it).
3786				The listener can change tempo, mute patterns, and write data, so on
3787				an untrusted network restrict it with ``receive_host="127.0.0.1"``.
3788		"""
3789
3790		self._osc_server = subsequence.osc.OscServer(
3791			self,
3792			receive_port = receive_port,
3793			send_port = send_port,
3794			send_host = send_host,
3795			receive_host = receive_host
3796		)
3797
3798	def osc_map (self, address: str, handler: typing.Callable) -> None:
3799
3800		"""
3801		Register a custom OSC handler.
3802
3803		Must be called after :meth:`osc` has been configured.
3804
3805		Parameters:
3806			address: OSC address pattern to match (e.g. ``"/my/param"``).
3807			handler: Callable invoked with ``(address, *args)`` when a
3808				matching message arrives.
3809
3810		Example::
3811
3812			composition.osc()
3813
3814			def on_intensity (address, value):
3815				composition.data["intensity"] = float(value)
3816
3817			composition.osc_map("/intensity", on_intensity)
3818		"""
3819
3820		if self._osc_server is None:
3821			raise RuntimeError("Call composition.osc() before composition.osc_map()")
3822
3823		self._osc_server.map(address, handler)
3824
3825	def set_bpm (self, bpm: float) -> None:
3826
3827		"""
3828		Instantly change the tempo.
3829
3830		Parameters:
3831			bpm: The new tempo in beats per minute.
3832
3833		When Ableton Link is active, this proposes the new tempo to the Link
3834		network instead of applying it locally.  The network-authoritative tempo
3835		is picked up on the next pulse.
3836		"""
3837
3838		self._sequencer.set_bpm(bpm)
3839
3840		if not self.is_clock_following and self._link_quantum is None:
3841			self.bpm = bpm
3842
3843	def target_bpm (self, bpm: float, bars: int, shape: str = "linear") -> None:
3844
3845		"""
3846		Smoothly ramp the tempo to a target value over a number of bars.
3847
3848		Parameters:
3849			bpm: Target tempo in beats per minute.
3850			bars: Duration of the transition in bars.
3851			shape: Easing curve name.  Defaults to ``"linear"``.
3852			       ``"ease_in_out"`` or ``"s_curve"`` are recommended for natural-
3853			       sounding tempo changes.  See :mod:`subsequence.easing` for all
3854			       available shapes.
3855
3856		Example:
3857			```python
3858			# Accelerate to 140 BPM over the next 8 bars with a smooth S-curve
3859			comp.target_bpm(140, bars=8, shape="ease_in_out")
3860			```
3861
3862		Note:
3863			Ignored while Ableton Link is active — the shared session tempo is
3864			authoritative.  Use ``set_bpm()`` to propose a tempo to the Link network.
3865		"""
3866
3867		self._sequencer.set_target_bpm(bpm, bars, shape)
3868
3869	def live_info (self) -> typing.Dict[str, typing.Any]:
3870
3871		"""
3872		Return a dictionary containing the current state of the composition.
3873		
3874		Includes BPM, key, current bar, active section, current chord, 
3875		running patterns, and custom data.
3876		"""
3877
3878		section_info = None
3879		if self._form_state is not None:
3880			section = self._form_state.get_section_info()
3881			if section is not None:
3882				section_info = {
3883					"name": section.name,
3884					"bar": section.bar,
3885					"bars": section.bars,
3886					"progress": section.progress
3887				}
3888
3889		chord_name = None
3890		sounding_chord = self.current_chord()
3891		if sounding_chord is not None:
3892			chord_name = sounding_chord.name()
3893
3894		pattern_list = []
3895		channel_offset = 0 if self._zero_indexed_channels else 1
3896		for name, pat in self._running_patterns.items():
3897			pattern_list.append({
3898				"name": name,
3899				"channel": pat.channel + channel_offset,
3900				"length": pat.length,
3901				"cycle": pat._cycle_count,
3902				"muted": pat._muted,
3903				"tweaks": dict(pat._tweaks)
3904			})
3905
3906		return {
3907			"bpm": self._sequencer.current_bpm,
3908			"key": self.key,
3909			"bar": self._builder_bar,
3910			"section": section_info,
3911			"chord": chord_name,
3912			"patterns": pattern_list,
3913			"input_device": self._input_device,
3914			"clock_follow": self.is_clock_following,
3915			"data": self.data
3916		}
3917
3918	def mute (self, name: str) -> None:
3919
3920		"""
3921		Mute a running pattern by name.
3922		
3923		The pattern continues to 'run' and increment its cycle count in 
3924		the background, but it will not produce any MIDI notes until unmuted.
3925
3926		Parameters:
3927			name: The function name of the pattern to mute.
3928		"""
3929
3930		if name not in self._running_patterns:
3931			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3932
3933		# The performer takes ownership: if a transition's approach window had
3934		# muted this pattern, drop it from that set so the section boundary
3935		# does not silently unmute it ("performer mutes win").
3936		self._transition_muted.discard(name)
3937
3938		self._running_patterns[name]._muted = True
3939		logger.info(f"Muted pattern: {name}")
3940
3941	def unmute (self, name: str) -> None:
3942
3943		"""
3944		Unmute a previously muted pattern.
3945		"""
3946
3947		if name not in self._running_patterns:
3948			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3949
3950		# Symmetric ownership claim: an explicit unmute means the transition
3951		# machinery should no longer manage this pattern at the boundary.
3952		self._transition_muted.discard(name)
3953
3954		self._running_patterns[name]._muted = False
3955		logger.info(f"Unmuted pattern: {name}")
3956
3957	def unregister (self, name: str) -> None:
3958
3959		"""Fully remove a running pattern from rotation.
3960
3961		Unlike ``mute()`` (which keeps the pattern alive but silent),
3962		``unregister()`` tears the pattern down entirely.  It sets
3963		``pattern._removed = True`` so the sequencer's reschedule loop
3964		skips re-adding it on the next pulse; sends ``note_off`` for any
3965		of the pattern's currently-sounding notes on the primary
3966		destination AND on every mirror destination (so drones and
3967		sustaining notes stop immediately); and removes the entry from
3968		``_running_patterns`` so it no longer appears in ``live_info()``,
3969		the terminal grid, or any other consumer that enumerates running
3970		patterns.
3971
3972		Already-queued events in the sequencer's event queue play out —
3973		note_offs are paired with their note_ons at queue time, so notes
3974		end at their natural duration; only drones rely on the targeted
3975		``_stop_pattern_notes`` pass.
3976
3977		Idempotent: silently logs a ``debug`` and returns if the pattern
3978		is already absent.  Useful from both the live REPL
3979		(``composition.live()``) and the file watcher
3980		(``composition.watch()``), which calls this for any pattern
3981		removed from the watched file between reloads.
3982
3983		Parameters:
3984			name: Function name of the pattern to remove.
3985		"""
3986
3987		if name not in self._running_patterns:
3988			logger.debug(f"unregister() no-op: pattern '{name}' not running")
3989			return
3990
3991		pattern = self._running_patterns[name]
3992
3993		# Mark for removal first so the reschedule loop sees the flag even if
3994		# it fires concurrently with the note-off pass below.
3995		pattern._removed = True
3996
3997		# Stop sustaining notes (including drones) on every destination this
3998		# pattern outputs to.  Fire-and-forget across threads via the event
3999		# loop; ``_stop_pattern_notes`` acquires the queue lock internally.
4000		if self._sequencer._event_loop is not None:
4001			asyncio.run_coroutine_threadsafe(
4002				self._sequencer._stop_pattern_notes(pattern),
4003				loop = self._sequencer._event_loop,
4004			)
4005
4006		def _finalise_removal () -> None:
4007			self._running_patterns.pop(name, None)
4008
4009			# Forget any pending (not-yet-graduated) declaration too, so a
4010			# later live reload cannot resurrect the pattern.
4011			self._pending_patterns = [
4012				pending for pending in self._pending_patterns
4013				if pending.builder_fn.__name__ != name
4014			]
4015
4016			logger.info(f"Unregistered pattern: {name}")
4017
4018		# The running-patterns dict is iterated by the display, web UI, and
4019		# reschedule loop on the event loop thread — mutate it there when this
4020		# call arrives from another thread (e.g. the live TCP server).
4021		loop = self._sequencer._event_loop
4022
4023		try:
4024			on_loop = loop is not None and asyncio.get_running_loop() is loop
4025		except RuntimeError:
4026			on_loop = False
4027
4028		if loop is not None and loop.is_running() and not on_loop:
4029			loop.call_soon_threadsafe(_finalise_removal)
4030		else:
4031			_finalise_removal()
4032
4033	def mirror (self, name: str, device: int, channel: int, drum_note_map: typing.Optional[typing.Dict[str, int]] = None) -> None:
4034
4035		"""
4036		Add a mirror destination to a running pattern.
4037
4038		Every note, CC, pitch bend, NRPN/RPN, program change, SysEx, and drone
4039		event the pattern emits will also be sent to ``(device, channel)``,
4040		starting from the next cycle rebuild.  Idempotent on ``(device, channel)``
4041		— calling with the same destination twice does not double-fan; calling
4042		again with a different ``drum_note_map`` re-points it in place.
4043
4044		Parameters:
4045			name: Function name of the pattern to mirror.
4046			device: Output device index (the integer returned from
4047				``midi_output()``; 0 = primary device).
4048			channel: MIDI channel using this composition's numbering convention
4049				(1-16 by default; 0-15 if ``zero_indexed_channels=True``).
4050			drum_note_map: Optional per-destination drum map.  When set, mirrored
4051				drum hits are re-resolved by name through it, so a named voice
4052				lands on this device's own note number — see the README
4053				"MIDI mirroring" section.
4054
4055		Bandwidth: each mirror adds another full copy of the pattern's events.
4056		See the README "MIDI mirroring" section for the tradeoffs.
4057		"""
4058
4059		if name not in self._running_patterns:
4060			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4061
4062		resolved_channel = self._resolve_channel(channel)
4063		prefix = (device, resolved_channel)
4064		entry: subsequence.pattern.MirrorSpec = prefix if drum_note_map is None else (device, resolved_channel, drum_note_map)
4065
4066		pattern = self._running_patterns[name]
4067
4068		# Mirror-to-self check: comparing the (device, channel) prefix against the
4069		# live pattern's resolved destination.  Unlike the decorator path this is
4070		# always concrete.
4071		if prefix == (pattern.device, pattern.channel):
4072			logger.warning(
4073				f"Mirror destination {prefix} matches '{name}'s primary destination "
4074				f"— every event will double-fire on this (device, channel).  This is almost "
4075				f"certainly unintended."
4076			)
4077
4078		# Idempotent on (device, channel): replace any existing entry for the same
4079		# destination (so its map can be re-pointed), else append.
4080		existing_index = next((idx for idx, e in enumerate(pattern.mirrors) if (e[0], e[1]) == prefix), None)
4081		if existing_index is None:
4082			pattern.mirrors.append(entry)
4083			logger.info(f"Mirror added: {name} -> device={device}, channel={resolved_channel}")
4084		elif pattern.mirrors[existing_index] != entry:
4085			pattern.mirrors[existing_index] = entry
4086			logger.info(f"Mirror updated: {name} -> device={device}, channel={resolved_channel}")
4087		else:
4088			logger.debug(f"Mirror already present on {name}: device={device}, channel={resolved_channel}")
4089
4090	def unmirror (self, name: str, device: int, channel: int) -> None:
4091
4092		"""
4093		Remove a single mirror destination from a running pattern.
4094
4095		Matches on ``(device, channel)`` only — any attached ``drum_note_map`` is
4096		ignored.  Idempotent: silently does nothing if the destination is not
4097		currently mirrored.  The change applies on the next cycle rebuild.
4098		"""
4099
4100		if name not in self._running_patterns:
4101			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4102
4103		resolved_channel = self._resolve_channel(channel)
4104		prefix = (device, resolved_channel)
4105
4106		pattern = self._running_patterns[name]
4107
4108		filtered = [e for e in pattern.mirrors if (e[0], e[1]) != prefix]
4109		if len(filtered) != len(pattern.mirrors):
4110			pattern.mirrors[:] = filtered
4111			logger.info(f"Mirror removed: {name} -> device={device}, channel={resolved_channel}")
4112		else:
4113			logger.debug(f"unmirror() no-op on {name}: device={device}, channel={resolved_channel} not in mirrors")
4114
4115	def unmirror_all (self, name: str) -> None:
4116
4117		"""
4118		Remove every mirror destination from a running pattern.
4119		"""
4120
4121		if name not in self._running_patterns:
4122			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4123
4124		pattern = self._running_patterns[name]
4125
4126		if pattern.mirrors:
4127			pattern.mirrors.clear()
4128			logger.info(f"All mirrors cleared on pattern: {name}")
4129
4130	def tweak (self, name: str, **kwargs: typing.Any) -> None:
4131
4132		"""Override parameters for a running pattern.
4133
4134		Values set here are available inside the pattern's builder
4135		function via ``p.param()``.  They persist across rebuilds
4136		until explicitly changed or cleared.  Changes take effect
4137		on the next rebuild cycle.
4138
4139		Parameters:
4140			name: The function name of the pattern.
4141			``**kwargs``: Parameter names and their new values.
4142
4143		Example (from the live REPL)::
4144
4145			composition.tweak("bass", pitches=[48, 52, 55, 60])
4146		"""
4147
4148		if name not in self._running_patterns:
4149			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4150
4151		self._running_patterns[name]._tweaks.update(kwargs)
4152		logger.info(f"Tweaked pattern '{name}': {list(kwargs.keys())}")
4153
4154	def clear_tweak (self, name: str, *param_names: str) -> None:
4155
4156		"""Remove tweaked parameters from a running pattern.
4157
4158		If no parameter names are given, all tweaks for the pattern
4159		are cleared and every ``p.param()`` call reverts to its
4160		default.
4161
4162		Parameters:
4163			name: The function name of the pattern.
4164			*param_names: Specific parameter names to clear.  If
4165				omitted, all tweaks are removed.
4166		"""
4167
4168		if name not in self._running_patterns:
4169			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4170
4171		if not param_names:
4172			self._running_patterns[name]._tweaks.clear()
4173			logger.info(f"Cleared all tweaks for pattern '{name}'")
4174		else:
4175			for param_name in param_names:
4176				self._running_patterns[name]._tweaks.pop(param_name, None)
4177			logger.info(f"Cleared tweaks for pattern '{name}': {list(param_names)}")
4178
4179	def get_tweaks (self, name: str) -> typing.Dict[str, typing.Any]:
4180
4181		"""Return a copy of the current tweaks for a running pattern.
4182
4183		Parameters:
4184			name: The function name of the pattern.
4185		"""
4186
4187		if name not in self._running_patterns:
4188			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4189
4190		return dict(self._running_patterns[name]._tweaks)
4191
4192	def schedule (self, fn: typing.Callable, cycle_beats: int, reschedule_lookahead: int = 1, wait_for_initial: bool = False, defer: bool = False) -> None:
4193
4194		"""
4195		Register a custom function to run on a repeating beat-based cycle.
4196
4197		Subsequence automatically runs synchronous functions in a thread pool
4198		so they don't block the timing-critical MIDI clock. Async functions
4199		are run directly on the event loop.
4200
4201		Parameters:
4202			fn: The function to call.
4203			cycle_beats: How often to call it (e.g., 4 = every bar).
4204			reschedule_lookahead: How far in advance to schedule the next call.
4205			wait_for_initial: If True, run the function once during startup
4206				and wait for it to complete before playback begins. This
4207				ensures ``composition.data`` is populated before patterns
4208				first build. Implies ``defer=True`` for the repeating
4209				schedule.
4210			defer: If True, skip the pulse-0 fire and defer the first
4211				repeating call to just before the second cycle boundary.
4212
4213		Raises:
4214			RuntimeError: If called after ``play()`` has started — scheduled
4215				tasks register at startup, so a late registration would be
4216				silently ignored otherwise.
4217		"""
4218
4219		if self._sequencer.running:
4220			raise RuntimeError("schedule() must be called before play() - scheduled tasks register at startup")
4221
4222		self._pending_scheduled.append(_PendingScheduled(fn, cycle_beats, reschedule_lookahead, wait_for_initial, defer))
4223
4224	def form (
4225		self,
4226		sections: typing.Union[
4227			"subsequence.forms.Form",
4228			typing.List[typing.Any],
4229			typing.Iterator[typing.Tuple[str, int]],
4230			typing.Dict[str, typing.Tuple[int, typing.Optional[typing.List[typing.Tuple[str, int]]]]]
4231		],
4232		loop: bool = False,
4233		start: typing.Optional[str] = None,
4234		at_end: str = "stop",
4235		key: typing.Optional[str] = None,
4236		scale: typing.Optional[str] = None,
4237	) -> None:
4238
4239		"""
4240		Define the structure (sections) of the composition.
4241
4242		You can define form in four ways:
4243
4244		1. **Form value**: a frozen :class:`~subsequence.forms.Form` of
4245		   :class:`~subsequence.forms.Section` values — the payload home
4246		   (energy, key per section); editable, navigable.
4247		2. **Sequence (List)**: a fixed order of ``(name, bars)`` tuples
4248		   or Sections (lists coerce — they are the same form).
4249		3. **Graph (Dict)**: dynamic transitions based on weights.
4250		4. **Generator**: a Python generator that yields ``(name, bars)`` pairs.
4251
4252		Form-value and list forms are **navigable**: ``form_jump()`` and
4253		``form_next()`` work on them (the jump lands on the next occurrence
4254		of the name, wrapping).
4255
4256		Re-binding ``form()`` during playback takes effect at the next bar —
4257		the clock reads the current form state on every bar, so the new form
4258		advances from there (its first section plays from its first bar).
4259
4260		Parameters:
4261			sections: The form definition (Form, List, Dict, or Generator).
4262			loop: Sugar for ``at_end="loop"``.
4263			start: The section to start with (Graph mode only).
4264			at_end: What happens when a sequence form runs out —
4265				``"stop"`` (the form finishes and patterns see no section;
4266				default), ``"hold"`` (the final section repeats until
4267				navigated away from), or ``"loop"`` (start over).  Graphs
4268				end via their terminal sections instead.
4269			key: A form-level key — the **form tier** of the key-source
4270				chain (``Section.key`` overrides it; it overrides the
4271				composition key).  Re-anchors key-relative content for the
4272				whole form.  When *sections* is a ``Form`` value carrying its
4273				own ``key``, that value is used unless this argument overrides.
4274			scale: A form-level scale/mode, paired with ``key``.
4275
4276		Example:
4277			```python
4278			# A simple pop structure
4279			comp.form([
4280				("verse", 8),
4281				("chorus", 8),
4282				("verse", 8),
4283				("chorus", 16)
4284			])
4285
4286			# The same structure with payloads, held open at the end
4287			S = subsequence.Section
4288			comp.form(subsequence.Form([
4289				S("verse", 8, energy=0.5), S("chorus", 8, energy=0.9),
4290			]), at_end="hold")
4291			```
4292		"""
4293
4294		# Seed FormState at form() time (per-call salt) so build-time walks —
4295		# the frozen clones form_freeze will take — are deterministic without
4296		# play(); the play-time stream is re-dealt name-keyed in _run().
4297		self._form_count += 1
4298
4299		self._form_state = subsequence.form_state.FormState(
4300			sections,
4301			loop = loop,
4302			start = start,
4303			rng = self._stream(f"form:{self._form_count}"),
4304			at_end = at_end,
4305		)
4306
4307		# A Form value carries energy payloads — that counts as an energy
4308		# source for the min_energy registration check in _run().
4309		self._form_has_payload = isinstance(sections, subsequence.forms.Form) or (
4310			isinstance(sections, list) and any(isinstance(element, subsequence.forms.Section) for element in sections)
4311		)
4312
4313		# Form-tier key/scale: an explicit argument wins; otherwise a Form
4314		# value's own key/scale seeds the tier.  Re-binding the form drops any
4315		# stale per-section resolution cache.
4316		if isinstance(sections, subsequence.forms.Form):
4317			self._form_key = key if key is not None else sections.key
4318			self._form_scale = scale if scale is not None else sections.scale
4319		else:
4320			self._form_key = key
4321			self._form_scale = scale
4322
4323		self._resolved_section_cache = {}
4324
4325	def form_freeze (self, sections: typing.Optional[int] = None) -> "subsequence.forms.Form":
4326
4327		"""Freeze the graph form's walk into an editable :class:`~subsequence.forms.Form`.
4328
4329		Walks a **clone** of the live form state — the same RNG state, so the
4330		frozen path is exactly the path the live graph would have played —
4331		and returns it as a Form value: inspect it, edit it
4332		(``path.replace(3, bars=16)``), and rebind it with
4333		``composition.form(path, at_end=...)``.  The live form state is
4334		untouched (rebinding replaces it).
4335
4336		Parameters:
4337			sections: Number of sections to freeze.  Without it, the walk
4338				runs until a terminal section; a graph with no terminal
4339				sections requires ``sections=`` explicitly.
4340
4341		Raises:
4342			ValueError: If no graph form is bound (a list form is already a
4343				frozen sequence), the form has already finished, or the walk
4344				cannot terminate.
4345
4346		Example::
4347
4348			composition.form({...}, start="intro")
4349			path = composition.form_freeze()          # the walk, frozen
4350			composition.form(path, at_end="stop")     # rebind the editable value
4351		"""
4352
4353		fs = self._form_state
4354
4355		if fs is None or fs._graph is None or fs._section_bars is None:
4356			raise ValueError(
4357				"form_freeze() freezes a graph form's walk — call form() with a dict first "
4358				"(a list form is already a frozen sequence)"
4359			)
4360
4361		if fs._current is None:
4362			raise ValueError("the form has already finished — nothing left to freeze")
4363
4364		if sections is not None and sections < 1:
4365			raise ValueError("sections must be at least 1")
4366
4367		if sections is None and not fs._terminal_sections:
4368			raise ValueError(
4369				"this graph has no terminal section, so the walk would never end — "
4370				"pass sections=n to bound it"
4371			)
4372
4373		# Clone the RNG state: the frozen walk reproduces the live form's
4374		# future draws without consuming them.
4375		rng = random.Random()
4376		rng.setstate(fs._rng.getstate())
4377
4378		walked = [fs._current]
4379		next_name = fs._next_section_name		# already decided by the live state
4380
4381		while next_name is not None:
4382			if sections is not None and len(walked) >= sections:
4383				break
4384			if sections is None and len(walked) >= 10000:
4385				raise ValueError(
4386					"form_freeze() walked 10000 sections without reaching a terminal — "
4387					"the terminals look unreachable; pass sections=n to bound the walk"
4388				)
4389
4390			walked.append(subsequence.forms.Section(name = next_name, bars = fs._section_bars[next_name]))
4391			next_name = None if next_name in fs._terminal_sections else fs._graph.choose_next(next_name, rng)
4392
4393		# Carry the form-tier key/scale onto the frozen value so a freeze →
4394		# rebind round-trip is lossless (an explicit form(key=) on rebind
4395		# still overrides).
4396		return subsequence.forms.Form(walked, key = self._form_key, scale = self._form_scale)
4397
4398	def energy (self, energies: typing.Dict[str, typing.Union[float, typing.Tuple[float, float]]]) -> None:
4399
4400		"""Set per-section energy — the arranging dial, as one plain dict.
4401
4402		``{"verse": 0.5, "chorus": 0.9, "build": (0.3, 1.0)}`` — a float is
4403		the section's level; a ``(start, end)`` tuple interpolates across the
4404		section (a build).  Patterns read ``p.energy`` (0.5 when nothing is
4405		configured) and gate themselves, or declare ``min_energy=`` on
4406		``pattern()`` for automatic muting.
4407
4408		The dict **overrides** any energy payload carried by bound
4409		:class:`~subsequence.forms.Section` values — it is the later,
4410		performance-level dial.  Re-calling replaces the whole mapping
4411		(idempotent, live-reload friendly).
4412
4413		Example::
4414
4415			composition.energy({"intro": 0.2, "verse": 0.55, "drop": 0.95})
4416		"""
4417
4418		validated: typing.Dict[str, typing.Union[float, typing.Tuple[float, float]]] = {}
4419
4420		for name, value in energies.items():
4421			if isinstance(value, tuple):
4422				if len(value) != 2:
4423					raise ValueError(f"energy ramp for {name!r} must be (start, end), got {value!r}")
4424				start_level, end_level = float(value[0]), float(value[1])
4425				for level in (start_level, end_level):
4426					if not 0.0 <= level <= 1.0:
4427						raise ValueError(f"energy for {name!r} must be 0.0–1.0, got {value!r}")
4428				validated[name] = (start_level, end_level)
4429			else:
4430				level = float(value)
4431				if not 0.0 <= level <= 1.0:
4432					raise ValueError(f"energy for {name!r} must be 0.0–1.0, got {value!r}")
4433				validated[name] = level
4434
4435		self._energy_map = validated
4436
4437	def _current_energy (self, info: typing.Optional[subsequence.form_state.SectionInfo]) -> float:
4438
4439		"""Resolve the energy for a section snapshot.
4440
4441		Priority: the ``energy()`` dict (ramps interpolate by section
4442		progress) > the bound Section payload > 0.5.
4443		"""
4444
4445		if info is None:
4446			return 0.5
4447
4448		spec = self._energy_map.get(info.name)
4449
4450		if spec is None:
4451			return info.energy
4452
4453		if isinstance(spec, tuple):
4454			start_level, end_level = spec
4455
4456			# A build reaches its declared end ON the final bar, so the ramp spans
4457			# bar 0 → bar (bars-1).  (info.progress is bar/bars, which would top
4458			# out one bar short and never deliver end.)  A one-bar section sits at
4459			# the destination level.
4460			span = info.bars - 1
4461			fraction = info.bar / span if span > 0 else 1.0
4462
4463			return start_level + (end_level - start_level) * fraction
4464
4465		return spec
4466
4467	def on_section (self, callback: typing.Callable[..., typing.Any]) -> None:
4468
4469		"""Register a callback fired on every section change.
4470
4471		The callback receives the new :class:`~subsequence.form_state.SectionInfo`
4472		(or ``None`` when the form finishes).  It fires from the form clock,
4473		one lookahead-beat **early** — in time to affect the new section's
4474		first patterns — and once at play start for the opening section.
4475
4476		Example::
4477
4478			composition.on_section(lambda info: print(f"now: {info.name if info else 'end'}"))
4479		"""
4480
4481		self.on_event("section", callback)
4482
4483	def transition (
4484		self,
4485		before: str,
4486		fill: typing.Optional[typing.Any] = None,
4487		channel: typing.Optional[int] = None,
4488		beat: float = 0.0,
4489		mute: typing.Optional[typing.List[str]] = None,
4490		beats: typing.Optional[float] = None,
4491		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
4492		device: subsequence.midi_utils.DeviceId = None,
4493	) -> None:
4494
4495		"""Declare boundary material — the automatic fill or mute, one line.
4496
4497		``before`` names the incoming section (``"chorus"``), or ``"*"`` for
4498		any *different* section (repeats don't fire it).  Two actions,
4499		combinable:
4500
4501		- ``fill=`` (+ ``channel=``, ``beat=``): a Motif played in the last
4502		  bar before the boundary, starting at ``beat`` of that bar.  Drum
4503		  names resolve through ``drum_note_map=`` if given, otherwise the
4504		  map is borrowed from a registered pattern on the same channel.
4505		- ``mute=`` (+ ``beats=``): pattern names muted over the approach
4506		  and unmuted at the boundary.  Muting is **bar-granular** (the
4507		  existing rule), so ``beats`` rounds up to whole bars.  Performer
4508		  mutes win: a pattern you muted yourself stays muted.
4509
4510		Transitions stack — call once per rule.  Registration is additive
4511		and idempotent per identical rule.
4512
4513		Example::
4514
4515			composition.transition(before="*", fill=FILL, channel=10, beat=2.0)
4516			composition.transition(before="drop", mute=["pads"], beats=4)
4517		"""
4518
4519		if fill is None and mute is None:
4520			raise ValueError("transition() needs fill= and/or mute= — it declares what happens at the boundary")
4521
4522		if fill is not None:
4523			if channel is None:
4524				raise ValueError("transition(fill=) needs channel= — the fill must land somewhere")
4525			if not hasattr(fill, "events") or not hasattr(fill, "length"):
4526				raise TypeError(f"fill must be a Motif-like value with .events/.length, got {type(fill).__name__}")
4527
4528		if mute is not None and beats is None:
4529			beats = float(self.time_signature[0])		# one bar by default
4530
4531		rule = _Transition(
4532			before = before,
4533			fill = fill,
4534			channel = self._resolve_channel(channel) if channel is not None else None,
4535			beat = float(beat),
4536			mute = list(mute) if mute is not None else None,
4537			beats = beats,
4538			drum_note_map = drum_note_map,
4539			device = device,			# resolved at fire time — names aren't known until play()
4540		)
4541
4542		if rule not in self._transitions:
4543			self._transitions.append(rule)
4544
4545	def _transition_drum_map (self, channel: typing.Optional[int]) -> typing.Optional[typing.Dict[str, int]]:
4546
4547		"""Borrow a drum map from a registered pattern on the same channel."""
4548
4549		if channel is None:
4550			return None
4551
4552		for pending in self._pending_patterns:
4553			if pending.channel == channel and pending.drum_note_map:
4554				return pending.drum_note_map
4555
4556		for running in self._running_patterns.values():
4557			candidate = getattr(running, "_drum_note_map", None)
4558			if running.channel == channel and candidate:
4559				return typing.cast(typing.Dict[str, int], candidate)
4560
4561		return None
4562
4563	def _fire_fill (self, rule: _Transition, start_pulse: int) -> None:
4564
4565		"""Build a transition fill as a one-shot pattern and schedule it."""
4566
4567		assert rule.fill is not None and rule.channel is not None
4568
4569		drum_map = rule.drum_note_map if rule.drum_note_map is not None else self._transition_drum_map(rule.channel)
4570
4571		pattern = subsequence.pattern.Pattern(
4572			channel = rule.channel,
4573			length = float(rule.fill.length),
4574			device = self._resolve_device_id(rule.device),
4575		)
4576
4577		harmony_view: typing.Optional[HarmonyView] = None
4578		if not self._harmony_horizon.is_empty:
4579			harmony_view = HarmonyView(self._harmony_horizon, start_pulse / self._sequencer.pulses_per_beat)
4580
4581		# The fill sounds in the outgoing section's final bar, so a degree-
4582		# bearing fill resolves against THAT section's effective key/scale —
4583		# previously it took the composition key, ignoring the section.
4584		fill_section = self._form_state.get_section_info() if self._form_state else None
4585		fill_key, fill_scale = self._effective_key_scale(fill_section)
4586
4587		builder = subsequence.pattern_builder.PatternBuilder(
4588			pattern = pattern,
4589			cycle = 0,
4590			drum_note_map = drum_map,
4591			section = fill_section,
4592			bar = self._builder_bar,
4593			conductor = self.conductor,
4594			rng = self._stream(f"transition:{rule.before}:{start_pulse}") or random.Random(),
4595			tweaks = {},
4596			default_grid = 16,
4597			data = self.data,
4598			key = fill_key,
4599			scale = fill_scale,
4600			time_signature = self.time_signature,
4601			harmony = harmony_view,
4602		)
4603
4604		try:
4605			builder.motif(rule.fill)
4606		except Exception:
4607			logger.exception("transition fill failed to build — the boundary plays without it")
4608			return
4609
4610		self._schedule_one_shot(pattern, start_pulse)
4611
4612	def _check_transitions (self, boundary_pulse: int, section_changed: bool) -> None:
4613
4614		"""The form clock's boundary hook: fire fills, manage approach mutes.
4615
4616		Called once per bar (lookahead-early, with the bar-line pulse).
4617		Fill rules fire when the current bar is the section's last before a
4618		matching boundary; mute rules close over the approach window
4619		(rounded up to whole bars — muting is bar-granular) and reopen at
4620		the boundary.  Performer mutes are never touched.
4621		"""
4622
4623		if section_changed and self._transition_muted:
4624			# The boundary arrived — restore only what we muted ourselves.
4625			for name in self._transition_muted:
4626				running = self._running_patterns.get(name)
4627				if running is not None:
4628					running._muted = False
4629			self._transition_muted.clear()
4630
4631		if not self._transitions or self._form_state is None:
4632			return
4633
4634		info = self._form_state.get_section_info()
4635
4636		if info is None or info.next_section is None:
4637			return
4638
4639		bar_beats = float(self.time_signature[0])
4640		bars_remaining = info.bars - info.bar
4641
4642		for rule in self._transitions:
4643
4644			if rule.before == "*":
4645				if info.next_section == info.name:
4646					continue		# a repeat is not a boundary
4647			elif info.next_section != rule.before:
4648				continue
4649
4650			if rule.fill is not None and bars_remaining == 1:
4651				self._fire_fill(rule, boundary_pulse + int(round(rule.beat * self._sequencer.pulses_per_beat)))
4652
4653			if rule.mute:
4654				window_beats = rule.beats if rule.beats is not None else bar_beats
4655				window_bars = max(1, int((window_beats + bar_beats - 1e-9) // bar_beats))
4656
4657				if bars_remaining <= window_bars:
4658					for name in rule.mute:
4659						running = self._running_patterns.get(name)
4660						if running is None or name in self._transition_muted:
4661							continue
4662						if running._muted:
4663							continue		# the performer's mute — not ours to manage
4664						running._muted = True
4665						self._transition_muted.add(name)
4666
4667	@staticmethod
4668	def _resolve_length (
4669		beats: typing.Optional[float],
4670		bars: typing.Optional[float],
4671		steps: typing.Optional[float],
4672		step_duration: typing.Optional[float],
4673		default: float = 4.0,
4674		beats_per_bar: int = 4,
4675	) -> typing.Tuple[float, int]:
4676
4677		"""
4678		Resolve the beat_length and default_grid from the duration parameters.
4679
4680		Two modes:
4681
4682		- **Duration mode** (no ``step_duration``): specify ``beats=`` or ``bars=``.
4683		  ``beats=4`` = 4 quarter notes; ``bars=2`` = 8 beats.
4684		- **Step mode** (with ``step_duration``): specify ``steps=`` and ``step_duration=``.
4685		  ``steps=6, step_duration=dur.SIXTEENTH`` = 6 sixteenth notes = 1.5 beats.
4686
4687		Constraints:
4688
4689		- ``beats`` and ``bars`` are mutually exclusive.
4690		- ``steps`` requires ``step_duration``; ``step_duration`` requires ``steps``.
4691		- ``steps`` cannot be combined with ``beats`` or ``bars``.
4692
4693		Returns:
4694			(beat_length, default_grid) — beat_length in beats (quarter notes);
4695			default_grid the number of grid steps (16th-notes in beat mode, or the
4696			explicit ``steps`` value directly in step mode).
4697		"""
4698
4699		if beats is not None and bars is not None:
4700			raise ValueError("Specify only one of beats= or bars=")
4701
4702		if steps is not None and (beats is not None or bars is not None):
4703			raise ValueError("steps= cannot be combined with beats= or bars=")
4704
4705		if step_duration is not None and steps is None:
4706			raise ValueError("step_duration= requires steps= (e.g. steps=6, step_duration=dur.SIXTEENTH)")
4707
4708		if steps is not None:
4709			if step_duration is None:
4710				raise ValueError("steps= requires step_duration= (e.g. step_duration=dur.SIXTEENTH)")
4711			return steps * step_duration, int(steps)
4712
4713		if bars is not None:
4714			raw = bars * beats_per_bar
4715		elif beats is not None:
4716			raw = beats
4717		else:
4718			raw = default
4719
4720		return raw, round(raw / subsequence.constants.durations.SIXTEENTH)
4721
4722	def pattern (
4723		self,
4724		channel: int,
4725		beats: typing.Optional[float] = None,
4726		bars: typing.Optional[float] = None,
4727		steps: typing.Optional[float] = None,
4728		step_duration: typing.Optional[float] = None,
4729		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
4730		cc_name_map: typing.Optional[typing.Dict[str, int]] = None,
4731		nrpn_name_map: typing.Optional[typing.Dict[str, int]] = None,
4732		reschedule_lookahead: float = 1,
4733		voice_leading: bool = False,
4734		device: subsequence.midi_utils.DeviceId = None,
4735		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
4736		min_energy: typing.Optional[float] = None,
4737	) -> typing.Callable:
4738
4739		"""
4740		Register a function as a repeating MIDI pattern.
4741
4742		The decorated function will be called once per cycle to 'rebuild' its
4743		content. This allows for generative logic that evolves over time.
4744
4745		Two ways to specify pattern length:
4746
4747		- **Duration mode** (default): use ``beats=`` or ``bars=``.
4748		  The grid defaults to sixteenth-note resolution.
4749		- **Step mode**: use ``steps=`` paired with ``step_duration=``.
4750		  The grid equals the step count, so ``p.hit_steps()`` indices map
4751		  directly to steps.
4752
4753		Parameters:
4754			channel: MIDI channel. By default uses 1-based numbering (1-16).
4755				Set ``zero_indexed_channels=True`` on the ``Composition`` to use
4756				0-based numbering (0-15), matching the raw MIDI protocol, instead.
4757			beats: Duration in beats (quarter notes). ``beats=4`` = 1 bar.
4758			bars: Duration in bars (uses the composition's time signature — 4 beats each in 4/4). ``bars=2`` = 8 beats.
4759			steps: Step count for step mode. Requires ``step_duration=``.
4760			step_duration: Duration of one step in beats (e.g. ``dur.SIXTEENTH``).
4761				Requires ``steps=``.
4762			drum_note_map: Optional mapping for drum instruments.
4763			cc_name_map: Optional mapping of CC names to MIDI CC numbers.
4764				Enables string-based CC names in ``p.cc()`` and ``p.cc_ramp()``.
4765			nrpn_name_map: Optional mapping of NRPN parameter names (strings) to
4766				14-bit parameter numbers (0–16383).  Enables string-based names
4767				in ``p.nrpn()`` and ``p.nrpn_ramp()`` — typically a
4768				device-specific dictionary (e.g. Sequential Take 5's
4769				``Osc1FreqFine`` → 9).
4770			reschedule_lookahead: Beats in advance to compute the next cycle.
4771			voice_leading: If True, chords in this pattern will automatically
4772				use inversions that minimize voice movement.
4773			mirrors: Optional list of additional ``(device, channel)`` destinations
4774				to duplicate every event from this pattern onto.  Notes, CCs, pitch
4775				bend, NRPN/RPN bursts, program changes, SysEx, and drone events are
4776				all mirrored; OSC events are not (OSC is not bound to a MIDI port).
4777				``device`` is the integer index returned by ``midi_output()`` (0 =
4778				primary).  ``channel`` follows this composition's channel-numbering
4779				convention.  See also ``mirror()`` / ``unmirror()`` for live toggling.
4780			min_energy: Automatic energy gating — the pattern is silent while
4781				the current section's energy (``composition.energy()`` dict,
4782				or the bound Section payload) is below this threshold.
4783				Composes with ``mute()``: a performer mute always wins.
4784
4785		Example:
4786			```python
4787			@comp.pattern(channel=1, beats=4)
4788			def chords (p):
4789				p.chord([60, 64, 67], beat=0, velocity=80, duration=3.9)
4790
4791			@comp.pattern(channel=1, bars=2)
4792			def long_phrase (p):
4793				...
4794
4795			@comp.pattern(channel=1, steps=6, step_duration=dur.SIXTEENTH)
4796			def riff (p):
4797				p.sequence(steps=[0, 1, 3, 5], pitches=60)
4798			```
4799		"""
4800
4801		channel = self._resolve_channel(channel)
4802
4803		beat_length, default_grid = self._resolve_length(beats, bars, steps, step_duration, beats_per_bar=self.time_signature[0])
4804
4805		# Resolve device string name to index if possible now; otherwise store
4806		# the raw DeviceId and resolve it in _run() once all devices are open.
4807		resolved_device: subsequence.midi_utils.DeviceId = device
4808
4809		# Mirror-to-self check is only reliable when the primary device is a
4810		# concrete integer at decoration time.  ``None`` resolves to device 0
4811		# downstream, so we treat it as 0 here too.  Strings are deferred to
4812		# ``_run()`` and we skip the check for them.
4813		primary: typing.Optional[typing.Tuple[int, int]]
4814		if isinstance(resolved_device, str):
4815			primary = None
4816		else:
4817			primary = (resolved_device if resolved_device is not None else 0, channel)
4818		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
4819
4820		def decorator (fn: typing.Callable) -> typing.Callable:
4821
4822			"""
4823			Wrap the builder function and register it as a pending pattern.
4824			During live sessions, hot-swap an existing pattern's builder instead.
4825			"""
4826
4827			# Record this declaration so the live-reload deletion diff knows the
4828			# pattern is still present in the source (see _apply_source_async).
4829			self._declared_names.add(fn.__name__)
4830
4831			# Hot-swap: if we're live and a pattern with this name exists, replace its builder.
4832			if self._is_live and fn.__name__ in self._running_patterns:
4833				running = self._running_patterns[fn.__name__]
4834				running._builder_fn = fn
4835				running._wants_chord = _fn_has_parameter(fn, "chord")
4836				logger.info(f"Hot-swapped pattern: {fn.__name__}")
4837				return fn
4838
4839			# Names key the seeded stream, mutes, tweaks, and reroll/lock — a
4840			# duplicate means two scheduled copies sharing one stream with
4841			# only one reachable by name.  Warn loudly at registration.
4842			if any(existing.builder_fn.__name__ == fn.__name__ for existing in self._pending_patterns):
4843				logger.warning(
4844					f"Duplicate pattern name '{fn.__name__}': both copies will be "
4845					f"scheduled, they share one seeded stream, and only one is "
4846					f"reachable by name — rename one of them."
4847				)
4848
4849			pending = _PendingPattern(
4850				builder_fn = fn,
4851				channel = channel,  # already resolved to 0-indexed
4852				length = beat_length,
4853				default_grid = default_grid,
4854				drum_note_map = drum_note_map,
4855				cc_name_map = cc_name_map,
4856				nrpn_name_map = nrpn_name_map,
4857				reschedule_lookahead = reschedule_lookahead,
4858				voice_leading = voice_leading,
4859				# For int/None: resolve immediately.  For str: store 0 as
4860				# placeholder; _resolve_pending_devices() fixes it in _run().
4861				device = 0 if (resolved_device is None or isinstance(resolved_device, str)) else resolved_device,
4862				raw_device = resolved_device,
4863				mirrors = resolved_mirrors,
4864				min_energy = min_energy,
4865			)
4866
4867			self._pending_patterns.append(pending)
4868
4869			return fn
4870
4871		return decorator
4872
4873	def layer (
4874		self,
4875		*builder_fns: typing.Callable,
4876		channel: int,
4877		beats: typing.Optional[float] = None,
4878		bars: typing.Optional[float] = None,
4879		steps: typing.Optional[float] = None,
4880		step_duration: typing.Optional[float] = None,
4881		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
4882		cc_name_map: typing.Optional[typing.Dict[str, int]] = None,
4883		nrpn_name_map: typing.Optional[typing.Dict[str, int]] = None,
4884		reschedule_lookahead: float = 1,
4885		voice_leading: bool = False,
4886		device: subsequence.midi_utils.DeviceId = None,
4887		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
4888	) -> None:
4889
4890		"""
4891		Combine multiple functions into a single MIDI pattern.
4892
4893		This is useful for composing complex patterns out of reusable
4894		building blocks (e.g., a 'kick' function and a 'snare' function).
4895
4896		See ``pattern()`` for the full description of ``beats``, ``bars``,
4897		``steps``, and ``step_duration``.
4898
4899		Parameters:
4900			builder_fns: One or more pattern builder functions.
4901			channel: MIDI channel (1-16, or 0-15 with ``zero_indexed_channels=True``).
4902			beats: Duration in beats (quarter notes).
4903			bars: Duration in bars (uses the composition's time signature — 4 beats each in 4/4).
4904			steps: Step count for step mode. Requires ``step_duration=``.
4905			step_duration: Duration of one step in beats. Requires ``steps=``.
4906			drum_note_map: Optional mapping for drum instruments.
4907			cc_name_map: Optional mapping of CC names to MIDI CC numbers.
4908			nrpn_name_map: Optional mapping of NRPN parameter names to 14-bit
4909				parameter numbers.
4910			reschedule_lookahead: Beats in advance to compute the next cycle.
4911			voice_leading: If True, chords use smooth voice leading.
4912			mirrors: Optional list of additional ``(device, channel)`` destinations
4913				to duplicate every event onto.  See ``pattern()`` for details.
4914		"""
4915
4916		beat_length, default_grid = self._resolve_length(beats, bars, steps, step_duration, beats_per_bar=self.time_signature[0])
4917
4918		# Resolve channel up-front so the mirror-to-self check has the canonical
4919		# primary form to compare against.
4920		resolved_channel = self._resolve_channel(channel)
4921
4922		# See pattern() for the same comment about None / str handling.
4923		primary: typing.Optional[typing.Tuple[int, int]]
4924		if isinstance(device, str):
4925			primary = None
4926		else:
4927			primary = (device if device is not None else 0, resolved_channel)
4928		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
4929
4930		wants_chord = any(_fn_has_parameter(fn, "chord") for fn in builder_fns)
4931
4932		if wants_chord:
4933
4934			def merged_builder (p: subsequence.pattern_builder.PatternBuilder, chord: _InjectedChord) -> None:
4935
4936				for fn in builder_fns:
4937					if _fn_has_parameter(fn, "chord"):
4938						fn(p, chord)
4939					else:
4940						fn(p)
4941
4942		else:
4943
4944			def merged_builder (p: subsequence.pattern_builder.PatternBuilder) -> None:  # type: ignore[misc]
4945
4946				for fn in builder_fns:
4947					fn(p)
4948
4949		# Give the merged builder a stable, unique name derived from its
4950		# components so multiple layer() calls don't all register under
4951		# "merged_builder" and collide in _running_patterns (which made
4952		# mute/tweak/unregister/live_info reach only the LAST layer).  "+" can't
4953		# appear in a Python identifier, so this never clashes with a real
4954		# pattern function's name.
4955		base_name = ("+".join(fn.__name__ for fn in builder_fns) or "layer") + f"@ch{resolved_channel}"
4956		merged_name = base_name
4957		suffix = 2
4958
4959		# Two layers with the same components (e.g. on different saves of a
4960		# live file) must map to the same names pass-over-pass, while two
4961		# DIFFERENT layers sharing components in one pass must not collide.
4962		while merged_name in self._declared_names:
4963			merged_name = f"{base_name}#{suffix}"
4964			suffix += 1
4965
4966		merged_builder.__name__ = merged_name
4967
4968		# Record the declaration for the live-reload deletion diff, and hot-swap
4969		# in place when this layer is already running so a reload picks up edits
4970		# to the component functions without losing the pattern's cycle count,
4971		# tweaks, or mirrors (mirrors the pattern() decorator's hot-swap).
4972		self._declared_names.add(merged_builder.__name__)
4973
4974		if self._is_live and merged_builder.__name__ in self._running_patterns:
4975			running = self._running_patterns[merged_builder.__name__]
4976			running._builder_fn = merged_builder
4977			running._wants_chord = wants_chord
4978			logger.info(f"Hot-swapped layer: {merged_builder.__name__}")
4979			return
4980
4981		pending = _PendingPattern(
4982			builder_fn = merged_builder,
4983			channel = resolved_channel,  # already resolved to 0-indexed above
4984			length = beat_length,
4985			default_grid = default_grid,
4986			drum_note_map = drum_note_map,
4987			cc_name_map = cc_name_map,
4988			nrpn_name_map = nrpn_name_map,
4989			reschedule_lookahead = reschedule_lookahead,
4990			voice_leading = voice_leading,
4991			mirrors = resolved_mirrors,
4992			device = 0 if (device is None or isinstance(device, str)) else device,
4993			raw_device = device,
4994		)
4995
4996		self._pending_patterns.append(pending)
4997
4998	def chords (
4999		self,
5000		*,
5001		channel: int,
5002		progression: subsequence.progressions.ProgressionSource,
5003		harmonic_rhythm: subsequence.progressions.HarmonicRhythmSpec,
5004		bars: typing.Optional[float] = None,
5005		beats: typing.Optional[float] = None,
5006		voicing: subsequence.progressions.VoicingSpec = (3, 4),
5007		velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_CHORD_VELOCITY,
5008		detached: typing.Optional[float] = None,
5009		root: int = 60,
5010		key: typing.Optional[str] = None,
5011		seed: typing.Optional[int] = None,
5012		device: subsequence.midi_utils.DeviceId = None,
5013		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
5014	) -> subsequence.progressions.Progression:
5015
5016		"""Declare a self-contained chord part: a progression at a chosen harmonic rhythm.
5017
5018		The one-call form of ``p.progression()`` — it registers a pattern on
5019		*channel* that plays *progression* across *bars* (or *beats*), each chord
5020		lasting a length drawn from *harmonic_rhythm* (the musical term for how often
5021		the chords change).  It needs no ``composition.harmony()`` call and, with an
5022		explicit chord list or a ``key=``, no composition key either — so a
5023		drums-plus-one-chord-part sketch stays simple.
5024
5025		The progression is realised once, up front, and the same timeline plays every
5026		cycle (a stable phrase).  That timeline is returned so you can see exactly what
5027		was chosen — ``print(comp.chords(...))``.
5028
5029		Parameters:
5030			channel: MIDI channel for the chord part.
5031			progression: A chord-graph style name to generate from, or an explicit list
5032				of chords (``Chord`` objects or names like ``["Cm7", "Dbmaj7"]``).
5033			harmonic_rhythm: How long each chord lasts — a number, a list of lengths,
5034				or ``between(low, high, step=...)``.  See ``p.progression()``.
5035			bars / beats: Length of the part (defaults to 4 beats if neither is given).  ``bars`` uses the
5036				composition's time signature.
5037			voicing: Notes per chord — an int, or a ``(low, high)`` range (e.g. ``(3, 4)``).
5038			velocity: MIDI velocity, or a ``(low, high)`` tuple for per-voice humanisation.
5039			detached: Beats of silence before each next chord (``duration = length - detached``).
5040			root: MIDI root the voicings are centred on (e.g. 48 = C3).
5041			key: Key for a generated progression; defaults to the composition key.
5042			seed: Seed for the (otherwise fixed) realisation; defaults to the
5043				composition seed, so the part is reproducible.
5044			device: Optional output-device override.
5045			mirrors: Optional additional ``(device, channel)`` destinations.
5046
5047		Returns:
5048			The realised :class:`~subsequence.progressions.Progression`.
5049		"""
5050
5051		beat_length, default_grid = self._resolve_length(beats, bars, None, None, beats_per_bar=self.time_signature[0])
5052		resolved_channel = self._resolve_channel(channel)
5053		resolved_key = key if key is not None else self.key
5054
5055		rng = random.Random(seed if seed is not None else self._seed)
5056		timeline = subsequence.progressions.realize(
5057			source = progression,
5058			harmonic_rhythm = harmonic_rhythm,
5059			key = resolved_key,
5060			length = beat_length,
5061			rng = rng,
5062			scale = self.scale or "ionian",
5063		)
5064
5065		captured_root = root
5066		captured_velocity = velocity
5067		captured_detached = detached
5068		captured_voicing = voicing
5069
5070		def chords_builder (p: subsequence.pattern_builder.PatternBuilder) -> None:
5071
5072			"""Replay the realised timeline as block chords each cycle (voicing per chord)."""
5073
5074			for chord, start, length in timeline:
5075				ring = length - captured_detached if (captured_detached and captured_detached < length) else length
5076				voices = subsequence.progressions.resolve_voices(captured_voicing, p.rng)
5077				p.chord(chord, root=captured_root, beat=start, duration=ring, count=voices, velocity=captured_velocity)
5078
5079		# Unique, stable name so multiple chord parts don't collide in
5080		# _running_patterns — including two parts on the SAME channel, which
5081		# get a deterministic #2/#3 suffix in declaration order.
5082		base_name = f"chords@ch{resolved_channel}"
5083		chords_name = base_name
5084		suffix = 2
5085
5086		while chords_name in self._declared_names:
5087			chords_name = f"{base_name}#{suffix}"
5088			suffix += 1
5089
5090		chords_builder.__name__ = chords_name
5091		self._declared_names.add(chords_name)
5092
5093		primary: typing.Optional[typing.Tuple[int, int]]
5094		if isinstance(device, str):
5095			primary = None
5096		else:
5097			primary = (device if device is not None else 0, resolved_channel)
5098		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
5099
5100		if self._is_live and chords_builder.__name__ in self._running_patterns:
5101			running = self._running_patterns[chords_builder.__name__]
5102			running._builder_fn = chords_builder
5103			running._wants_chord = False
5104			logger.info(f"Hot-swapped chords: {chords_builder.__name__}")
5105			return timeline
5106
5107		pending = _PendingPattern(
5108			builder_fn = chords_builder,
5109			channel = resolved_channel,
5110			length = beat_length,
5111			default_grid = default_grid,
5112			drum_note_map = None,
5113			reschedule_lookahead = 1,
5114			voice_leading = False,
5115			mirrors = resolved_mirrors,
5116			device = 0 if (device is None or isinstance(device, str)) else device,
5117			raw_device = device,
5118		)
5119		self._pending_patterns.append(pending)
5120		return timeline
5121
5122	def phrase_part (
5123		self,
5124		*,
5125		channel: int,
5126		part: typing.Optional[str] = None,
5127		root: int = 60,
5128		bars: typing.Optional[float] = None,
5129		beats: typing.Optional[float] = None,
5130		velocity: typing.Optional[typing.Union[int, typing.Tuple[int, int]]] = None,
5131		fit: typing.Optional[float] = None,
5132		device: subsequence.midi_utils.DeviceId = None,
5133		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
5134	) -> None:
5135
5136		"""Declare a part that plays each section's bound Motif/Phrase.
5137
5138		The one-call consumer for :meth:`section_motifs` — it registers a
5139		pattern on *channel* that walks whatever value is bound to the
5140		current section for *part* (stateless position from the cycle
5141		counter, via ``p.phrase()``).  A section with no binding for the
5142		part is **silent** for that part — bind material or don't; no
5143		fallback guessing.
5144
5145		Parameters:
5146			channel: MIDI channel for the part.
5147			part: The part label to read from the registry (``None`` = the
5148				unlabelled binding).
5149			root: Register anchor for degree resolution.
5150			bars / beats: Cycle length of the part (defaults to 4 beats);
5151				the phrase is sliced one cycle window at a time.
5152			velocity: Optional override applied to every note.
5153			fit: Passed through (active with the melody engine stage).
5154			device: Optional output-device override.
5155			mirrors: Optional additional ``(device, channel)`` destinations.
5156
5157		Example::
5158
5159			composition.section_motifs("verse",  verse_line,  part="lead")
5160			composition.section_motifs("chorus", chorus_line, part="lead")
5161			composition.phrase_part(channel=4, part="lead", root=72, bars=2)
5162		"""
5163
5164		beat_length, default_grid = self._resolve_length(beats, bars, None, None, beats_per_bar=self.time_signature[0])
5165		resolved_channel = self._resolve_channel(channel)
5166
5167		captured_part = part
5168		captured_root = root
5169		captured_velocity = velocity
5170		captured_fit = fit
5171
5172		def phrase_builder (p: subsequence.pattern_builder.PatternBuilder) -> None:
5173
5174			"""Walk the current section's bound value (silent when unbound)."""
5175
5176			value = p.section_motif(captured_part)
5177
5178			if value is None:
5179				return	# unbound section: silence for this part, by design
5180
5181			p.phrase(value, root=captured_root, velocity=captured_velocity, fit=captured_fit)
5182
5183		# Unique, stable name so multiple phrase parts don't collide —
5184		# including two parts on the SAME channel (deterministic #2/#3
5185		# suffixes in declaration order, the chords() convention).
5186		base_name = f"phrase@{captured_part}@ch{resolved_channel}" if captured_part else f"phrase@ch{resolved_channel}"
5187		phrase_name = base_name
5188		suffix = 2
5189
5190		while phrase_name in self._declared_names:
5191			phrase_name = f"{base_name}#{suffix}"
5192			suffix += 1
5193
5194		phrase_builder.__name__ = phrase_name
5195		self._declared_names.add(phrase_name)
5196
5197		primary: typing.Optional[typing.Tuple[int, int]]
5198		if isinstance(device, str):
5199			primary = None
5200		else:
5201			primary = (device if device is not None else 0, resolved_channel)
5202		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
5203
5204		if self._is_live and phrase_builder.__name__ in self._running_patterns:
5205			running = self._running_patterns[phrase_builder.__name__]
5206			running._builder_fn = phrase_builder
5207			running._wants_chord = False
5208			logger.info(f"Hot-swapped phrase part: {phrase_builder.__name__}")
5209			return
5210
5211		pending = _PendingPattern(
5212			builder_fn = phrase_builder,
5213			channel = resolved_channel,
5214			length = beat_length,
5215			default_grid = default_grid,
5216			drum_note_map = None,
5217			reschedule_lookahead = 1,
5218			voice_leading = False,
5219			mirrors = resolved_mirrors,
5220			device = 0 if (device is None or isinstance(device, str)) else device,
5221			raw_device = device,
5222		)
5223		self._pending_patterns.append(pending)
5224
5225	def trigger (
5226		self,
5227		fn: typing.Callable,
5228		channel: int,
5229		beats: typing.Optional[float] = None,
5230		bars: typing.Optional[float] = None,
5231		steps: typing.Optional[float] = None,
5232		step_duration: typing.Optional[float] = None,
5233		quantize: float = 0,
5234		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
5235		cc_name_map: typing.Optional[typing.Dict[str, int]] = None,
5236		nrpn_name_map: typing.Optional[typing.Dict[str, int]] = None,
5237		chord: bool = False,
5238		device: subsequence.midi_utils.DeviceId = None,
5239		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
5240	) -> None:
5241
5242		"""
5243		Trigger a one-shot pattern immediately or on a quantized boundary.
5244
5245		This is useful for real-time response to sensors, OSC messages, or other
5246		external events. The builder function is called immediately with a fresh
5247		PatternBuilder, and the generated events are injected into the queue at
5248		the specified quantize boundary.
5249
5250		The builder function has the same API as a ``@composition.pattern``
5251		decorated function and can use all PatternBuilder methods: ``p.note()``,
5252		``p.euclidean()``, ``p.arpeggio()``, and so on.
5253
5254		See ``pattern()`` for the full description of ``beats``, ``bars``,
5255		``steps``, and ``step_duration``. Default is 1 beat.
5256
5257		Parameters:
5258			fn: The pattern builder function (same signature as ``@comp.pattern``).
5259			channel: MIDI channel (1-16, or 0-15 with ``zero_indexed_channels=True``).
5260			beats: Duration in beats (quarter notes, default 1).
5261			bars: Duration in bars (uses the composition's time signature — 4 beats each in 4/4).
5262			steps: Step count for step mode. Requires ``step_duration=``.
5263			step_duration: Duration of one step in beats. Requires ``steps=``.
5264			quantize: Snap the trigger to a beat boundary: ``0`` = immediate (default),
5265				``1`` = next beat (quarter note), ``4`` = next bar. Use ``dur.*``
5266				constants from ``subsequence.constants.durations``.
5267			drum_note_map: Optional drum name mapping for this pattern.
5268			cc_name_map: Optional mapping of CC names to MIDI CC numbers.
5269			nrpn_name_map: Optional mapping of NRPN parameter names to
5270				14-bit parameter numbers.
5271			chord: If ``True``, the builder function receives the current chord as
5272				a second parameter (same as ``@composition.pattern``).
5273			mirrors: Optional list of additional ``(device, channel)`` destinations
5274				to fire this one-shot onto in parallel with the primary destination.
5275
5276		Example:
5277			```python
5278			# Immediate single note (channels are 1-16 by default)
5279			composition.trigger(
5280				lambda p: p.note(60, beat=0, velocity=100, duration=0.5),
5281				channel=1
5282			)
5283
5284			# Quantized fill (next bar) — channel 10 is the GM drum channel
5285			import subsequence.constants.durations as dur
5286			composition.trigger(
5287				lambda p: p.euclidean("snare", pulses=7, velocity=90),
5288				channel=10,
5289				drum_note_map=gm_drums.GM_DRUM_MAP,
5290				quantize=dur.WHOLE
5291			)
5292
5293			# With chord context — the builder receives the chord as a second
5294			# argument when chord=True.
5295			composition.trigger(
5296				lambda p, chord: p.arpeggio(chord.tones(root=60), spacing=dur.SIXTEENTH),
5297				channel=1,
5298				quantize=dur.QUARTER,
5299				chord=True
5300			)
5301			```
5302		"""
5303
5304		# Resolve channel numbering
5305		resolved_channel = self._resolve_channel(channel)
5306
5307		beat_length, default_grid = self._resolve_length(beats, bars, steps, step_duration, default=1.0, beats_per_bar=self.time_signature[0])
5308
5309		# Resolve device index — for trigger() this is always concrete by call time,
5310		# so the mirror-to-self check has the full primary tuple available.
5311		resolved_device_idx = self._resolve_device_id(device)
5312		resolved_mirrors = self._resolve_mirrors(mirrors, primary=(resolved_device_idx, resolved_channel))
5313
5314		# Create a temporary Pattern
5315		pattern = subsequence.pattern.Pattern(channel=resolved_channel, length=beat_length, device=resolved_device_idx, mirrors=resolved_mirrors)
5316
5317		# Resolve the section context once: the one-shot inherits the section's
5318		# effective key/scale (so a triggered degree resolves like everywhere
5319		# else) and a harmony view at the current playhead (so ChordTone /
5320		# Approach resolve too).
5321		trigger_section = self._form_state.get_section_info() if self._form_state else None
5322		trigger_key, trigger_scale = self._effective_key_scale(trigger_section)
5323
5324		trigger_harmony: typing.Optional[HarmonyView] = None
5325		if not self._harmony_horizon.is_empty:
5326			trigger_harmony = HarmonyView(self._harmony_horizon, self._sequencer.pulse_count / self._sequencer.pulses_per_beat)
5327
5328		# Create a PatternBuilder
5329		builder = subsequence.pattern_builder.PatternBuilder(
5330			pattern=pattern,
5331			cycle=0,  # One-shot patterns don't rebuild, so cycle is always 0
5332			drum_note_map=drum_note_map,
5333			cc_name_map=cc_name_map,
5334			nrpn_name_map=nrpn_name_map,
5335			section=trigger_section,
5336			bar=self._builder_bar,
5337			conductor=self.conductor,
5338			rng=random.Random(),  # Fresh random state for each trigger
5339			tweaks={},
5340			default_grid=default_grid,
5341			data=self.data,
5342			# A one-shot resolves key-relative content against the same
5343			# effective key/scale as the section it fires into (previously
5344			# omitted entirely — degrees raised even in a keyed composition).
5345			key=trigger_key,
5346			scale=trigger_scale,
5347			time_signature=self.time_signature,
5348			held_notes=self._sequencer._held_notes,
5349			harmony=trigger_harmony,
5350			energy=self._current_energy(trigger_section)
5351		)
5352
5353		# Call the builder function
5354		try:
5355
5356			current_chord = self.current_chord() if chord else None
5357
5358			if current_chord is not None:
5359				injected = _InjectedChord(current_chord, None)  # No voice leading for one-shots
5360				fn(builder, injected)
5361
5362			else:
5363				fn(builder)
5364
5365		except Exception:
5366			logger.exception("Error in trigger builder — pattern will be silent")
5367			return
5368
5369		# Calculate the start pulse based on quantize
5370		current_pulse = self._sequencer.pulse_count
5371		pulses_per_beat = subsequence.constants.MIDI_QUARTER_NOTE
5372
5373		if quantize == 0:
5374			# Immediate: use current pulse
5375			start_pulse = current_pulse
5376
5377		else:
5378			# Quantize to the next multiple of (quantize * pulses_per_beat)
5379			quantize_pulses = int(quantize * pulses_per_beat)
5380			start_pulse = ((current_pulse // quantize_pulses) + 1) * quantize_pulses
5381
5382		self._schedule_one_shot(pattern, start_pulse)
5383
5384	def _schedule_one_shot (self, pattern: subsequence.pattern.Pattern, start_pulse: int) -> None:
5385
5386		"""Schedule a one-shot pattern at an absolute pulse, thread-safely."""
5387
5388		try:
5389			# Probe only: raises RuntimeError when not on the event loop.
5390			asyncio.get_running_loop()
5391			asyncio.create_task(self._sequencer.schedule_pattern(pattern, start_pulse))
5392
5393		except RuntimeError:
5394			# Not on the event loop — hand the coroutine to the loop thread.
5395			if self._sequencer._event_loop is not None:
5396				asyncio.run_coroutine_threadsafe(
5397					self._sequencer.schedule_pattern(pattern, start_pulse),
5398					loop=self._sequencer._event_loop
5399				)
5400			else:
5401				logger.warning("trigger() called before playback started; pattern ignored")
5402
5403	@property
5404	def is_clock_following (self) -> bool:
5405
5406		"""True if either the primary or any additional device is following external clock."""
5407
5408		return self._clock_follow or any(cf for _, _, cf in self._additional_inputs)
5409
5410
5411	def play (self) -> None:
5412
5413		"""
5414		Start the composition.
5415
5416		This call blocks until the program is interrupted (e.g., via Ctrl+C).
5417		It initializes the MIDI hardware, launches the background sequencer,
5418		and begins playback.
5419		"""
5420
5421		try:
5422			asyncio.run(self._run())
5423
5424		except KeyboardInterrupt:
5425			pass
5426
5427
5428	def render (self, bars: typing.Optional[int] = None, filename: str = "render.mid", max_minutes: typing.Optional[float] = 60.0) -> None:
5429
5430		"""Render the composition to a MIDI file without real-time playback.
5431
5432		Runs the sequencer as fast as possible (no timing delays) and stops
5433		when the first active limit is reached.  The result is saved as a
5434		standard MIDI file that can be imported into any DAW.
5435
5436		All patterns, scheduled callbacks, and harmony logic run exactly as
5437		they would during live playback — BPM transitions, generative fills,
5438		and probabilistic gates all work in render mode.  The only difference
5439		is that time is simulated rather than wall-clock driven.
5440
5441		Parameters:
5442			bars: Number of bars to render, or ``None`` for no bar limit
5443			      (default ``None``).  When both *bars* and *max_minutes* are
5444			      active, playback stops at whichever limit is reached first.
5445			filename: Output MIDI filename (default ``"render.mid"``).
5446			max_minutes: Safety cap on the length of rendered MIDI in minutes
5447			             (default ``60.0``).  Pass ``None`` to disable the time
5448			             cap — you must then provide an explicit *bars* value.
5449
5450		Raises:
5451			ValueError: If both *bars* and *max_minutes* are ``None``, which
5452			            would produce an infinite render.
5453
5454		Examples:
5455			```python
5456			# Default: renders up to 60 minutes of MIDI content.
5457			composition.render()
5458
5459			# Render exactly 64 bars (time cap still active as backstop).
5460			composition.render(bars=64, filename="demo.mid")
5461
5462			# Render up to 5 minutes of an infinite generative composition.
5463			composition.render(max_minutes=5, filename="five_min.mid")
5464
5465			# Remove the time cap — must supply bars instead.
5466			composition.render(bars=128, max_minutes=None, filename="long.mid")
5467			```
5468		"""
5469
5470		if bars is None and max_minutes is None:
5471			raise ValueError(
5472				"render() requires at least one limit: provide bars=, max_minutes=, or both. "
5473				"Passing both as None would produce an infinite render."
5474			)
5475
5476		self._sequencer.recording = True
5477		self._sequencer.record_filename = filename
5478		self._sequencer.render_mode = True
5479		self._sequencer.render_bars = bars if bars is not None else 0
5480		self._sequencer.render_max_seconds = max_minutes * 60.0 if max_minutes is not None else None
5481		asyncio.run(self._run())
5482
5483	def _broadcast_osc_status (self, bar: int) -> None:
5484
5485		"""
5486		Send the per-bar OSC status snapshot: bar number, current tempo,
5487		and (when active) the current chord name and form section.
5488		"""
5489
5490		if self._osc_server:
5491			self._osc_server.send("/bar", bar)
5492			self._osc_server.send("/bpm", self._sequencer.current_bpm)
5493
5494			sounding = self.current_chord()
5495			if sounding is not None:
5496				self._osc_server.send("/chord", sounding.name())
5497
5498			if self._form_state:
5499				info = self._form_state.get_section_info()
5500				if info:
5501					self._osc_server.send("/section", info.name)
5502
5503	async def _run (self) -> None:
5504
5505		"""
5506		Async entry point that schedules all patterns and runs the sequencer.
5507		"""
5508
5509		# 1. Pre-calculate MIDI input indices and configure sequencer clock follow.
5510		if self._input_device is not None:
5511			self._sequencer.input_device_name = self._input_device
5512			self._sequencer.clock_follow = self._clock_follow
5513			self._sequencer.clock_device_idx = 0
5514
5515			if not self._clock_follow:
5516				# Find first additional input that wants to be the clock master.
5517				for idx, (_, _, cf) in enumerate(self._additional_inputs, start=1):
5518					if cf:
5519						self._sequencer.clock_follow = True
5520						self._sequencer.clock_device_idx = idx
5521						break
5522
5523		# Populate input device name mapping early (before opening ports) so we can
5524		# resolve CC mappings to integer device indices immediately.
5525		if self._sequencer.input_device_name:
5526			self._input_device_names[self._sequencer.input_device_name] = 0
5527			if self._input_device_alias is not None:
5528				self._input_device_names[self._input_device_alias] = 0
5529
5530		for idx, (dev_name, alias, _) in enumerate(self._additional_inputs, start=1):
5531			self._input_device_names[dev_name] = idx
5532			if alias:
5533				self._input_device_names[alias] = idx
5534
5535		# 2. Pre-calculate output device names.
5536		if self._sequencer.output_device_name:
5537			self._output_device_names[self._sequencer.output_device_name] = 0
5538			# Primary device (index 0) is open by now (_init_midi_output ran in
5539			# the Sequencer constructor), so its latency can be set safely here.
5540			if self._output_latency_ms:
5541				self._sequencer.set_device_latency(0, self._output_latency_ms)
5542
5543		# 3. Resolve name-based INPUT device ids in cc_map/cc_forward early — the
5544		# input-names map is fully populated above, and the callback thread needs
5545		# integer indices as soon as ports open.  OUTPUT names (cc_forward
5546		# output_device=, pattern device=) resolve after the additional outputs
5547		# are opened below; resolving them here matched against a map containing
5548		# only the primary and silently routed everything to device 0.
5549		for mapping in self._cc_mappings:
5550			raw = mapping.get('input_device')
5551			if isinstance(raw, str):
5552				mapping['input_device'] = self._resolve_input_device_id(raw)
5553		for fwd in self._cc_forwards:
5554			raw_in = fwd.get('input_device')
5555			if isinstance(raw_in, str):
5556				fwd['input_device'] = self._resolve_input_device_id(raw_in)
5557
5558		# 4. Share CC input mappings, forwards, and a reference to composition.data
5559		# with the sequencer BEFORE opening the ports. This ensures that any initial
5560		# messages in the OS buffer are correctly mapped as soon as the port opens.
5561		self._sequencer.cc_mappings = self._cc_mappings
5562		self._sequencer.cc_forwards = self._cc_forwards
5563		self._sequencer._composition_data = self.data
5564
5565		# Held-note input: create the tracker and resolve its channel/device
5566		# filter so the callback thread can buffer matching note events.
5567		if self._note_input is not None:
5568			if self._input_device is None and not self._additional_inputs:
5569				raise RuntimeError("note_input() requires a MIDI input — call composition.midi_input(device) first")
5570			raw_dev = self._note_input.get('input_device')
5571			if isinstance(raw_dev, str):
5572				raw_dev = self._resolve_input_device_id(raw_dev)
5573			self._sequencer._note_input_channel = self._note_input['channel']
5574			self._sequencer._note_input_device = raw_dev
5575			self._sequencer._held_notes = subsequence.held_notes.HeldNotes(
5576				release_ms = self._note_input['release_ms'],
5577				latch = self._note_input['latch'],
5578			)
5579
5580		# 5. Open MIDI input ports early. Even without a deliberate sleep, opening
5581		# them before pattern building minimizes the window for missed messages.
5582		# Primary input
5583		self._sequencer._open_midi_inputs()
5584
5585		# Additional inputs
5586		for idx, (dev_name, alias, cf) in enumerate(self._additional_inputs, start=1):
5587			# Use the pre-calculated index
5588			callback = self._sequencer._make_input_callback(idx)
5589			open_name, port = subsequence.midi_utils.select_input_device(dev_name, callback)
5590			if open_name and port is not None:
5591				self._sequencer.add_input_device(open_name, port)
5592			else:
5593				logger.warning(f"Could not open additional input device '{dev_name}'")
5594
5595		# 6. Open additional MIDI output devices.
5596		for out in self._additional_outputs:
5597			open_name, port = subsequence.midi_utils.select_output_device(out.device)
5598			if open_name and port is not None:
5599				idx = self._sequencer.add_output_device(open_name, port, out.latency_ms)
5600				self._output_device_names[open_name] = idx
5601				if out.alias is not None:
5602					self._output_device_names[out.alias] = idx
5603			else:
5604				logger.warning(f"Could not open additional output device '{out.device}'")
5605
5606		# Warn if latency compensation adds noticeable whole-rig delay: the
5607		# slowest device defines the alignment point, so every faster device is
5608		# delayed up to that amount and live-input feel suffers.
5609		self._warn_if_high_latency()
5610
5611		# Resolve any name-based output device IDs on patterns that may have been added
5612		# for additional output devices.
5613		self._resolve_pending_devices()
5614
5615		# Resolve cc_forward output-device names now that every output port and
5616		# alias is registered (resolving earlier silently routed to device 0).
5617		for fwd in self._cc_forwards:
5618			raw_out = fwd.get('output_device')
5619			if isinstance(raw_out, str):
5620				fwd['output_device'] = self._resolve_device_id(raw_out)
5621
5622		# Pass clock output flag (suppressed automatically when clock_follow=True).
5623		self._sequencer.clock_output = self._clock_output and not self.is_clock_following
5624
5625		# Create Ableton Link clock if comp.link() was called.
5626		if self._link_quantum is not None:
5627			self._sequencer._link_clock = subsequence.link_clock.LinkClock(
5628				bpm = self.bpm,
5629				quantum = self._link_quantum,
5630				loop = asyncio.get_running_loop(),
5631			)
5632
5633		# Deal play-time streams.  Every stream is NAME-keyed (crc32 of
5634		# "seed:name", see _stream_seed) rather than dealt from one master in
5635		# registration order: adding or removing one consumer can never shift
5636		# another's stream, and patterns added live derive identically in
5637		# _build_pattern_from_pending.  When no seed is set, components keep
5638		# their own unseeded RNGs (existing behaviour).
5639		if self._seed is not None:
5640
5641			harmony_stream = self._stream("play:harmony")
5642			if self._harmonic_state is not None and harmony_stream is not None:
5643				self._harmonic_state.rng = harmony_stream
5644
5645			form_stream = self._stream("play:form")
5646			if self._form_state is not None and form_stream is not None:
5647				self._form_state._rng = form_stream
5648
5649		# The clocks fire BEFORE pattern rebuilds at the same pulse, and their
5650		# lookahead is RAISED to the maximum pattern lookahead (never patterns
5651		# clamped down): when a pattern rebuilds for its next cycle, the form
5652		# state and the harmony window already describe that cycle.
5653		bar_beats = float(self.time_signature[0])
5654
5655		pattern_lookaheads = [pending.reschedule_lookahead for pending in self._pending_patterns]
5656		pattern_lookaheads += [pattern.reschedule_lookahead for pattern in self._running_patterns.values()]
5657		max_pattern_lookahead = max(pattern_lookaheads, default = 1)
5658
5659		clock_lookahead = max(1.0, float(self._harmony_reschedule_lookahead), float(max_pattern_lookahead))
5660
5661		if clock_lookahead > bar_beats:
5662			logger.warning(
5663				"A pattern's reschedule_lookahead (%.2g beats) exceeds the bar length (%.2g) — "
5664				"the harmony/form clocks fire at most one bar ahead, so that pattern may "
5665				"rebuild before the window covers its cycle start.",
5666				clock_lookahead, bar_beats,
5667			)
5668			clock_lookahead = bar_beats
5669
5670		# Minimum span >= maximum lookahead: the clock cannot prepare a chord
5671		# boundary that arrives sooner than it fires.  Harmonic motion faster
5672		# than this floor stays available at the part level (p.progression),
5673		# where placement is not clock-bound.
5674		def _check_span_floor (progression: typing.Optional[Progression], label: str) -> None:
5675			if progression is None:
5676				return
5677			shortest = min(span.beats for span in progression.spans)
5678			if shortest < clock_lookahead - 1e-9:
5679				raise ValueError(
5680					f"{label}: shortest chord span ({shortest:g} beats) is below the clock "
5681					f"lookahead ({clock_lookahead:g} beats — the largest pattern lookahead). "
5682					"Lengthen the span, lower the pattern lookaheads, or place fast harmony "
5683					"at the part level with p.progression()."
5684				)
5685
5686		_check_span_floor(self._bound_progression, "harmony(progression=)")
5687		for section_name, section_progression in self._section_progressions.items():
5688			_check_span_floor(section_progression, f"section_chords({section_name!r})")
5689
5690		# Key-relative section progressions resolve late, per occurrence — so
5691		# verify they WILL resolve now, before playback, rather than surfacing
5692		# a silent skip (or a dead clock) mid-render.  For each occurrence's
5693		# effective key+scale: a missing key, or a degree/scale that does not
5694		# resolve, is raised here with an actionable message.
5695		fs = self._form_state
5696
5697		for section_name, section_progression in self._section_progressions.items():
5698			if section_progression.is_concrete:
5699				continue
5700
5701			# The (key, scale) contexts this section may be resolved against.
5702			contexts: typing.List[typing.Tuple[typing.Optional[str], typing.Optional[str]]] = []
5703			if fs is not None and fs._sequence is not None and any(s.name == section_name for s in fs._sequence):
5704				for section in fs._sequence:
5705					if section.name != section_name:
5706						continue
5707					ctx = (section.key or self._form_key or self.key, section.scale or self._form_scale or self.scale)
5708					if ctx not in contexts:
5709						contexts.append(ctx)
5710			else:
5711				contexts.append((self._form_key or self.key, self._form_scale or self.scale))
5712
5713			for ctx_key, ctx_scale in contexts:
5714				if ctx_key is None:
5715					raise ValueError(
5716						f"section_chords({section_name!r}) is key-relative (degrees/romans) but no key "
5717						"resolves for it — set key= on the Composition, a form key (form(key=...)), or "
5718						f"a Section.key on every {section_name!r} section."
5719					)
5720				try:
5721					section_progression.resolve(ctx_key, ctx_scale or "ionian")
5722				except ValueError as error:
5723					raise ValueError(
5724						f"section_chords({section_name!r}) does not resolve against its effective key "
5725						f"{ctx_key} {ctx_scale or 'ionian'}: {error}"
5726					)
5727
5728		# min_energy with nothing feeding p.energy is a silent no-op — warn loudly.
5729		energy_gated = [p.builder_fn.__name__ for p in self._pending_patterns if p.min_energy is not None]
5730
5731		if energy_gated and not self._energy_map and not self._form_has_payload:
5732			logger.warning(
5733				f"min_energy is set on {', '.join(energy_gated)} but no energy source is "
5734				"configured — p.energy is always 0.5 (call composition.energy() or bind a "
5735				"Form whose Sections carry energy)"
5736			)
5737
5738		# The form clock MUST be registered before the harmonic clock: same-pulse
5739		# fixed callbacks fire in registration order (and all fixed callbacks fire
5740		# before callback sequences), and on a section-boundary bar the harmonic
5741		# clock reads the current section (via _get_section_progression) to decide
5742		# whether to walk that section's chords.  Registering harmony first would
5743		# make it read the OLD section on every boundary, shifting section_chords()
5744		# replays by one bar and bleeding them across sections.
5745		if self._form_state is not None:
5746
5747			await schedule_form(
5748				sequencer = self._sequencer,
5749				form_state = self._form_state,
5750				reschedule_lookahead = clock_lookahead,
5751				on_bar = self._check_transitions,
5752				# Re-read every bar so a mid-playback form() re-bind advances
5753				# the NEW state instead of the abandoned object.
5754				get_form_state = lambda: self._form_state,
5755			)
5756
5757		self._harmony_horizon.reset()
5758		self._harmonic_clock_started = False
5759
5760		if self._harmonic_state is not None or self._bound_progression is not None or self._section_progressions:
5761			await self._start_harmonic_clock(bar_beats, clock_lookahead)
5762
5763		# Bar counter - always active so p.bar is available to all builders.
5764		def _advance_builder_bar (pulse: int) -> None:
5765			self._builder_bar += 1
5766
5767		first_bar_pulse = int(self.time_signature[0] * self._sequencer.pulses_per_beat)
5768
5769		await self._sequencer.schedule_callback_repeating(
5770			callback = _advance_builder_bar,
5771			interval_beats = self.time_signature[0],
5772			start_pulse = first_bar_pulse,
5773			# Same raised lookahead as the form/harmony clocks: a pattern
5774			# rebuilding lookahead-early for its next cycle must read the bar
5775			# that cycle starts in, not the previous one.
5776			reschedule_lookahead = clock_lookahead
5777		)
5778
5779		# Run wait_for_initial=True scheduled functions and block until all complete.
5780		# This ensures composition.data is populated before patterns build.
5781		initial_tasks = [t for t in self._pending_scheduled if t.wait_for_initial]
5782
5783		if initial_tasks:
5784
5785			names = ", ".join(getattr(t.fn, '__name__', repr(t.fn)) for t in initial_tasks)
5786			logger.info(f"Waiting for initial scheduled {'function' if len(initial_tasks) == 1 else 'functions'} before start: {names}")
5787
5788			async def _run_initial (fn: typing.Callable) -> None:
5789
5790				accepts_ctx = _fn_has_parameter(fn, "p")
5791				ctx = ScheduleContext(cycle=0)
5792
5793				try:
5794					if inspect.iscoroutinefunction(fn):
5795						await (fn(ctx) if accepts_ctx else fn())
5796					else:
5797						loop = asyncio.get_running_loop()
5798						call = (lambda: fn(ctx)) if accepts_ctx else fn
5799						await loop.run_in_executor(None, call)
5800				except Exception as exc:
5801					logger.warning(f"Initial run of {getattr(fn, '__name__', repr(fn))!r} failed: {exc}")
5802
5803			await asyncio.gather(*[_run_initial(t.fn) for t in initial_tasks])
5804
5805		for pending_task in self._pending_scheduled:
5806
5807			accepts_ctx = _fn_has_parameter(pending_task.fn, "p")
5808
5809			# A wait_for_initial task already ran once as cycle 0 (the blocking
5810			# pre-roll above), so its repeating wrapper starts at cycle 1 — keeping
5811			# ScheduleContext.cycle monotonic across the initial and repeating runs.
5812			wrapped = _make_safe_callback(
5813				pending_task.fn,
5814				accepts_context = accepts_ctx,
5815				start_cycle = 1 if pending_task.wait_for_initial else 0,
5816			)
5817
5818			# wait_for_initial=True implies defer — no point firing at pulse 0
5819			# after the blocking run just completed.  defer=True skips the
5820			# backshift fire so the first repeating call happens one full cycle
5821			# later.
5822			if pending_task.wait_for_initial or pending_task.defer:
5823				start_pulse = int(pending_task.cycle_beats * self._sequencer.pulses_per_beat)
5824			else:
5825				start_pulse = 0
5826
5827			await self._sequencer.schedule_callback_repeating(
5828				callback = wrapped,
5829				interval_beats = pending_task.cycle_beats,
5830				start_pulse = start_pulse,
5831				reschedule_lookahead = pending_task.reschedule_lookahead
5832			)
5833
5834		# Build Pattern objects from pending registrations.
5835		patterns: typing.List[subsequence.pattern.Pattern] = []
5836
5837		for i, pending in enumerate(self._pending_patterns):
5838
5839			pattern = self._build_pattern_from_pending(pending)
5840			patterns.append(pattern)
5841
5842		await schedule_patterns(
5843			sequencer = self._sequencer,
5844			patterns = patterns,
5845			start_pulse = 0
5846		)
5847
5848		# Populate the running patterns dict for live hot-swap and mute/unmute.
5849		for i, pending in enumerate(self._pending_patterns):
5850			name = pending.builder_fn.__name__
5851			self._running_patterns[name] = patterns[i]
5852
5853		# Everything pending is running now; drop the declarations so a later
5854		# live reload cannot graduate stale copies.
5855		self._pending_patterns = []
5856
5857		if self._display is not None and not self._sequencer.render_mode:
5858			self._display.start()
5859			self._sequencer.on_event("bar",  self._display.update)
5860			self._sequencer.on_event("beat", self._display.update)
5861
5862		if self._live_server is not None:
5863			await self._live_server.start()
5864
5865		if self._osc_server is not None:
5866			await self._osc_server.start()
5867			self._sequencer.osc_server = self._osc_server
5868			self._sequencer.on_event("bar", self._broadcast_osc_status)
5869
5870		# Start keystroke listener if hotkeys are enabled and not in render mode.
5871		if self._hotkeys_enabled and not self._sequencer.render_mode:
5872			self._keystroke_listener = subsequence.keystroke.KeystrokeListener()
5873			self._keystroke_listener.start()
5874
5875			if self._keystroke_listener.active:
5876				# Listener started successfully — register the bar handler
5877				# and show all bindings so the user knows what's available.
5878				self._sequencer.on_event("bar", self._process_hotkeys)
5879				self._list_hotkeys()
5880			# If not active, KeystrokeListener.start() already logged a warning.
5881
5882		if self._web_ui_enabled and not self._sequencer.render_mode:
5883			self._web_ui_server = subsequence.web_ui.WebUI(self, http_host=self._web_ui_http_host, ws_host=self._web_ui_ws_host)
5884			self._web_ui_server.start()
5885
5886		try:
5887			await run_until_stopped(self._sequencer)
5888		finally:
5889			# Tear down every service even if run_until_stopped (or an earlier
5890			# stop) raised, and guard each individually, so one failure can't
5891			# strand the rest — most importantly the keystroke listener's
5892			# terminal restore.
5893			if self._web_ui_server is not None:
5894				try:
5895					self._web_ui_server.stop()
5896				except Exception:
5897					logger.exception("Error stopping web UI")
5898
5899			if self._live_server is not None:
5900				try:
5901					await self._live_server.stop()
5902				except Exception:
5903					logger.exception("Error stopping live server")
5904
5905			if self._live_reloader is not None:
5906				try:
5907					self._live_reloader.stop()
5908				except Exception:
5909					logger.exception("Error stopping live reloader")
5910
5911			if self._osc_server is not None:
5912				try:
5913					await self._osc_server.stop()
5914				except Exception:
5915					logger.exception("Error stopping OSC server")
5916				self._sequencer.osc_server = None
5917
5918			if self._display is not None:
5919				try:
5920					self._display.stop()
5921				except Exception:
5922					logger.exception("Error stopping display")
5923
5924			if self._keystroke_listener is not None:
5925				try:
5926					self._keystroke_listener.stop()
5927				except Exception:
5928					logger.exception("Error stopping keystroke listener")
5929				self._keystroke_listener = None
5930
5931	def _build_pattern_from_pending (self, pending: _PendingPattern, start_pulse: int = 0) -> subsequence.pattern.Pattern:
5932
5933		"""
5934		Create a Pattern from a pending registration using a temporary subclass.
5935
5936		The pattern's play stream is dealt here, keyed by NAME (crc32 of
5937		"seed:name" plus any reroll nonce), so registration order is
5938		irrelevant and a pattern added live gets exactly the stream it would
5939		have had at startup.  ``start_pulse`` anchors the first cycle on the
5940		beat axis so the initial build reads the harmony window at the right
5941		place (the sequencer keeps the anchor current on every reschedule).
5942		"""
5943
5944		composition_ref = self
5945		rng = self._stream(pending.builder_fn.__name__)
5946
5947		class _DecoratorPattern (subsequence.pattern.Pattern):
5948
5949			"""
5950			Pattern subclass that delegates to a builder function on each reschedule.
5951			"""
5952
5953			def __init__ (self, pending: _PendingPattern, pattern_rng: typing.Optional[random.Random] = None) -> None:
5954
5955				"""
5956				Initialize the decorator pattern from pending registration details.
5957				"""
5958
5959				super().__init__(
5960					channel = pending.channel,
5961					length = pending.length,
5962					reschedule_lookahead = pending.reschedule_lookahead,
5963					device = pending.device,
5964					mirrors = pending.mirrors,
5965				)
5966
5967				self._builder_fn = pending.builder_fn
5968				self._drum_note_map = pending.drum_note_map
5969				self._cc_name_map = pending.cc_name_map
5970				self._nrpn_name_map = pending.nrpn_name_map
5971				self._default_grid: int = pending.default_grid
5972				self._wants_chord = _fn_has_parameter(pending.builder_fn, "chord")
5973				self._cycle_count = 0
5974				self._rng = pattern_rng
5975				self._muted = False
5976				self._min_energy = pending.min_energy
5977				self._energy_gated = False
5978				self._voice_leading_state: typing.Optional[subsequence.voicings.VoiceLeadingState] = (
5979					subsequence.voicings.VoiceLeadingState() if pending.voice_leading else None
5980				)
5981				self._tweaks: typing.Dict[str, typing.Any] = {}
5982
5983				# Anchor of the cycle being built, on the absolute pulse axis.
5984				# The sequencer updates this on every reschedule; the initial
5985				# value is the pattern's first scheduled start.
5986				self._cycle_start_pulse = start_pulse
5987
5988				self._rebuild()
5989
5990			def _rebuild (self) -> None:
5991
5992				"""
5993				Clear steps and call the builder function to repopulate.
5994				"""
5995
5996				self.steps = {}
5997				self.cc_events = []
5998				self.osc_events = []
5999				self.raw_note_events = []
6000				current_cycle = self._cycle_count
6001				self._cycle_count += 1
6002
6003				# lock(): re-deal the stream from its effective seed every
6004				# rebuild so a locked pattern realizes identically each cycle.
6005				# Checked here (engine-side) so it survives live reload.
6006				if self._builder_fn.__name__ in composition_ref._locked_names:
6007					locked_seed = composition_ref._stream_seed(self._builder_fn.__name__)
6008					if locked_seed is not None:
6009						self._rng = random.Random(locked_seed)
6010
6011				if self._muted:
6012					return
6013
6014				section_info = composition_ref._form_state.get_section_info() if composition_ref._form_state else None
6015				energy = composition_ref._current_energy(section_info)
6016				effective_key, effective_scale = composition_ref._effective_key_scale(section_info)
6017
6018				# Automatic energy gating: below the threshold the pattern is
6019				# silent this cycle (composing with _muted — a performer mute
6020				# always wins).  Gate flips log once.
6021				if self._min_energy is not None:
6022					gated = energy < self._min_energy
6023
6024					if gated != self._energy_gated:
6025						state_word = "closed" if gated else "open"
6026						logger.info(
6027							f"Pattern '{self._builder_fn.__name__}': energy gate {state_word} "
6028							f"(energy {energy:.2f}, min_energy {self._min_energy:g})"
6029						)
6030						self._energy_gated = gated
6031
6032					if gated:
6033						return
6034
6035				# The harmony view for this cycle, anchored at its start beat —
6036				# under variable harmonic rhythm the window, not the engine's
6037				# mutating singleton, is the source of truth.
6038				harmony_view: typing.Optional[HarmonyView] = None
6039
6040				if not composition_ref._harmony_horizon.is_empty:
6041					origin_beat = self._cycle_start_pulse / composition_ref._sequencer.pulses_per_beat
6042					harmony_view = HarmonyView(composition_ref._harmony_horizon, origin_beat)
6043
6044				builder = subsequence.pattern_builder.PatternBuilder(
6045					pattern = self,
6046					cycle = current_cycle,
6047					drum_note_map = self._drum_note_map,
6048					cc_name_map = self._cc_name_map,
6049					nrpn_name_map = self._nrpn_name_map,
6050					section = section_info,
6051					bar = composition_ref._builder_bar,
6052					conductor = composition_ref.conductor,
6053					rng = self._rng,
6054					tweaks = self._tweaks,
6055					default_grid = self._default_grid,
6056					data = composition_ref.data,
6057					# The effective key/scale re-anchors key-relative content
6058					# (degrees, romans, generated material) to the section /
6059					# form / composition tier in force — mode travels too.
6060					key = effective_key,
6061					scale = effective_scale,
6062					time_signature = composition_ref.time_signature,
6063					held_notes = composition_ref._sequencer._held_notes,
6064					harmony = harmony_view,
6065					section_motifs = composition_ref._section_motifs,
6066					energy = energy,
6067				)
6068
6069				try:
6070
6071					if self._wants_chord:
6072
6073						# The two-parameter convention: the injected chord is
6074						# the cycle-start snapshot from the window (falling
6075						# back to the engine before the clock has run).
6076						chord = harmony_view.chord if harmony_view is not None else (
6077							composition_ref._harmonic_state.get_current_chord()
6078							if composition_ref._harmonic_state is not None else None
6079						)
6080
6081						if chord is not None:
6082							injected = _InjectedChord(
6083								chord,
6084								self._voice_leading_state,
6085								next_chord = harmony_view.next_chord if harmony_view is not None else None,
6086								beats_remaining = harmony_view.until_change if harmony_view is not None else None,
6087							)
6088							self._builder_fn(builder, injected)
6089						else:
6090							self._builder_fn(builder)
6091
6092					else:
6093						self._builder_fn(builder)
6094
6095				except Exception:
6096					# Discard whatever the builder placed before it raised —
6097					# otherwise a half-built pattern plays and the log lies.
6098					self.steps = {}
6099					self.cc_events = []
6100					self.osc_events = []
6101					self.raw_note_events = []
6102					logger.exception("Error in pattern builder '%s' (cycle %d) - pattern will be silent this cycle", self._builder_fn.__name__, current_cycle)
6103
6104				# Auto-apply global tuning if set and not already applied by the builder.
6105				if (
6106					composition_ref._tuning is not None
6107					and not builder._tuning_applied
6108					and not (composition_ref._tuning_exclude_drums and self._drum_note_map)
6109				):
6110					import subsequence.tuning as _tuning_mod
6111					_tuning_mod.apply_tuning_to_pattern(
6112						self,
6113						composition_ref._tuning,
6114						bend_range=composition_ref._tuning_bend_range,
6115						channels=composition_ref._tuning_channels,
6116						reference_note=composition_ref._tuning_reference_note,
6117					)
6118
6119			def on_reschedule (self) -> None:
6120
6121				"""
6122				Rebuild the pattern from the builder function before the next cycle.
6123				"""
6124
6125				self._rebuild()
6126
6127		return _DecoratorPattern(pending, rng)