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 pause (self) -> None:
3919
3920		"""
3921		Hold playback where it is, keeping the composition's place.
3922
3923		The clock stops advancing, sounding notes are released, and MIDI Stop
3924		is sent to any hardware following the clock output.  :meth:`resume`
3925		continues from the same pulse, beat and bar — where stopping and
3926		playing again would start the piece over.
3927
3928		Bar and cycle counters hold too, so patterns resume mid-phrase rather
3929		than jumping.  A note cut short by the pause is not re-struck on
3930		resume; it returns on its pattern's next cycle.
3931
3932		Idempotent and safe to call from any thread.  Ignored, with a log line,
3933		when the transport is not ours to hold — under ``clock_follow=True`` or
3934		an active Ableton Link session.
3935		"""
3936
3937		self._sequencer.pause()
3938
3939	def resume (self) -> None:
3940
3941		"""
3942		Continue playback from where :meth:`pause` held it.
3943
3944		Sends MIDI Continue rather than Start, so downstream hardware picks up
3945		where it left off instead of resetting to the top of its own pattern.
3946		Idempotent.
3947		"""
3948
3949		self._sequencer.resume()
3950
3951	@property
3952	def is_paused (self) -> bool:
3953
3954		"""True while playback is held by :meth:`pause`."""
3955
3956		return self._sequencer.paused
3957
3958	def mute (self, name: str) -> None:
3959
3960		"""
3961		Mute a running pattern by name.
3962		
3963		The pattern continues to 'run' and increment its cycle count in 
3964		the background, but it will not produce any MIDI notes until unmuted.
3965
3966		Parameters:
3967			name: The function name of the pattern to mute.
3968		"""
3969
3970		if name not in self._running_patterns:
3971			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3972
3973		# The performer takes ownership: if a transition's approach window had
3974		# muted this pattern, drop it from that set so the section boundary
3975		# does not silently unmute it ("performer mutes win").
3976		self._transition_muted.discard(name)
3977
3978		self._running_patterns[name]._muted = True
3979		logger.info(f"Muted pattern: {name}")
3980
3981	def unmute (self, name: str) -> None:
3982
3983		"""
3984		Unmute a previously muted pattern.
3985		"""
3986
3987		if name not in self._running_patterns:
3988			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3989
3990		# Symmetric ownership claim: an explicit unmute means the transition
3991		# machinery should no longer manage this pattern at the boundary.
3992		self._transition_muted.discard(name)
3993
3994		self._running_patterns[name]._muted = False
3995		logger.info(f"Unmuted pattern: {name}")
3996
3997	def unregister (self, name: str) -> None:
3998
3999		"""Fully remove a running pattern from rotation.
4000
4001		Unlike ``mute()`` (which keeps the pattern alive but silent),
4002		``unregister()`` tears the pattern down entirely.  It sets
4003		``pattern._removed = True`` so the sequencer's reschedule loop
4004		skips re-adding it on the next pulse; sends ``note_off`` for any
4005		of the pattern's currently-sounding notes on the primary
4006		destination AND on every mirror destination (so drones and
4007		sustaining notes stop immediately); and removes the entry from
4008		``_running_patterns`` so it no longer appears in ``live_info()``,
4009		the terminal grid, or any other consumer that enumerates running
4010		patterns.
4011
4012		Already-queued events in the sequencer's event queue play out —
4013		note_offs are paired with their note_ons at queue time, so notes
4014		end at their natural duration; only drones rely on the targeted
4015		``_stop_pattern_notes`` pass.
4016
4017		Idempotent: silently logs a ``debug`` and returns if the pattern
4018		is already absent.  Useful from both the live REPL
4019		(``composition.live()``) and the file watcher
4020		(``composition.watch()``), which calls this for any pattern
4021		removed from the watched file between reloads.
4022
4023		Parameters:
4024			name: Function name of the pattern to remove.
4025		"""
4026
4027		if name not in self._running_patterns:
4028			logger.debug(f"unregister() no-op: pattern '{name}' not running")
4029			return
4030
4031		pattern = self._running_patterns[name]
4032
4033		# Mark for removal first so the reschedule loop sees the flag even if
4034		# it fires concurrently with the note-off pass below.
4035		pattern._removed = True
4036
4037		# Stop sustaining notes (including drones) on every destination this
4038		# pattern outputs to.  Fire-and-forget across threads via the event
4039		# loop; ``_stop_pattern_notes`` acquires the queue lock internally.
4040		if self._sequencer._event_loop is not None:
4041			asyncio.run_coroutine_threadsafe(
4042				self._sequencer._stop_pattern_notes(pattern),
4043				loop = self._sequencer._event_loop,
4044			)
4045
4046		def _finalise_removal () -> None:
4047			self._running_patterns.pop(name, None)
4048
4049			# Forget any pending (not-yet-graduated) declaration too, so a
4050			# later live reload cannot resurrect the pattern.
4051			self._pending_patterns = [
4052				pending for pending in self._pending_patterns
4053				if pending.builder_fn.__name__ != name
4054			]
4055
4056			logger.info(f"Unregistered pattern: {name}")
4057
4058		# The running-patterns dict is iterated by the display, web UI, and
4059		# reschedule loop on the event loop thread — mutate it there when this
4060		# call arrives from another thread (e.g. the live TCP server).
4061		loop = self._sequencer._event_loop
4062
4063		try:
4064			on_loop = loop is not None and asyncio.get_running_loop() is loop
4065		except RuntimeError:
4066			on_loop = False
4067
4068		if loop is not None and loop.is_running() and not on_loop:
4069			loop.call_soon_threadsafe(_finalise_removal)
4070		else:
4071			_finalise_removal()
4072
4073	def mirror (self, name: str, device: int, channel: int, drum_note_map: typing.Optional[typing.Dict[str, int]] = None) -> None:
4074
4075		"""
4076		Add a mirror destination to a running pattern.
4077
4078		Every note, CC, pitch bend, NRPN/RPN, program change, SysEx, and drone
4079		event the pattern emits will also be sent to ``(device, channel)``,
4080		starting from the next cycle rebuild.  Idempotent on ``(device, channel)``
4081		— calling with the same destination twice does not double-fan; calling
4082		again with a different ``drum_note_map`` re-points it in place.
4083
4084		Parameters:
4085			name: Function name of the pattern to mirror.
4086			device: Output device index (the integer returned from
4087				``midi_output()``; 0 = primary device).
4088			channel: MIDI channel using this composition's numbering convention
4089				(1-16 by default; 0-15 if ``zero_indexed_channels=True``).
4090			drum_note_map: Optional per-destination drum map.  When set, mirrored
4091				drum hits are re-resolved by name through it, so a named voice
4092				lands on this device's own note number — see the README
4093				"MIDI mirroring" section.
4094
4095		Bandwidth: each mirror adds another full copy of the pattern's events.
4096		See the README "MIDI mirroring" section for the tradeoffs.
4097		"""
4098
4099		if name not in self._running_patterns:
4100			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4101
4102		resolved_channel = self._resolve_channel(channel)
4103		prefix = (device, resolved_channel)
4104		entry: subsequence.pattern.MirrorSpec = prefix if drum_note_map is None else (device, resolved_channel, drum_note_map)
4105
4106		pattern = self._running_patterns[name]
4107
4108		# Mirror-to-self check: comparing the (device, channel) prefix against the
4109		# live pattern's resolved destination.  Unlike the decorator path this is
4110		# always concrete.
4111		if prefix == (pattern.device, pattern.channel):
4112			logger.warning(
4113				f"Mirror destination {prefix} matches '{name}'s primary destination "
4114				f"— every event will double-fire on this (device, channel).  This is almost "
4115				f"certainly unintended."
4116			)
4117
4118		# Idempotent on (device, channel): replace any existing entry for the same
4119		# destination (so its map can be re-pointed), else append.
4120		existing_index = next((idx for idx, e in enumerate(pattern.mirrors) if (e[0], e[1]) == prefix), None)
4121		if existing_index is None:
4122			pattern.mirrors.append(entry)
4123			logger.info(f"Mirror added: {name} -> device={device}, channel={resolved_channel}")
4124		elif pattern.mirrors[existing_index] != entry:
4125			pattern.mirrors[existing_index] = entry
4126			logger.info(f"Mirror updated: {name} -> device={device}, channel={resolved_channel}")
4127		else:
4128			logger.debug(f"Mirror already present on {name}: device={device}, channel={resolved_channel}")
4129
4130	def unmirror (self, name: str, device: int, channel: int) -> None:
4131
4132		"""
4133		Remove a single mirror destination from a running pattern.
4134
4135		Matches on ``(device, channel)`` only — any attached ``drum_note_map`` is
4136		ignored.  Idempotent: silently does nothing if the destination is not
4137		currently mirrored.  The change applies on the next cycle rebuild.
4138		"""
4139
4140		if name not in self._running_patterns:
4141			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4142
4143		resolved_channel = self._resolve_channel(channel)
4144		prefix = (device, resolved_channel)
4145
4146		pattern = self._running_patterns[name]
4147
4148		filtered = [e for e in pattern.mirrors if (e[0], e[1]) != prefix]
4149		if len(filtered) != len(pattern.mirrors):
4150			pattern.mirrors[:] = filtered
4151			logger.info(f"Mirror removed: {name} -> device={device}, channel={resolved_channel}")
4152		else:
4153			logger.debug(f"unmirror() no-op on {name}: device={device}, channel={resolved_channel} not in mirrors")
4154
4155	def unmirror_all (self, name: str) -> None:
4156
4157		"""
4158		Remove every mirror destination from a running pattern.
4159		"""
4160
4161		if name not in self._running_patterns:
4162			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4163
4164		pattern = self._running_patterns[name]
4165
4166		if pattern.mirrors:
4167			pattern.mirrors.clear()
4168			logger.info(f"All mirrors cleared on pattern: {name}")
4169
4170	def tweak (self, name: str, **kwargs: typing.Any) -> None:
4171
4172		"""Override parameters for a running pattern.
4173
4174		Values set here are available inside the pattern's builder
4175		function via ``p.param()``.  They persist across rebuilds
4176		until explicitly changed or cleared.  Changes take effect
4177		on the next rebuild cycle.
4178
4179		Parameters:
4180			name: The function name of the pattern.
4181			``**kwargs``: Parameter names and their new values.
4182
4183		Example (from the live REPL)::
4184
4185			composition.tweak("bass", pitches=[48, 52, 55, 60])
4186		"""
4187
4188		if name not in self._running_patterns:
4189			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4190
4191		self._running_patterns[name]._tweaks.update(kwargs)
4192		logger.info(f"Tweaked pattern '{name}': {list(kwargs.keys())}")
4193
4194	def clear_tweak (self, name: str, *param_names: str) -> None:
4195
4196		"""Remove tweaked parameters from a running pattern.
4197
4198		If no parameter names are given, all tweaks for the pattern
4199		are cleared and every ``p.param()`` call reverts to its
4200		default.
4201
4202		Parameters:
4203			name: The function name of the pattern.
4204			*param_names: Specific parameter names to clear.  If
4205				omitted, all tweaks are removed.
4206		"""
4207
4208		if name not in self._running_patterns:
4209			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4210
4211		if not param_names:
4212			self._running_patterns[name]._tweaks.clear()
4213			logger.info(f"Cleared all tweaks for pattern '{name}'")
4214		else:
4215			for param_name in param_names:
4216				self._running_patterns[name]._tweaks.pop(param_name, None)
4217			logger.info(f"Cleared tweaks for pattern '{name}': {list(param_names)}")
4218
4219	def get_tweaks (self, name: str) -> typing.Dict[str, typing.Any]:
4220
4221		"""Return a copy of the current tweaks for a running pattern.
4222
4223		Parameters:
4224			name: The function name of the pattern.
4225		"""
4226
4227		if name not in self._running_patterns:
4228			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
4229
4230		return dict(self._running_patterns[name]._tweaks)
4231
4232	def schedule (self, fn: typing.Callable, cycle_beats: int, reschedule_lookahead: int = 1, wait_for_initial: bool = False, defer: bool = False) -> None:
4233
4234		"""
4235		Register a custom function to run on a repeating beat-based cycle.
4236
4237		Subsequence automatically runs synchronous functions in a thread pool
4238		so they don't block the timing-critical MIDI clock. Async functions
4239		are run directly on the event loop.
4240
4241		Parameters:
4242			fn: The function to call.
4243			cycle_beats: How often to call it (e.g., 4 = every bar).
4244			reschedule_lookahead: How far in advance to schedule the next call.
4245			wait_for_initial: If True, run the function once during startup
4246				and wait for it to complete before playback begins. This
4247				ensures ``composition.data`` is populated before patterns
4248				first build. Implies ``defer=True`` for the repeating
4249				schedule.
4250			defer: If True, skip the pulse-0 fire and defer the first
4251				repeating call to just before the second cycle boundary.
4252
4253		Raises:
4254			RuntimeError: If called after ``play()`` has started — scheduled
4255				tasks register at startup, so a late registration would be
4256				silently ignored otherwise.
4257		"""
4258
4259		if self._sequencer.running:
4260			raise RuntimeError("schedule() must be called before play() - scheduled tasks register at startup")
4261
4262		self._pending_scheduled.append(_PendingScheduled(fn, cycle_beats, reschedule_lookahead, wait_for_initial, defer))
4263
4264	def form (
4265		self,
4266		sections: typing.Union[
4267			"subsequence.forms.Form",
4268			typing.List[typing.Any],
4269			typing.Iterator[typing.Tuple[str, int]],
4270			typing.Dict[str, typing.Tuple[int, typing.Optional[typing.List[typing.Tuple[str, int]]]]]
4271		],
4272		loop: bool = False,
4273		start: typing.Optional[str] = None,
4274		at_end: str = "stop",
4275		key: typing.Optional[str] = None,
4276		scale: typing.Optional[str] = None,
4277	) -> None:
4278
4279		"""
4280		Define the structure (sections) of the composition.
4281
4282		You can define form in four ways:
4283
4284		1. **Form value**: a frozen :class:`~subsequence.forms.Form` of
4285		   :class:`~subsequence.forms.Section` values — the payload home
4286		   (energy, key per section); editable, navigable.
4287		2. **Sequence (List)**: a fixed order of ``(name, bars)`` tuples
4288		   or Sections (lists coerce — they are the same form).
4289		3. **Graph (Dict)**: dynamic transitions based on weights.
4290		4. **Generator**: a Python generator that yields ``(name, bars)`` pairs.
4291
4292		Form-value and list forms are **navigable**: ``form_jump()`` and
4293		``form_next()`` work on them (the jump lands on the next occurrence
4294		of the name, wrapping).
4295
4296		Re-binding ``form()`` during playback takes effect at the next bar —
4297		the clock reads the current form state on every bar, so the new form
4298		advances from there (its first section plays from its first bar).
4299
4300		Parameters:
4301			sections: The form definition (Form, List, Dict, or Generator).
4302			loop: Sugar for ``at_end="loop"``.
4303			start: The section to start with (Graph mode only).
4304			at_end: What happens when a sequence form runs out —
4305				``"stop"`` (the form finishes and patterns see no section;
4306				default), ``"hold"`` (the final section repeats until
4307				navigated away from), or ``"loop"`` (start over).  Graphs
4308				end via their terminal sections instead.
4309			key: A form-level key — the **form tier** of the key-source
4310				chain (``Section.key`` overrides it; it overrides the
4311				composition key).  Re-anchors key-relative content for the
4312				whole form.  When *sections* is a ``Form`` value carrying its
4313				own ``key``, that value is used unless this argument overrides.
4314			scale: A form-level scale/mode, paired with ``key``.
4315
4316		Example:
4317			```python
4318			# A simple pop structure
4319			comp.form([
4320				("verse", 8),
4321				("chorus", 8),
4322				("verse", 8),
4323				("chorus", 16)
4324			])
4325
4326			# The same structure with payloads, held open at the end
4327			S = subsequence.Section
4328			comp.form(subsequence.Form([
4329				S("verse", 8, energy=0.5), S("chorus", 8, energy=0.9),
4330			]), at_end="hold")
4331			```
4332		"""
4333
4334		# Seed FormState at form() time (per-call salt) so build-time walks —
4335		# the frozen clones form_freeze will take — are deterministic without
4336		# play(); the play-time stream is re-dealt name-keyed in _run().
4337		self._form_count += 1
4338
4339		self._form_state = subsequence.form_state.FormState(
4340			sections,
4341			loop = loop,
4342			start = start,
4343			rng = self._stream(f"form:{self._form_count}"),
4344			at_end = at_end,
4345		)
4346
4347		# A Form value carries energy payloads — that counts as an energy
4348		# source for the min_energy registration check in _run().
4349		self._form_has_payload = isinstance(sections, subsequence.forms.Form) or (
4350			isinstance(sections, list) and any(isinstance(element, subsequence.forms.Section) for element in sections)
4351		)
4352
4353		# Form-tier key/scale: an explicit argument wins; otherwise a Form
4354		# value's own key/scale seeds the tier.  Re-binding the form drops any
4355		# stale per-section resolution cache.
4356		if isinstance(sections, subsequence.forms.Form):
4357			self._form_key = key if key is not None else sections.key
4358			self._form_scale = scale if scale is not None else sections.scale
4359		else:
4360			self._form_key = key
4361			self._form_scale = scale
4362
4363		self._resolved_section_cache = {}
4364
4365	def form_freeze (self, sections: typing.Optional[int] = None) -> "subsequence.forms.Form":
4366
4367		"""Freeze the graph form's walk into an editable :class:`~subsequence.forms.Form`.
4368
4369		Walks a **clone** of the live form state — the same RNG state, so the
4370		frozen path is exactly the path the live graph would have played —
4371		and returns it as a Form value: inspect it, edit it
4372		(``path.replace(3, bars=16)``), and rebind it with
4373		``composition.form(path, at_end=...)``.  The live form state is
4374		untouched (rebinding replaces it).
4375
4376		Parameters:
4377			sections: Number of sections to freeze.  Without it, the walk
4378				runs until a terminal section; a graph with no terminal
4379				sections requires ``sections=`` explicitly.
4380
4381		Raises:
4382			ValueError: If no graph form is bound (a list form is already a
4383				frozen sequence), the form has already finished, or the walk
4384				cannot terminate.
4385
4386		Example::
4387
4388			composition.form({...}, start="intro")
4389			path = composition.form_freeze()          # the walk, frozen
4390			composition.form(path, at_end="stop")     # rebind the editable value
4391		"""
4392
4393		fs = self._form_state
4394
4395		if fs is None or fs._graph is None or fs._section_bars is None:
4396			raise ValueError(
4397				"form_freeze() freezes a graph form's walk — call form() with a dict first "
4398				"(a list form is already a frozen sequence)"
4399			)
4400
4401		if fs._current is None:
4402			raise ValueError("the form has already finished — nothing left to freeze")
4403
4404		if sections is not None and sections < 1:
4405			raise ValueError("sections must be at least 1")
4406
4407		if sections is None and not fs._terminal_sections:
4408			raise ValueError(
4409				"this graph has no terminal section, so the walk would never end — "
4410				"pass sections=n to bound it"
4411			)
4412
4413		# Clone the RNG state: the frozen walk reproduces the live form's
4414		# future draws without consuming them.
4415		rng = random.Random()
4416		rng.setstate(fs._rng.getstate())
4417
4418		walked = [fs._current]
4419		next_name = fs._next_section_name		# already decided by the live state
4420
4421		while next_name is not None:
4422			if sections is not None and len(walked) >= sections:
4423				break
4424			if sections is None and len(walked) >= 10000:
4425				raise ValueError(
4426					"form_freeze() walked 10000 sections without reaching a terminal — "
4427					"the terminals look unreachable; pass sections=n to bound the walk"
4428				)
4429
4430			walked.append(subsequence.forms.Section(name = next_name, bars = fs._section_bars[next_name]))
4431			next_name = None if next_name in fs._terminal_sections else fs._graph.choose_next(next_name, rng)
4432
4433		# Carry the form-tier key/scale onto the frozen value so a freeze →
4434		# rebind round-trip is lossless (an explicit form(key=) on rebind
4435		# still overrides).
4436		return subsequence.forms.Form(walked, key = self._form_key, scale = self._form_scale)
4437
4438	def energy (self, energies: typing.Dict[str, typing.Union[float, typing.Tuple[float, float]]]) -> None:
4439
4440		"""Set per-section energy — the arranging dial, as one plain dict.
4441
4442		``{"verse": 0.5, "chorus": 0.9, "build": (0.3, 1.0)}`` — a float is
4443		the section's level; a ``(start, end)`` tuple interpolates across the
4444		section (a build).  Patterns read ``p.energy`` (0.5 when nothing is
4445		configured) and gate themselves, or declare ``min_energy=`` on
4446		``pattern()`` for automatic muting.
4447
4448		The dict **overrides** any energy payload carried by bound
4449		:class:`~subsequence.forms.Section` values — it is the later,
4450		performance-level dial.  Re-calling replaces the whole mapping
4451		(idempotent, live-reload friendly).
4452
4453		Example::
4454
4455			composition.energy({"intro": 0.2, "verse": 0.55, "drop": 0.95})
4456		"""
4457
4458		validated: typing.Dict[str, typing.Union[float, typing.Tuple[float, float]]] = {}
4459
4460		for name, value in energies.items():
4461			if isinstance(value, tuple):
4462				if len(value) != 2:
4463					raise ValueError(f"energy ramp for {name!r} must be (start, end), got {value!r}")
4464				start_level, end_level = float(value[0]), float(value[1])
4465				for level in (start_level, end_level):
4466					if not 0.0 <= level <= 1.0:
4467						raise ValueError(f"energy for {name!r} must be 0.0–1.0, got {value!r}")
4468				validated[name] = (start_level, end_level)
4469			else:
4470				level = float(value)
4471				if not 0.0 <= level <= 1.0:
4472					raise ValueError(f"energy for {name!r} must be 0.0–1.0, got {value!r}")
4473				validated[name] = level
4474
4475		self._energy_map = validated
4476
4477	def _current_energy (self, info: typing.Optional[subsequence.form_state.SectionInfo]) -> float:
4478
4479		"""Resolve the energy for a section snapshot.
4480
4481		Priority: the ``energy()`` dict (ramps interpolate by section
4482		progress) > the bound Section payload > 0.5.
4483		"""
4484
4485		if info is None:
4486			return 0.5
4487
4488		spec = self._energy_map.get(info.name)
4489
4490		if spec is None:
4491			return info.energy
4492
4493		if isinstance(spec, tuple):
4494			start_level, end_level = spec
4495
4496			# A build reaches its declared end ON the final bar, so the ramp spans
4497			# bar 0 → bar (bars-1).  (info.progress is bar/bars, which would top
4498			# out one bar short and never deliver end.)  A one-bar section sits at
4499			# the destination level.
4500			span = info.bars - 1
4501			fraction = info.bar / span if span > 0 else 1.0
4502
4503			return start_level + (end_level - start_level) * fraction
4504
4505		return spec
4506
4507	def on_section (self, callback: typing.Callable[..., typing.Any]) -> None:
4508
4509		"""Register a callback fired on every section change.
4510
4511		The callback receives the new :class:`~subsequence.form_state.SectionInfo`
4512		(or ``None`` when the form finishes).  It fires from the form clock,
4513		one lookahead-beat **early** — in time to affect the new section's
4514		first patterns — and once at play start for the opening section.
4515
4516		Example::
4517
4518			composition.on_section(lambda info: print(f"now: {info.name if info else 'end'}"))
4519		"""
4520
4521		self.on_event("section", callback)
4522
4523	def transition (
4524		self,
4525		before: str,
4526		fill: typing.Optional[typing.Any] = None,
4527		channel: typing.Optional[int] = None,
4528		beat: float = 0.0,
4529		mute: typing.Optional[typing.List[str]] = None,
4530		beats: typing.Optional[float] = None,
4531		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
4532		device: subsequence.midi_utils.DeviceId = None,
4533	) -> None:
4534
4535		"""Declare boundary material — the automatic fill or mute, one line.
4536
4537		``before`` names the incoming section (``"chorus"``), or ``"*"`` for
4538		any *different* section (repeats don't fire it).  Two actions,
4539		combinable:
4540
4541		- ``fill=`` (+ ``channel=``, ``beat=``): a Motif played in the last
4542		  bar before the boundary, starting at ``beat`` of that bar.  Drum
4543		  names resolve through ``drum_note_map=`` if given, otherwise the
4544		  map is borrowed from a registered pattern on the same channel.
4545		- ``mute=`` (+ ``beats=``): pattern names muted over the approach
4546		  and unmuted at the boundary.  Muting is **bar-granular** (the
4547		  existing rule), so ``beats`` rounds up to whole bars.  Performer
4548		  mutes win: a pattern you muted yourself stays muted.
4549
4550		Transitions stack — call once per rule.  Registration is additive
4551		and idempotent per identical rule.
4552
4553		Example::
4554
4555			composition.transition(before="*", fill=FILL, channel=10, beat=2.0)
4556			composition.transition(before="drop", mute=["pads"], beats=4)
4557		"""
4558
4559		if fill is None and mute is None:
4560			raise ValueError("transition() needs fill= and/or mute= — it declares what happens at the boundary")
4561
4562		if fill is not None:
4563			if channel is None:
4564				raise ValueError("transition(fill=) needs channel= — the fill must land somewhere")
4565			if not hasattr(fill, "events") or not hasattr(fill, "length"):
4566				raise TypeError(f"fill must be a Motif-like value with .events/.length, got {type(fill).__name__}")
4567
4568		if mute is not None and beats is None:
4569			beats = float(self.time_signature[0])		# one bar by default
4570
4571		rule = _Transition(
4572			before = before,
4573			fill = fill,
4574			channel = self._resolve_channel(channel) if channel is not None else None,
4575			beat = float(beat),
4576			mute = list(mute) if mute is not None else None,
4577			beats = beats,
4578			drum_note_map = drum_note_map,
4579			device = device,			# resolved at fire time — names aren't known until play()
4580		)
4581
4582		if rule not in self._transitions:
4583			self._transitions.append(rule)
4584
4585	def _transition_drum_map (self, channel: typing.Optional[int]) -> typing.Optional[typing.Dict[str, int]]:
4586
4587		"""Borrow a drum map from a registered pattern on the same channel."""
4588
4589		if channel is None:
4590			return None
4591
4592		for pending in self._pending_patterns:
4593			if pending.channel == channel and pending.drum_note_map:
4594				return pending.drum_note_map
4595
4596		for running in self._running_patterns.values():
4597			candidate = getattr(running, "_drum_note_map", None)
4598			if running.channel == channel and candidate:
4599				return typing.cast(typing.Dict[str, int], candidate)
4600
4601		return None
4602
4603	def _fire_fill (self, rule: _Transition, start_pulse: int) -> None:
4604
4605		"""Build a transition fill as a one-shot pattern and schedule it."""
4606
4607		assert rule.fill is not None and rule.channel is not None
4608
4609		drum_map = rule.drum_note_map if rule.drum_note_map is not None else self._transition_drum_map(rule.channel)
4610
4611		pattern = subsequence.pattern.Pattern(
4612			channel = rule.channel,
4613			length = float(rule.fill.length),
4614			device = self._resolve_device_id(rule.device),
4615		)
4616
4617		harmony_view: typing.Optional[HarmonyView] = None
4618		if not self._harmony_horizon.is_empty:
4619			harmony_view = HarmonyView(self._harmony_horizon, start_pulse / self._sequencer.pulses_per_beat)
4620
4621		# The fill sounds in the outgoing section's final bar, so a degree-
4622		# bearing fill resolves against THAT section's effective key/scale —
4623		# previously it took the composition key, ignoring the section.
4624		fill_section = self._form_state.get_section_info() if self._form_state else None
4625		fill_key, fill_scale = self._effective_key_scale(fill_section)
4626
4627		builder = subsequence.pattern_builder.PatternBuilder(
4628			pattern = pattern,
4629			cycle = 0,
4630			drum_note_map = drum_map,
4631			section = fill_section,
4632			bar = self._builder_bar,
4633			conductor = self.conductor,
4634			rng = self._stream(f"transition:{rule.before}:{start_pulse}") or random.Random(),
4635			tweaks = {},
4636			default_grid = 16,
4637			data = self.data,
4638			key = fill_key,
4639			scale = fill_scale,
4640			time_signature = self.time_signature,
4641			harmony = harmony_view,
4642		)
4643
4644		try:
4645			builder.motif(rule.fill)
4646		except Exception:
4647			logger.exception("transition fill failed to build — the boundary plays without it")
4648			return
4649
4650		self._schedule_one_shot(pattern, start_pulse)
4651
4652	def _check_transitions (self, boundary_pulse: int, section_changed: bool) -> None:
4653
4654		"""The form clock's boundary hook: fire fills, manage approach mutes.
4655
4656		Called once per bar (lookahead-early, with the bar-line pulse).
4657		Fill rules fire when the current bar is the section's last before a
4658		matching boundary; mute rules close over the approach window
4659		(rounded up to whole bars — muting is bar-granular) and reopen at
4660		the boundary.  Performer mutes are never touched.
4661		"""
4662
4663		if section_changed and self._transition_muted:
4664			# The boundary arrived — restore only what we muted ourselves.
4665			for name in self._transition_muted:
4666				running = self._running_patterns.get(name)
4667				if running is not None:
4668					running._muted = False
4669			self._transition_muted.clear()
4670
4671		if not self._transitions or self._form_state is None:
4672			return
4673
4674		info = self._form_state.get_section_info()
4675
4676		if info is None or info.next_section is None:
4677			return
4678
4679		bar_beats = float(self.time_signature[0])
4680		bars_remaining = info.bars - info.bar
4681
4682		for rule in self._transitions:
4683
4684			if rule.before == "*":
4685				if info.next_section == info.name:
4686					continue		# a repeat is not a boundary
4687			elif info.next_section != rule.before:
4688				continue
4689
4690			if rule.fill is not None and bars_remaining == 1:
4691				self._fire_fill(rule, boundary_pulse + int(round(rule.beat * self._sequencer.pulses_per_beat)))
4692
4693			if rule.mute:
4694				window_beats = rule.beats if rule.beats is not None else bar_beats
4695				window_bars = max(1, int((window_beats + bar_beats - 1e-9) // bar_beats))
4696
4697				if bars_remaining <= window_bars:
4698					for name in rule.mute:
4699						running = self._running_patterns.get(name)
4700						if running is None or name in self._transition_muted:
4701							continue
4702						if running._muted:
4703							continue		# the performer's mute — not ours to manage
4704						running._muted = True
4705						self._transition_muted.add(name)
4706
4707	@staticmethod
4708	def _resolve_length (
4709		beats: typing.Optional[float],
4710		bars: typing.Optional[float],
4711		steps: typing.Optional[float],
4712		step_duration: typing.Optional[float],
4713		default: float = 4.0,
4714		beats_per_bar: int = 4,
4715	) -> typing.Tuple[float, int]:
4716
4717		"""
4718		Resolve the beat_length and default_grid from the duration parameters.
4719
4720		Two modes:
4721
4722		- **Duration mode** (no ``step_duration``): specify ``beats=`` or ``bars=``.
4723		  ``beats=4`` = 4 quarter notes; ``bars=2`` = 8 beats.
4724		- **Step mode** (with ``step_duration``): specify ``steps=`` and ``step_duration=``.
4725		  ``steps=6, step_duration=dur.SIXTEENTH`` = 6 sixteenth notes = 1.5 beats.
4726
4727		Constraints:
4728
4729		- ``beats`` and ``bars`` are mutually exclusive.
4730		- ``steps`` requires ``step_duration``; ``step_duration`` requires ``steps``.
4731		- ``steps`` cannot be combined with ``beats`` or ``bars``.
4732
4733		Returns:
4734			(beat_length, default_grid) — beat_length in beats (quarter notes);
4735			default_grid the number of grid steps (16th-notes in beat mode, or the
4736			explicit ``steps`` value directly in step mode).
4737		"""
4738
4739		if beats is not None and bars is not None:
4740			raise ValueError("Specify only one of beats= or bars=")
4741
4742		if steps is not None and (beats is not None or bars is not None):
4743			raise ValueError("steps= cannot be combined with beats= or bars=")
4744
4745		if step_duration is not None and steps is None:
4746			raise ValueError("step_duration= requires steps= (e.g. steps=6, step_duration=dur.SIXTEENTH)")
4747
4748		if steps is not None:
4749			if step_duration is None:
4750				raise ValueError("steps= requires step_duration= (e.g. step_duration=dur.SIXTEENTH)")
4751			return steps * step_duration, int(steps)
4752
4753		if bars is not None:
4754			raw = bars * beats_per_bar
4755		elif beats is not None:
4756			raw = beats
4757		else:
4758			raw = default
4759
4760		return raw, round(raw / subsequence.constants.durations.SIXTEENTH)
4761
4762	def pattern (
4763		self,
4764		channel: int,
4765		beats: typing.Optional[float] = None,
4766		bars: typing.Optional[float] = None,
4767		steps: typing.Optional[float] = None,
4768		step_duration: typing.Optional[float] = None,
4769		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
4770		cc_name_map: typing.Optional[typing.Dict[str, int]] = None,
4771		nrpn_name_map: typing.Optional[typing.Dict[str, int]] = None,
4772		reschedule_lookahead: float = 1,
4773		voice_leading: bool = False,
4774		device: subsequence.midi_utils.DeviceId = None,
4775		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
4776		min_energy: typing.Optional[float] = None,
4777	) -> typing.Callable:
4778
4779		"""
4780		Register a function as a repeating MIDI pattern.
4781
4782		The decorated function will be called once per cycle to 'rebuild' its
4783		content. This allows for generative logic that evolves over time.
4784
4785		Two ways to specify pattern length:
4786
4787		- **Duration mode** (default): use ``beats=`` or ``bars=``.
4788		  The grid defaults to sixteenth-note resolution.
4789		- **Step mode**: use ``steps=`` paired with ``step_duration=``.
4790		  The grid equals the step count, so ``p.hit_steps()`` indices map
4791		  directly to steps.
4792
4793		Parameters:
4794			channel: MIDI channel. By default uses 1-based numbering (1-16).
4795				Set ``zero_indexed_channels=True`` on the ``Composition`` to use
4796				0-based numbering (0-15), matching the raw MIDI protocol, instead.
4797			beats: Duration in beats (quarter notes). ``beats=4`` = 1 bar.
4798			bars: Duration in bars (uses the composition's time signature — 4 beats each in 4/4). ``bars=2`` = 8 beats.
4799			steps: Step count for step mode. Requires ``step_duration=``.
4800			step_duration: Duration of one step in beats (e.g. ``dur.SIXTEENTH``).
4801				Requires ``steps=``.
4802			drum_note_map: Optional mapping for drum instruments.
4803			cc_name_map: Optional mapping of CC names to MIDI CC numbers.
4804				Enables string-based CC names in ``p.cc()`` and ``p.cc_ramp()``.
4805			nrpn_name_map: Optional mapping of NRPN parameter names (strings) to
4806				14-bit parameter numbers (0–16383).  Enables string-based names
4807				in ``p.nrpn()`` and ``p.nrpn_ramp()`` — typically a
4808				device-specific dictionary (e.g. Sequential Take 5's
4809				``Osc1FreqFine`` → 9).
4810			reschedule_lookahead: Beats in advance to compute the next cycle.
4811			voice_leading: If True, chords in this pattern will automatically
4812				use inversions that minimize voice movement.
4813			mirrors: Optional list of additional ``(device, channel)`` destinations
4814				to duplicate every event from this pattern onto.  Notes, CCs, pitch
4815				bend, NRPN/RPN bursts, program changes, SysEx, and drone events are
4816				all mirrored; OSC events are not (OSC is not bound to a MIDI port).
4817				``device`` is the integer index returned by ``midi_output()`` (0 =
4818				primary).  ``channel`` follows this composition's channel-numbering
4819				convention.  See also ``mirror()`` / ``unmirror()`` for live toggling.
4820			min_energy: Automatic energy gating — the pattern is silent while
4821				the current section's energy (``composition.energy()`` dict,
4822				or the bound Section payload) is below this threshold.
4823				Composes with ``mute()``: a performer mute always wins.
4824
4825		Example:
4826			```python
4827			@comp.pattern(channel=1, beats=4)
4828			def chords (p):
4829				p.chord([60, 64, 67], beat=0, velocity=80, duration=3.9)
4830
4831			@comp.pattern(channel=1, bars=2)
4832			def long_phrase (p):
4833				...
4834
4835			@comp.pattern(channel=1, steps=6, step_duration=dur.SIXTEENTH)
4836			def riff (p):
4837				p.sequence(steps=[0, 1, 3, 5], pitches=60)
4838			```
4839		"""
4840
4841		channel = self._resolve_channel(channel)
4842
4843		beat_length, default_grid = self._resolve_length(beats, bars, steps, step_duration, beats_per_bar=self.time_signature[0])
4844
4845		# Resolve device string name to index if possible now; otherwise store
4846		# the raw DeviceId and resolve it in _run() once all devices are open.
4847		resolved_device: subsequence.midi_utils.DeviceId = device
4848
4849		# Mirror-to-self check is only reliable when the primary device is a
4850		# concrete integer at decoration time.  ``None`` resolves to device 0
4851		# downstream, so we treat it as 0 here too.  Strings are deferred to
4852		# ``_run()`` and we skip the check for them.
4853		primary: typing.Optional[typing.Tuple[int, int]]
4854		if isinstance(resolved_device, str):
4855			primary = None
4856		else:
4857			primary = (resolved_device if resolved_device is not None else 0, channel)
4858		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
4859
4860		def decorator (fn: typing.Callable) -> typing.Callable:
4861
4862			"""
4863			Wrap the builder function and register it as a pending pattern.
4864			During live sessions, hot-swap an existing pattern's builder instead.
4865			"""
4866
4867			# Record this declaration so the live-reload deletion diff knows the
4868			# pattern is still present in the source (see _apply_source_async).
4869			self._declared_names.add(fn.__name__)
4870
4871			# Hot-swap: if we're live and a pattern with this name exists, replace its builder.
4872			if self._is_live and fn.__name__ in self._running_patterns:
4873				running = self._running_patterns[fn.__name__]
4874				running._builder_fn = fn
4875				running._wants_chord = _fn_has_parameter(fn, "chord")
4876				logger.info(f"Hot-swapped pattern: {fn.__name__}")
4877				return fn
4878
4879			# Names key the seeded stream, mutes, tweaks, and reroll/lock — a
4880			# duplicate means two scheduled copies sharing one stream with
4881			# only one reachable by name.  Warn loudly at registration.
4882			if any(existing.builder_fn.__name__ == fn.__name__ for existing in self._pending_patterns):
4883				logger.warning(
4884					f"Duplicate pattern name '{fn.__name__}': both copies will be "
4885					f"scheduled, they share one seeded stream, and only one is "
4886					f"reachable by name — rename one of them."
4887				)
4888
4889			pending = _PendingPattern(
4890				builder_fn = fn,
4891				channel = channel,  # already resolved to 0-indexed
4892				length = beat_length,
4893				default_grid = default_grid,
4894				drum_note_map = drum_note_map,
4895				cc_name_map = cc_name_map,
4896				nrpn_name_map = nrpn_name_map,
4897				reschedule_lookahead = reschedule_lookahead,
4898				voice_leading = voice_leading,
4899				# For int/None: resolve immediately.  For str: store 0 as
4900				# placeholder; _resolve_pending_devices() fixes it in _run().
4901				device = 0 if (resolved_device is None or isinstance(resolved_device, str)) else resolved_device,
4902				raw_device = resolved_device,
4903				mirrors = resolved_mirrors,
4904				min_energy = min_energy,
4905			)
4906
4907			self._pending_patterns.append(pending)
4908
4909			return fn
4910
4911		return decorator
4912
4913	def layer (
4914		self,
4915		*builder_fns: typing.Callable,
4916		channel: int,
4917		beats: typing.Optional[float] = None,
4918		bars: typing.Optional[float] = None,
4919		steps: typing.Optional[float] = None,
4920		step_duration: typing.Optional[float] = None,
4921		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
4922		cc_name_map: typing.Optional[typing.Dict[str, int]] = None,
4923		nrpn_name_map: typing.Optional[typing.Dict[str, int]] = None,
4924		reschedule_lookahead: float = 1,
4925		voice_leading: bool = False,
4926		device: subsequence.midi_utils.DeviceId = None,
4927		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
4928	) -> None:
4929
4930		"""
4931		Combine multiple functions into a single MIDI pattern.
4932
4933		This is useful for composing complex patterns out of reusable
4934		building blocks (e.g., a 'kick' function and a 'snare' function).
4935
4936		See ``pattern()`` for the full description of ``beats``, ``bars``,
4937		``steps``, and ``step_duration``.
4938
4939		Parameters:
4940			builder_fns: One or more pattern builder functions.
4941			channel: MIDI channel (1-16, or 0-15 with ``zero_indexed_channels=True``).
4942			beats: Duration in beats (quarter notes).
4943			bars: Duration in bars (uses the composition's time signature — 4 beats each in 4/4).
4944			steps: Step count for step mode. Requires ``step_duration=``.
4945			step_duration: Duration of one step in beats. Requires ``steps=``.
4946			drum_note_map: Optional mapping for drum instruments.
4947			cc_name_map: Optional mapping of CC names to MIDI CC numbers.
4948			nrpn_name_map: Optional mapping of NRPN parameter names to 14-bit
4949				parameter numbers.
4950			reschedule_lookahead: Beats in advance to compute the next cycle.
4951			voice_leading: If True, chords use smooth voice leading.
4952			mirrors: Optional list of additional ``(device, channel)`` destinations
4953				to duplicate every event onto.  See ``pattern()`` for details.
4954		"""
4955
4956		beat_length, default_grid = self._resolve_length(beats, bars, steps, step_duration, beats_per_bar=self.time_signature[0])
4957
4958		# Resolve channel up-front so the mirror-to-self check has the canonical
4959		# primary form to compare against.
4960		resolved_channel = self._resolve_channel(channel)
4961
4962		# See pattern() for the same comment about None / str handling.
4963		primary: typing.Optional[typing.Tuple[int, int]]
4964		if isinstance(device, str):
4965			primary = None
4966		else:
4967			primary = (device if device is not None else 0, resolved_channel)
4968		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
4969
4970		wants_chord = any(_fn_has_parameter(fn, "chord") for fn in builder_fns)
4971
4972		if wants_chord:
4973
4974			def merged_builder (p: subsequence.pattern_builder.PatternBuilder, chord: _InjectedChord) -> None:
4975
4976				for fn in builder_fns:
4977					if _fn_has_parameter(fn, "chord"):
4978						fn(p, chord)
4979					else:
4980						fn(p)
4981
4982		else:
4983
4984			def merged_builder (p: subsequence.pattern_builder.PatternBuilder) -> None:  # type: ignore[misc]
4985
4986				for fn in builder_fns:
4987					fn(p)
4988
4989		# Give the merged builder a stable, unique name derived from its
4990		# components so multiple layer() calls don't all register under
4991		# "merged_builder" and collide in _running_patterns (which made
4992		# mute/tweak/unregister/live_info reach only the LAST layer).  "+" can't
4993		# appear in a Python identifier, so this never clashes with a real
4994		# pattern function's name.
4995		base_name = ("+".join(fn.__name__ for fn in builder_fns) or "layer") + f"@ch{resolved_channel}"
4996		merged_name = base_name
4997		suffix = 2
4998
4999		# Two layers with the same components (e.g. on different saves of a
5000		# live file) must map to the same names pass-over-pass, while two
5001		# DIFFERENT layers sharing components in one pass must not collide.
5002		while merged_name in self._declared_names:
5003			merged_name = f"{base_name}#{suffix}"
5004			suffix += 1
5005
5006		merged_builder.__name__ = merged_name
5007
5008		# Record the declaration for the live-reload deletion diff, and hot-swap
5009		# in place when this layer is already running so a reload picks up edits
5010		# to the component functions without losing the pattern's cycle count,
5011		# tweaks, or mirrors (mirrors the pattern() decorator's hot-swap).
5012		self._declared_names.add(merged_builder.__name__)
5013
5014		if self._is_live and merged_builder.__name__ in self._running_patterns:
5015			running = self._running_patterns[merged_builder.__name__]
5016			running._builder_fn = merged_builder
5017			running._wants_chord = wants_chord
5018			logger.info(f"Hot-swapped layer: {merged_builder.__name__}")
5019			return
5020
5021		pending = _PendingPattern(
5022			builder_fn = merged_builder,
5023			channel = resolved_channel,  # already resolved to 0-indexed above
5024			length = beat_length,
5025			default_grid = default_grid,
5026			drum_note_map = drum_note_map,
5027			cc_name_map = cc_name_map,
5028			nrpn_name_map = nrpn_name_map,
5029			reschedule_lookahead = reschedule_lookahead,
5030			voice_leading = voice_leading,
5031			mirrors = resolved_mirrors,
5032			device = 0 if (device is None or isinstance(device, str)) else device,
5033			raw_device = device,
5034		)
5035
5036		self._pending_patterns.append(pending)
5037
5038	def chords (
5039		self,
5040		*,
5041		channel: int,
5042		progression: subsequence.progressions.ProgressionSource,
5043		harmonic_rhythm: subsequence.progressions.HarmonicRhythmSpec,
5044		bars: typing.Optional[float] = None,
5045		beats: typing.Optional[float] = None,
5046		voicing: subsequence.progressions.VoicingSpec = (3, 4),
5047		velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_CHORD_VELOCITY,
5048		detached: typing.Optional[float] = None,
5049		root: int = 60,
5050		key: typing.Optional[str] = None,
5051		seed: typing.Optional[int] = None,
5052		device: subsequence.midi_utils.DeviceId = None,
5053		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
5054	) -> subsequence.progressions.Progression:
5055
5056		"""Declare a self-contained chord part: a progression at a chosen harmonic rhythm.
5057
5058		The one-call form of ``p.progression()`` — it registers a pattern on
5059		*channel* that plays *progression* across *bars* (or *beats*), each chord
5060		lasting a length drawn from *harmonic_rhythm* (the musical term for how often
5061		the chords change).  It needs no ``composition.harmony()`` call and, with an
5062		explicit chord list or a ``key=``, no composition key either — so a
5063		drums-plus-one-chord-part sketch stays simple.
5064
5065		The progression is realised once, up front, and the same timeline plays every
5066		cycle (a stable phrase).  That timeline is returned so you can see exactly what
5067		was chosen — ``print(comp.chords(...))``.
5068
5069		Parameters:
5070			channel: MIDI channel for the chord part.
5071			progression: A chord-graph style name to generate from, or an explicit list
5072				of chords (``Chord`` objects or names like ``["Cm7", "Dbmaj7"]``).
5073			harmonic_rhythm: How long each chord lasts — a number, a list of lengths,
5074				or ``between(low, high, step=...)``.  See ``p.progression()``.
5075			bars / beats: Length of the part (defaults to 4 beats if neither is given).  ``bars`` uses the
5076				composition's time signature.
5077			voicing: Notes per chord — an int, or a ``(low, high)`` range (e.g. ``(3, 4)``).
5078			velocity: MIDI velocity, or a ``(low, high)`` tuple for per-voice humanisation.
5079			detached: Beats of silence before each next chord (``duration = length - detached``).
5080			root: MIDI root the voicings are centred on (e.g. 48 = C3).
5081			key: Key for a generated progression; defaults to the composition key.
5082			seed: Seed for the (otherwise fixed) realisation; defaults to the
5083				composition seed, so the part is reproducible.
5084			device: Optional output-device override.
5085			mirrors: Optional additional ``(device, channel)`` destinations.
5086
5087		Returns:
5088			The realised :class:`~subsequence.progressions.Progression`.
5089		"""
5090
5091		beat_length, default_grid = self._resolve_length(beats, bars, None, None, beats_per_bar=self.time_signature[0])
5092		resolved_channel = self._resolve_channel(channel)
5093		resolved_key = key if key is not None else self.key
5094
5095		rng = random.Random(seed if seed is not None else self._seed)
5096		timeline = subsequence.progressions.realize(
5097			source = progression,
5098			harmonic_rhythm = harmonic_rhythm,
5099			key = resolved_key,
5100			length = beat_length,
5101			rng = rng,
5102			scale = self.scale or "ionian",
5103		)
5104
5105		captured_root = root
5106		captured_velocity = velocity
5107		captured_detached = detached
5108		captured_voicing = voicing
5109
5110		def chords_builder (p: subsequence.pattern_builder.PatternBuilder) -> None:
5111
5112			"""Replay the realised timeline as block chords each cycle (voicing per chord)."""
5113
5114			for chord, start, length in timeline:
5115				ring = length - captured_detached if (captured_detached and captured_detached < length) else length
5116				voices = subsequence.progressions.resolve_voices(captured_voicing, p.rng)
5117				p.chord(chord, root=captured_root, beat=start, duration=ring, count=voices, velocity=captured_velocity)
5118
5119		# Unique, stable name so multiple chord parts don't collide in
5120		# _running_patterns — including two parts on the SAME channel, which
5121		# get a deterministic #2/#3 suffix in declaration order.
5122		base_name = f"chords@ch{resolved_channel}"
5123		chords_name = base_name
5124		suffix = 2
5125
5126		while chords_name in self._declared_names:
5127			chords_name = f"{base_name}#{suffix}"
5128			suffix += 1
5129
5130		chords_builder.__name__ = chords_name
5131		self._declared_names.add(chords_name)
5132
5133		primary: typing.Optional[typing.Tuple[int, int]]
5134		if isinstance(device, str):
5135			primary = None
5136		else:
5137			primary = (device if device is not None else 0, resolved_channel)
5138		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
5139
5140		if self._is_live and chords_builder.__name__ in self._running_patterns:
5141			running = self._running_patterns[chords_builder.__name__]
5142			running._builder_fn = chords_builder
5143			running._wants_chord = False
5144			logger.info(f"Hot-swapped chords: {chords_builder.__name__}")
5145			return timeline
5146
5147		pending = _PendingPattern(
5148			builder_fn = chords_builder,
5149			channel = resolved_channel,
5150			length = beat_length,
5151			default_grid = default_grid,
5152			drum_note_map = None,
5153			reschedule_lookahead = 1,
5154			voice_leading = False,
5155			mirrors = resolved_mirrors,
5156			device = 0 if (device is None or isinstance(device, str)) else device,
5157			raw_device = device,
5158		)
5159		self._pending_patterns.append(pending)
5160		return timeline
5161
5162	def phrase_part (
5163		self,
5164		*,
5165		channel: int,
5166		part: typing.Optional[str] = None,
5167		root: int = 60,
5168		bars: typing.Optional[float] = None,
5169		beats: typing.Optional[float] = None,
5170		velocity: typing.Optional[typing.Union[int, typing.Tuple[int, int]]] = None,
5171		fit: typing.Optional[float] = None,
5172		device: subsequence.midi_utils.DeviceId = None,
5173		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
5174	) -> None:
5175
5176		"""Declare a part that plays each section's bound Motif/Phrase.
5177
5178		The one-call consumer for :meth:`section_motifs` — it registers a
5179		pattern on *channel* that walks whatever value is bound to the
5180		current section for *part* (stateless position from the cycle
5181		counter, via ``p.phrase()``).  A section with no binding for the
5182		part is **silent** for that part — bind material or don't; no
5183		fallback guessing.
5184
5185		Parameters:
5186			channel: MIDI channel for the part.
5187			part: The part label to read from the registry (``None`` = the
5188				unlabelled binding).
5189			root: Register anchor for degree resolution.
5190			bars / beats: Cycle length of the part (defaults to 4 beats);
5191				the phrase is sliced one cycle window at a time.
5192			velocity: Optional override applied to every note.
5193			fit: Passed through (active with the melody engine stage).
5194			device: Optional output-device override.
5195			mirrors: Optional additional ``(device, channel)`` destinations.
5196
5197		Example::
5198
5199			composition.section_motifs("verse",  verse_line,  part="lead")
5200			composition.section_motifs("chorus", chorus_line, part="lead")
5201			composition.phrase_part(channel=4, part="lead", root=72, bars=2)
5202		"""
5203
5204		beat_length, default_grid = self._resolve_length(beats, bars, None, None, beats_per_bar=self.time_signature[0])
5205		resolved_channel = self._resolve_channel(channel)
5206
5207		captured_part = part
5208		captured_root = root
5209		captured_velocity = velocity
5210		captured_fit = fit
5211
5212		def phrase_builder (p: subsequence.pattern_builder.PatternBuilder) -> None:
5213
5214			"""Walk the current section's bound value (silent when unbound)."""
5215
5216			value = p.section_motif(captured_part)
5217
5218			if value is None:
5219				return	# unbound section: silence for this part, by design
5220
5221			p.phrase(value, root=captured_root, velocity=captured_velocity, fit=captured_fit)
5222
5223		# Unique, stable name so multiple phrase parts don't collide —
5224		# including two parts on the SAME channel (deterministic #2/#3
5225		# suffixes in declaration order, the chords() convention).
5226		base_name = f"phrase@{captured_part}@ch{resolved_channel}" if captured_part else f"phrase@ch{resolved_channel}"
5227		phrase_name = base_name
5228		suffix = 2
5229
5230		while phrase_name in self._declared_names:
5231			phrase_name = f"{base_name}#{suffix}"
5232			suffix += 1
5233
5234		phrase_builder.__name__ = phrase_name
5235		self._declared_names.add(phrase_name)
5236
5237		primary: typing.Optional[typing.Tuple[int, int]]
5238		if isinstance(device, str):
5239			primary = None
5240		else:
5241			primary = (device if device is not None else 0, resolved_channel)
5242		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
5243
5244		if self._is_live and phrase_builder.__name__ in self._running_patterns:
5245			running = self._running_patterns[phrase_builder.__name__]
5246			running._builder_fn = phrase_builder
5247			running._wants_chord = False
5248			logger.info(f"Hot-swapped phrase part: {phrase_builder.__name__}")
5249			return
5250
5251		pending = _PendingPattern(
5252			builder_fn = phrase_builder,
5253			channel = resolved_channel,
5254			length = beat_length,
5255			default_grid = default_grid,
5256			drum_note_map = None,
5257			reschedule_lookahead = 1,
5258			voice_leading = False,
5259			mirrors = resolved_mirrors,
5260			device = 0 if (device is None or isinstance(device, str)) else device,
5261			raw_device = device,
5262		)
5263		self._pending_patterns.append(pending)
5264
5265	def trigger (
5266		self,
5267		fn: typing.Callable,
5268		channel: int,
5269		beats: typing.Optional[float] = None,
5270		bars: typing.Optional[float] = None,
5271		steps: typing.Optional[float] = None,
5272		step_duration: typing.Optional[float] = None,
5273		quantize: float = 0,
5274		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
5275		cc_name_map: typing.Optional[typing.Dict[str, int]] = None,
5276		nrpn_name_map: typing.Optional[typing.Dict[str, int]] = None,
5277		chord: bool = False,
5278		device: subsequence.midi_utils.DeviceId = None,
5279		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
5280	) -> None:
5281
5282		"""
5283		Trigger a one-shot pattern immediately or on a quantized boundary.
5284
5285		This is useful for real-time response to sensors, OSC messages, or other
5286		external events. The builder function is called immediately with a fresh
5287		PatternBuilder, and the generated events are injected into the queue at
5288		the specified quantize boundary.
5289
5290		The builder function has the same API as a ``@composition.pattern``
5291		decorated function and can use all PatternBuilder methods: ``p.note()``,
5292		``p.euclidean()``, ``p.arpeggio()``, and so on.
5293
5294		See ``pattern()`` for the full description of ``beats``, ``bars``,
5295		``steps``, and ``step_duration``. Default is 1 beat.
5296
5297		Parameters:
5298			fn: The pattern builder function (same signature as ``@comp.pattern``).
5299			channel: MIDI channel (1-16, or 0-15 with ``zero_indexed_channels=True``).
5300			beats: Duration in beats (quarter notes, default 1).
5301			bars: Duration in bars (uses the composition's time signature — 4 beats each in 4/4).
5302			steps: Step count for step mode. Requires ``step_duration=``.
5303			step_duration: Duration of one step in beats. Requires ``steps=``.
5304			quantize: Snap the trigger to a beat boundary: ``0`` = immediate (default),
5305				``1`` = next beat (quarter note), ``4`` = next bar. Use ``dur.*``
5306				constants from ``subsequence.constants.durations``.
5307			drum_note_map: Optional drum name mapping for this pattern.
5308			cc_name_map: Optional mapping of CC names to MIDI CC numbers.
5309			nrpn_name_map: Optional mapping of NRPN parameter names to
5310				14-bit parameter numbers.
5311			chord: If ``True``, the builder function receives the current chord as
5312				a second parameter (same as ``@composition.pattern``).
5313			mirrors: Optional list of additional ``(device, channel)`` destinations
5314				to fire this one-shot onto in parallel with the primary destination.
5315
5316		Example:
5317			```python
5318			# Immediate single note (channels are 1-16 by default)
5319			composition.trigger(
5320				lambda p: p.note(60, beat=0, velocity=100, duration=0.5),
5321				channel=1
5322			)
5323
5324			# Quantized fill (next bar) — channel 10 is the GM drum channel
5325			import subsequence.constants.durations as dur
5326			composition.trigger(
5327				lambda p: p.euclidean("snare", pulses=7, velocity=90),
5328				channel=10,
5329				drum_note_map=gm_drums.GM_DRUM_MAP,
5330				quantize=dur.WHOLE
5331			)
5332
5333			# With chord context — the builder receives the chord as a second
5334			# argument when chord=True.
5335			composition.trigger(
5336				lambda p, chord: p.arpeggio(chord.tones(root=60), spacing=dur.SIXTEENTH),
5337				channel=1,
5338				quantize=dur.QUARTER,
5339				chord=True
5340			)
5341			```
5342		"""
5343
5344		# Resolve channel numbering
5345		resolved_channel = self._resolve_channel(channel)
5346
5347		beat_length, default_grid = self._resolve_length(beats, bars, steps, step_duration, default=1.0, beats_per_bar=self.time_signature[0])
5348
5349		# Resolve device index — for trigger() this is always concrete by call time,
5350		# so the mirror-to-self check has the full primary tuple available.
5351		resolved_device_idx = self._resolve_device_id(device)
5352		resolved_mirrors = self._resolve_mirrors(mirrors, primary=(resolved_device_idx, resolved_channel))
5353
5354		# Create a temporary Pattern
5355		pattern = subsequence.pattern.Pattern(channel=resolved_channel, length=beat_length, device=resolved_device_idx, mirrors=resolved_mirrors)
5356
5357		# Resolve the section context once: the one-shot inherits the section's
5358		# effective key/scale (so a triggered degree resolves like everywhere
5359		# else) and a harmony view at the current playhead (so ChordTone /
5360		# Approach resolve too).
5361		trigger_section = self._form_state.get_section_info() if self._form_state else None
5362		trigger_key, trigger_scale = self._effective_key_scale(trigger_section)
5363
5364		trigger_harmony: typing.Optional[HarmonyView] = None
5365		if not self._harmony_horizon.is_empty:
5366			trigger_harmony = HarmonyView(self._harmony_horizon, self._sequencer.pulse_count / self._sequencer.pulses_per_beat)
5367
5368		# Create a PatternBuilder
5369		builder = subsequence.pattern_builder.PatternBuilder(
5370			pattern=pattern,
5371			cycle=0,  # One-shot patterns don't rebuild, so cycle is always 0
5372			drum_note_map=drum_note_map,
5373			cc_name_map=cc_name_map,
5374			nrpn_name_map=nrpn_name_map,
5375			section=trigger_section,
5376			bar=self._builder_bar,
5377			conductor=self.conductor,
5378			rng=random.Random(),  # Fresh random state for each trigger
5379			tweaks={},
5380			default_grid=default_grid,
5381			data=self.data,
5382			# A one-shot resolves key-relative content against the same
5383			# effective key/scale as the section it fires into (previously
5384			# omitted entirely — degrees raised even in a keyed composition).
5385			key=trigger_key,
5386			scale=trigger_scale,
5387			time_signature=self.time_signature,
5388			held_notes=self._sequencer._held_notes,
5389			harmony=trigger_harmony,
5390			energy=self._current_energy(trigger_section)
5391		)
5392
5393		# Call the builder function
5394		try:
5395
5396			current_chord = self.current_chord() if chord else None
5397
5398			if current_chord is not None:
5399				injected = _InjectedChord(current_chord, None)  # No voice leading for one-shots
5400				fn(builder, injected)
5401
5402			else:
5403				fn(builder)
5404
5405		except Exception:
5406			logger.exception("Error in trigger builder — pattern will be silent")
5407			return
5408
5409		# Calculate the start pulse based on quantize
5410		current_pulse = self._sequencer.pulse_count
5411		pulses_per_beat = subsequence.constants.MIDI_QUARTER_NOTE
5412
5413		if quantize == 0:
5414			# Immediate: use current pulse
5415			start_pulse = current_pulse
5416
5417		else:
5418			# Quantize to the next multiple of (quantize * pulses_per_beat)
5419			quantize_pulses = int(quantize * pulses_per_beat)
5420			start_pulse = ((current_pulse // quantize_pulses) + 1) * quantize_pulses
5421
5422		self._schedule_one_shot(pattern, start_pulse)
5423
5424	def _schedule_one_shot (self, pattern: subsequence.pattern.Pattern, start_pulse: int) -> None:
5425
5426		"""Schedule a one-shot pattern at an absolute pulse, thread-safely."""
5427
5428		try:
5429			# Probe only: raises RuntimeError when not on the event loop.
5430			asyncio.get_running_loop()
5431			asyncio.create_task(self._sequencer.schedule_pattern(pattern, start_pulse))
5432
5433		except RuntimeError:
5434			# Not on the event loop — hand the coroutine to the loop thread.
5435			if self._sequencer._event_loop is not None:
5436				asyncio.run_coroutine_threadsafe(
5437					self._sequencer.schedule_pattern(pattern, start_pulse),
5438					loop=self._sequencer._event_loop
5439				)
5440			else:
5441				logger.warning("trigger() called before playback started; pattern ignored")
5442
5443	@property
5444	def is_clock_following (self) -> bool:
5445
5446		"""True if either the primary or any additional device is following external clock."""
5447
5448		return self._clock_follow or any(cf for _, _, cf in self._additional_inputs)
5449
5450
5451	def play (self) -> None:
5452
5453		"""
5454		Start the composition.
5455
5456		This call blocks until the program is interrupted (e.g., via Ctrl+C).
5457		It initializes the MIDI hardware, launches the background sequencer,
5458		and begins playback.
5459		"""
5460
5461		try:
5462			asyncio.run(self._run())
5463
5464		except KeyboardInterrupt:
5465			pass
5466
5467
5468	def render (self, bars: typing.Optional[int] = None, filename: str = "render.mid", max_minutes: typing.Optional[float] = 60.0) -> None:
5469
5470		"""Render the composition to a MIDI file without real-time playback.
5471
5472		Runs the sequencer as fast as possible (no timing delays) and stops
5473		when the first active limit is reached.  The result is saved as a
5474		standard MIDI file that can be imported into any DAW.
5475
5476		All patterns, scheduled callbacks, and harmony logic run exactly as
5477		they would during live playback — BPM transitions, generative fills,
5478		and probabilistic gates all work in render mode.  The only difference
5479		is that time is simulated rather than wall-clock driven.
5480
5481		Parameters:
5482			bars: Number of bars to render, or ``None`` for no bar limit
5483			      (default ``None``).  When both *bars* and *max_minutes* are
5484			      active, playback stops at whichever limit is reached first.
5485			filename: Output MIDI filename (default ``"render.mid"``).
5486			max_minutes: Safety cap on the length of rendered MIDI in minutes
5487			             (default ``60.0``).  Pass ``None`` to disable the time
5488			             cap — you must then provide an explicit *bars* value.
5489
5490		Raises:
5491			ValueError: If both *bars* and *max_minutes* are ``None``, which
5492			            would produce an infinite render.
5493
5494		Examples:
5495			```python
5496			# Default: renders up to 60 minutes of MIDI content.
5497			composition.render()
5498
5499			# Render exactly 64 bars (time cap still active as backstop).
5500			composition.render(bars=64, filename="demo.mid")
5501
5502			# Render up to 5 minutes of an infinite generative composition.
5503			composition.render(max_minutes=5, filename="five_min.mid")
5504
5505			# Remove the time cap — must supply bars instead.
5506			composition.render(bars=128, max_minutes=None, filename="long.mid")
5507			```
5508		"""
5509
5510		if bars is None and max_minutes is None:
5511			raise ValueError(
5512				"render() requires at least one limit: provide bars=, max_minutes=, or both. "
5513				"Passing both as None would produce an infinite render."
5514			)
5515
5516		self._sequencer.recording = True
5517		self._sequencer.record_filename = filename
5518		self._sequencer.render_mode = True
5519		self._sequencer.render_bars = bars if bars is not None else 0
5520		self._sequencer.render_max_seconds = max_minutes * 60.0 if max_minutes is not None else None
5521		asyncio.run(self._run())
5522
5523	def _broadcast_osc_status (self, bar: int) -> None:
5524
5525		"""
5526		Send the per-bar OSC status snapshot: bar number, current tempo,
5527		and (when active) the current chord name and form section.
5528		"""
5529
5530		if self._osc_server:
5531			self._osc_server.send("/bar", bar)
5532			self._osc_server.send("/bpm", self._sequencer.current_bpm)
5533
5534			sounding = self.current_chord()
5535			if sounding is not None:
5536				self._osc_server.send("/chord", sounding.name())
5537
5538			if self._form_state:
5539				info = self._form_state.get_section_info()
5540				if info:
5541					self._osc_server.send("/section", info.name)
5542
5543	async def _run (self) -> None:
5544
5545		"""
5546		Async entry point that schedules all patterns and runs the sequencer.
5547		"""
5548
5549		# 1. Pre-calculate MIDI input indices and configure sequencer clock follow.
5550		if self._input_device is not None:
5551			self._sequencer.input_device_name = self._input_device
5552			self._sequencer.clock_follow = self._clock_follow
5553			self._sequencer.clock_device_idx = 0
5554
5555			if not self._clock_follow:
5556				# Find first additional input that wants to be the clock master.
5557				for idx, (_, _, cf) in enumerate(self._additional_inputs, start=1):
5558					if cf:
5559						self._sequencer.clock_follow = True
5560						self._sequencer.clock_device_idx = idx
5561						break
5562
5563		# Populate input device name mapping early (before opening ports) so we can
5564		# resolve CC mappings to integer device indices immediately.
5565		if self._sequencer.input_device_name:
5566			self._input_device_names[self._sequencer.input_device_name] = 0
5567			if self._input_device_alias is not None:
5568				self._input_device_names[self._input_device_alias] = 0
5569
5570		for idx, (dev_name, alias, _) in enumerate(self._additional_inputs, start=1):
5571			self._input_device_names[dev_name] = idx
5572			if alias:
5573				self._input_device_names[alias] = idx
5574
5575		# 2. Pre-calculate output device names.
5576		if self._sequencer.output_device_name:
5577			self._output_device_names[self._sequencer.output_device_name] = 0
5578			# Primary device (index 0) is open by now (_init_midi_output ran in
5579			# the Sequencer constructor), so its latency can be set safely here.
5580			if self._output_latency_ms:
5581				self._sequencer.set_device_latency(0, self._output_latency_ms)
5582
5583		# 3. Resolve name-based INPUT device ids in cc_map/cc_forward early — the
5584		# input-names map is fully populated above, and the callback thread needs
5585		# integer indices as soon as ports open.  OUTPUT names (cc_forward
5586		# output_device=, pattern device=) resolve after the additional outputs
5587		# are opened below; resolving them here matched against a map containing
5588		# only the primary and silently routed everything to device 0.
5589		for mapping in self._cc_mappings:
5590			raw = mapping.get('input_device')
5591			if isinstance(raw, str):
5592				mapping['input_device'] = self._resolve_input_device_id(raw)
5593		for fwd in self._cc_forwards:
5594			raw_in = fwd.get('input_device')
5595			if isinstance(raw_in, str):
5596				fwd['input_device'] = self._resolve_input_device_id(raw_in)
5597
5598		# 4. Share CC input mappings, forwards, and a reference to composition.data
5599		# with the sequencer BEFORE opening the ports. This ensures that any initial
5600		# messages in the OS buffer are correctly mapped as soon as the port opens.
5601		self._sequencer.cc_mappings = self._cc_mappings
5602		self._sequencer.cc_forwards = self._cc_forwards
5603		self._sequencer._composition_data = self.data
5604
5605		# Held-note input: create the tracker and resolve its channel/device
5606		# filter so the callback thread can buffer matching note events.
5607		if self._note_input is not None:
5608			if self._input_device is None and not self._additional_inputs:
5609				raise RuntimeError("note_input() requires a MIDI input — call composition.midi_input(device) first")
5610			raw_dev = self._note_input.get('input_device')
5611			if isinstance(raw_dev, str):
5612				raw_dev = self._resolve_input_device_id(raw_dev)
5613			self._sequencer._note_input_channel = self._note_input['channel']
5614			self._sequencer._note_input_device = raw_dev
5615			self._sequencer._held_notes = subsequence.held_notes.HeldNotes(
5616				release_ms = self._note_input['release_ms'],
5617				latch = self._note_input['latch'],
5618			)
5619
5620		# 5. Open MIDI input ports early. Even without a deliberate sleep, opening
5621		# them before pattern building minimizes the window for missed messages.
5622		# Primary input
5623		self._sequencer._open_midi_inputs()
5624
5625		# Additional inputs
5626		for idx, (dev_name, alias, cf) in enumerate(self._additional_inputs, start=1):
5627			# Use the pre-calculated index
5628			callback = self._sequencer._make_input_callback(idx)
5629			open_name, port = subsequence.midi_utils.select_input_device(dev_name, callback)
5630			if open_name and port is not None:
5631				self._sequencer.add_input_device(open_name, port)
5632			else:
5633				logger.warning(f"Could not open additional input device '{dev_name}'")
5634
5635		# 6. Open additional MIDI output devices.
5636		for out in self._additional_outputs:
5637			open_name, port = subsequence.midi_utils.select_output_device(out.device)
5638			if open_name and port is not None:
5639				idx = self._sequencer.add_output_device(open_name, port, out.latency_ms)
5640				self._output_device_names[open_name] = idx
5641				if out.alias is not None:
5642					self._output_device_names[out.alias] = idx
5643			else:
5644				logger.warning(f"Could not open additional output device '{out.device}'")
5645
5646		# Warn if latency compensation adds noticeable whole-rig delay: the
5647		# slowest device defines the alignment point, so every faster device is
5648		# delayed up to that amount and live-input feel suffers.
5649		self._warn_if_high_latency()
5650
5651		# Resolve any name-based output device IDs on patterns that may have been added
5652		# for additional output devices.
5653		self._resolve_pending_devices()
5654
5655		# Resolve cc_forward output-device names now that every output port and
5656		# alias is registered (resolving earlier silently routed to device 0).
5657		for fwd in self._cc_forwards:
5658			raw_out = fwd.get('output_device')
5659			if isinstance(raw_out, str):
5660				fwd['output_device'] = self._resolve_device_id(raw_out)
5661
5662		# Pass clock output flag (suppressed automatically when clock_follow=True).
5663		self._sequencer.clock_output = self._clock_output and not self.is_clock_following
5664
5665		# Create Ableton Link clock if comp.link() was called.
5666		if self._link_quantum is not None:
5667			self._sequencer._link_clock = subsequence.link_clock.LinkClock(
5668				bpm = self.bpm,
5669				quantum = self._link_quantum,
5670				loop = asyncio.get_running_loop(),
5671			)
5672
5673		# Deal play-time streams.  Every stream is NAME-keyed (crc32 of
5674		# "seed:name", see _stream_seed) rather than dealt from one master in
5675		# registration order: adding or removing one consumer can never shift
5676		# another's stream, and patterns added live derive identically in
5677		# _build_pattern_from_pending.  When no seed is set, components keep
5678		# their own unseeded RNGs (existing behaviour).
5679		if self._seed is not None:
5680
5681			harmony_stream = self._stream("play:harmony")
5682			if self._harmonic_state is not None and harmony_stream is not None:
5683				self._harmonic_state.rng = harmony_stream
5684
5685			form_stream = self._stream("play:form")
5686			if self._form_state is not None and form_stream is not None:
5687				self._form_state._rng = form_stream
5688
5689		# The clocks fire BEFORE pattern rebuilds at the same pulse, and their
5690		# lookahead is RAISED to the maximum pattern lookahead (never patterns
5691		# clamped down): when a pattern rebuilds for its next cycle, the form
5692		# state and the harmony window already describe that cycle.
5693		bar_beats = float(self.time_signature[0])
5694
5695		pattern_lookaheads = [pending.reschedule_lookahead for pending in self._pending_patterns]
5696		pattern_lookaheads += [pattern.reschedule_lookahead for pattern in self._running_patterns.values()]
5697		max_pattern_lookahead = max(pattern_lookaheads, default = 1)
5698
5699		clock_lookahead = max(1.0, float(self._harmony_reschedule_lookahead), float(max_pattern_lookahead))
5700
5701		if clock_lookahead > bar_beats:
5702			logger.warning(
5703				"A pattern's reschedule_lookahead (%.2g beats) exceeds the bar length (%.2g) — "
5704				"the harmony/form clocks fire at most one bar ahead, so that pattern may "
5705				"rebuild before the window covers its cycle start.",
5706				clock_lookahead, bar_beats,
5707			)
5708			clock_lookahead = bar_beats
5709
5710		# Minimum span >= maximum lookahead: the clock cannot prepare a chord
5711		# boundary that arrives sooner than it fires.  Harmonic motion faster
5712		# than this floor stays available at the part level (p.progression),
5713		# where placement is not clock-bound.
5714		def _check_span_floor (progression: typing.Optional[Progression], label: str) -> None:
5715			if progression is None:
5716				return
5717			shortest = min(span.beats for span in progression.spans)
5718			if shortest < clock_lookahead - 1e-9:
5719				raise ValueError(
5720					f"{label}: shortest chord span ({shortest:g} beats) is below the clock "
5721					f"lookahead ({clock_lookahead:g} beats — the largest pattern lookahead). "
5722					"Lengthen the span, lower the pattern lookaheads, or place fast harmony "
5723					"at the part level with p.progression()."
5724				)
5725
5726		_check_span_floor(self._bound_progression, "harmony(progression=)")
5727		for section_name, section_progression in self._section_progressions.items():
5728			_check_span_floor(section_progression, f"section_chords({section_name!r})")
5729
5730		# Key-relative section progressions resolve late, per occurrence — so
5731		# verify they WILL resolve now, before playback, rather than surfacing
5732		# a silent skip (or a dead clock) mid-render.  For each occurrence's
5733		# effective key+scale: a missing key, or a degree/scale that does not
5734		# resolve, is raised here with an actionable message.
5735		fs = self._form_state
5736
5737		for section_name, section_progression in self._section_progressions.items():
5738			if section_progression.is_concrete:
5739				continue
5740
5741			# The (key, scale) contexts this section may be resolved against.
5742			contexts: typing.List[typing.Tuple[typing.Optional[str], typing.Optional[str]]] = []
5743			if fs is not None and fs._sequence is not None and any(s.name == section_name for s in fs._sequence):
5744				for section in fs._sequence:
5745					if section.name != section_name:
5746						continue
5747					ctx = (section.key or self._form_key or self.key, section.scale or self._form_scale or self.scale)
5748					if ctx not in contexts:
5749						contexts.append(ctx)
5750			else:
5751				contexts.append((self._form_key or self.key, self._form_scale or self.scale))
5752
5753			for ctx_key, ctx_scale in contexts:
5754				if ctx_key is None:
5755					raise ValueError(
5756						f"section_chords({section_name!r}) is key-relative (degrees/romans) but no key "
5757						"resolves for it — set key= on the Composition, a form key (form(key=...)), or "
5758						f"a Section.key on every {section_name!r} section."
5759					)
5760				try:
5761					section_progression.resolve(ctx_key, ctx_scale or "ionian")
5762				except ValueError as error:
5763					raise ValueError(
5764						f"section_chords({section_name!r}) does not resolve against its effective key "
5765						f"{ctx_key} {ctx_scale or 'ionian'}: {error}"
5766					)
5767
5768		# min_energy with nothing feeding p.energy is a silent no-op — warn loudly.
5769		energy_gated = [p.builder_fn.__name__ for p in self._pending_patterns if p.min_energy is not None]
5770
5771		if energy_gated and not self._energy_map and not self._form_has_payload:
5772			logger.warning(
5773				f"min_energy is set on {', '.join(energy_gated)} but no energy source is "
5774				"configured — p.energy is always 0.5 (call composition.energy() or bind a "
5775				"Form whose Sections carry energy)"
5776			)
5777
5778		# The form clock MUST be registered before the harmonic clock: same-pulse
5779		# fixed callbacks fire in registration order (and all fixed callbacks fire
5780		# before callback sequences), and on a section-boundary bar the harmonic
5781		# clock reads the current section (via _get_section_progression) to decide
5782		# whether to walk that section's chords.  Registering harmony first would
5783		# make it read the OLD section on every boundary, shifting section_chords()
5784		# replays by one bar and bleeding them across sections.
5785		if self._form_state is not None:
5786
5787			await schedule_form(
5788				sequencer = self._sequencer,
5789				form_state = self._form_state,
5790				reschedule_lookahead = clock_lookahead,
5791				on_bar = self._check_transitions,
5792				# Re-read every bar so a mid-playback form() re-bind advances
5793				# the NEW state instead of the abandoned object.
5794				get_form_state = lambda: self._form_state,
5795			)
5796
5797		self._harmony_horizon.reset()
5798		self._harmonic_clock_started = False
5799
5800		if self._harmonic_state is not None or self._bound_progression is not None or self._section_progressions:
5801			await self._start_harmonic_clock(bar_beats, clock_lookahead)
5802
5803		# Bar counter - always active so p.bar is available to all builders.
5804		def _advance_builder_bar (pulse: int) -> None:
5805			self._builder_bar += 1
5806
5807		first_bar_pulse = int(self.time_signature[0] * self._sequencer.pulses_per_beat)
5808
5809		await self._sequencer.schedule_callback_repeating(
5810			callback = _advance_builder_bar,
5811			interval_beats = self.time_signature[0],
5812			start_pulse = first_bar_pulse,
5813			# Same raised lookahead as the form/harmony clocks: a pattern
5814			# rebuilding lookahead-early for its next cycle must read the bar
5815			# that cycle starts in, not the previous one.
5816			reschedule_lookahead = clock_lookahead
5817		)
5818
5819		# Run wait_for_initial=True scheduled functions and block until all complete.
5820		# This ensures composition.data is populated before patterns build.
5821		initial_tasks = [t for t in self._pending_scheduled if t.wait_for_initial]
5822
5823		if initial_tasks:
5824
5825			names = ", ".join(getattr(t.fn, '__name__', repr(t.fn)) for t in initial_tasks)
5826			logger.info(f"Waiting for initial scheduled {'function' if len(initial_tasks) == 1 else 'functions'} before start: {names}")
5827
5828			async def _run_initial (fn: typing.Callable) -> None:
5829
5830				accepts_ctx = _fn_has_parameter(fn, "p")
5831				ctx = ScheduleContext(cycle=0)
5832
5833				try:
5834					if inspect.iscoroutinefunction(fn):
5835						await (fn(ctx) if accepts_ctx else fn())
5836					else:
5837						loop = asyncio.get_running_loop()
5838						call = (lambda: fn(ctx)) if accepts_ctx else fn
5839						await loop.run_in_executor(None, call)
5840				except Exception as exc:
5841					logger.warning(f"Initial run of {getattr(fn, '__name__', repr(fn))!r} failed: {exc}")
5842
5843			await asyncio.gather(*[_run_initial(t.fn) for t in initial_tasks])
5844
5845		for pending_task in self._pending_scheduled:
5846
5847			accepts_ctx = _fn_has_parameter(pending_task.fn, "p")
5848
5849			# A wait_for_initial task already ran once as cycle 0 (the blocking
5850			# pre-roll above), so its repeating wrapper starts at cycle 1 — keeping
5851			# ScheduleContext.cycle monotonic across the initial and repeating runs.
5852			wrapped = _make_safe_callback(
5853				pending_task.fn,
5854				accepts_context = accepts_ctx,
5855				start_cycle = 1 if pending_task.wait_for_initial else 0,
5856			)
5857
5858			# wait_for_initial=True implies defer — no point firing at pulse 0
5859			# after the blocking run just completed.  defer=True skips the
5860			# backshift fire so the first repeating call happens one full cycle
5861			# later.
5862			if pending_task.wait_for_initial or pending_task.defer:
5863				start_pulse = int(pending_task.cycle_beats * self._sequencer.pulses_per_beat)
5864			else:
5865				start_pulse = 0
5866
5867			await self._sequencer.schedule_callback_repeating(
5868				callback = wrapped,
5869				interval_beats = pending_task.cycle_beats,
5870				start_pulse = start_pulse,
5871				reschedule_lookahead = pending_task.reschedule_lookahead
5872			)
5873
5874		# Build Pattern objects from pending registrations.
5875		patterns: typing.List[subsequence.pattern.Pattern] = []
5876
5877		for i, pending in enumerate(self._pending_patterns):
5878
5879			pattern = self._build_pattern_from_pending(pending)
5880			patterns.append(pattern)
5881
5882		await schedule_patterns(
5883			sequencer = self._sequencer,
5884			patterns = patterns,
5885			start_pulse = 0
5886		)
5887
5888		# Populate the running patterns dict for live hot-swap and mute/unmute.
5889		for i, pending in enumerate(self._pending_patterns):
5890			name = pending.builder_fn.__name__
5891			self._running_patterns[name] = patterns[i]
5892
5893		# Everything pending is running now; drop the declarations so a later
5894		# live reload cannot graduate stale copies.
5895		self._pending_patterns = []
5896
5897		if self._display is not None and not self._sequencer.render_mode:
5898			self._display.start()
5899			self._sequencer.on_event("bar",  self._display.update)
5900			self._sequencer.on_event("beat", self._display.update)
5901
5902		if self._live_server is not None:
5903			await self._live_server.start()
5904
5905		if self._osc_server is not None:
5906			await self._osc_server.start()
5907			self._sequencer.osc_server = self._osc_server
5908			self._sequencer.on_event("bar", self._broadcast_osc_status)
5909
5910		# Start keystroke listener if hotkeys are enabled and not in render mode.
5911		if self._hotkeys_enabled and not self._sequencer.render_mode:
5912			self._keystroke_listener = subsequence.keystroke.KeystrokeListener()
5913			self._keystroke_listener.start()
5914
5915			if self._keystroke_listener.active:
5916				# Listener started successfully — register the bar handler
5917				# and show all bindings so the user knows what's available.
5918				self._sequencer.on_event("bar", self._process_hotkeys)
5919				self._list_hotkeys()
5920			# If not active, KeystrokeListener.start() already logged a warning.
5921
5922		if self._web_ui_enabled and not self._sequencer.render_mode:
5923			self._web_ui_server = subsequence.web_ui.WebUI(self, http_host=self._web_ui_http_host, ws_host=self._web_ui_ws_host)
5924			self._web_ui_server.start()
5925
5926		try:
5927			await run_until_stopped(self._sequencer)
5928		finally:
5929			# Tear down every service even if run_until_stopped (or an earlier
5930			# stop) raised, and guard each individually, so one failure can't
5931			# strand the rest — most importantly the keystroke listener's
5932			# terminal restore.
5933			if self._web_ui_server is not None:
5934				try:
5935					self._web_ui_server.stop()
5936				except Exception:
5937					logger.exception("Error stopping web UI")
5938
5939			if self._live_server is not None:
5940				try:
5941					await self._live_server.stop()
5942				except Exception:
5943					logger.exception("Error stopping live server")
5944
5945			if self._live_reloader is not None:
5946				try:
5947					self._live_reloader.stop()
5948				except Exception:
5949					logger.exception("Error stopping live reloader")
5950
5951			if self._osc_server is not None:
5952				try:
5953					await self._osc_server.stop()
5954				except Exception:
5955					logger.exception("Error stopping OSC server")
5956				self._sequencer.osc_server = None
5957
5958			if self._display is not None:
5959				try:
5960					self._display.stop()
5961				except Exception:
5962					logger.exception("Error stopping display")
5963
5964			if self._keystroke_listener is not None:
5965				try:
5966					self._keystroke_listener.stop()
5967				except Exception:
5968					logger.exception("Error stopping keystroke listener")
5969				self._keystroke_listener = None
5970
5971	def _build_pattern_from_pending (self, pending: _PendingPattern, start_pulse: int = 0) -> subsequence.pattern.Pattern:
5972
5973		"""
5974		Create a Pattern from a pending registration using a temporary subclass.
5975
5976		The pattern's play stream is dealt here, keyed by NAME (crc32 of
5977		"seed:name" plus any reroll nonce), so registration order is
5978		irrelevant and a pattern added live gets exactly the stream it would
5979		have had at startup.  ``start_pulse`` anchors the first cycle on the
5980		beat axis so the initial build reads the harmony window at the right
5981		place (the sequencer keeps the anchor current on every reschedule).
5982		"""
5983
5984		composition_ref = self
5985		rng = self._stream(pending.builder_fn.__name__)
5986
5987		class _DecoratorPattern (subsequence.pattern.Pattern):
5988
5989			"""
5990			Pattern subclass that delegates to a builder function on each reschedule.
5991			"""
5992
5993			def __init__ (self, pending: _PendingPattern, pattern_rng: typing.Optional[random.Random] = None) -> None:
5994
5995				"""
5996				Initialize the decorator pattern from pending registration details.
5997				"""
5998
5999				super().__init__(
6000					channel = pending.channel,
6001					length = pending.length,
6002					reschedule_lookahead = pending.reschedule_lookahead,
6003					device = pending.device,
6004					mirrors = pending.mirrors,
6005				)
6006
6007				self._builder_fn = pending.builder_fn
6008				self._drum_note_map = pending.drum_note_map
6009				self._cc_name_map = pending.cc_name_map
6010				self._nrpn_name_map = pending.nrpn_name_map
6011				self._default_grid: int = pending.default_grid
6012				self._wants_chord = _fn_has_parameter(pending.builder_fn, "chord")
6013				self._cycle_count = 0
6014				self._rng = pattern_rng
6015				self._muted = False
6016				self._min_energy = pending.min_energy
6017				self._energy_gated = False
6018				self._voice_leading_state: typing.Optional[subsequence.voicings.VoiceLeadingState] = (
6019					subsequence.voicings.VoiceLeadingState() if pending.voice_leading else None
6020				)
6021				self._tweaks: typing.Dict[str, typing.Any] = {}
6022
6023				# Anchor of the cycle being built, on the absolute pulse axis.
6024				# The sequencer updates this on every reschedule; the initial
6025				# value is the pattern's first scheduled start.
6026				self._cycle_start_pulse = start_pulse
6027
6028				self._rebuild()
6029
6030			def _rebuild (self) -> None:
6031
6032				"""
6033				Clear steps and call the builder function to repopulate.
6034				"""
6035
6036				self.steps = {}
6037				self.cc_events = []
6038				self.osc_events = []
6039				self.raw_note_events = []
6040				current_cycle = self._cycle_count
6041				self._cycle_count += 1
6042
6043				# lock(): re-deal the stream from its effective seed every
6044				# rebuild so a locked pattern realizes identically each cycle.
6045				# Checked here (engine-side) so it survives live reload.
6046				if self._builder_fn.__name__ in composition_ref._locked_names:
6047					locked_seed = composition_ref._stream_seed(self._builder_fn.__name__)
6048					if locked_seed is not None:
6049						self._rng = random.Random(locked_seed)
6050
6051				if self._muted:
6052					return
6053
6054				section_info = composition_ref._form_state.get_section_info() if composition_ref._form_state else None
6055				energy = composition_ref._current_energy(section_info)
6056				effective_key, effective_scale = composition_ref._effective_key_scale(section_info)
6057
6058				# Automatic energy gating: below the threshold the pattern is
6059				# silent this cycle (composing with _muted — a performer mute
6060				# always wins).  Gate flips log once.
6061				if self._min_energy is not None:
6062					gated = energy < self._min_energy
6063
6064					if gated != self._energy_gated:
6065						state_word = "closed" if gated else "open"
6066						logger.info(
6067							f"Pattern '{self._builder_fn.__name__}': energy gate {state_word} "
6068							f"(energy {energy:.2f}, min_energy {self._min_energy:g})"
6069						)
6070						self._energy_gated = gated
6071
6072					if gated:
6073						return
6074
6075				# The harmony view for this cycle, anchored at its start beat —
6076				# under variable harmonic rhythm the window, not the engine's
6077				# mutating singleton, is the source of truth.
6078				harmony_view: typing.Optional[HarmonyView] = None
6079
6080				if not composition_ref._harmony_horizon.is_empty:
6081					origin_beat = self._cycle_start_pulse / composition_ref._sequencer.pulses_per_beat
6082					harmony_view = HarmonyView(composition_ref._harmony_horizon, origin_beat)
6083
6084				builder = subsequence.pattern_builder.PatternBuilder(
6085					pattern = self,
6086					cycle = current_cycle,
6087					drum_note_map = self._drum_note_map,
6088					cc_name_map = self._cc_name_map,
6089					nrpn_name_map = self._nrpn_name_map,
6090					section = section_info,
6091					bar = composition_ref._builder_bar,
6092					conductor = composition_ref.conductor,
6093					rng = self._rng,
6094					tweaks = self._tweaks,
6095					default_grid = self._default_grid,
6096					data = composition_ref.data,
6097					# The effective key/scale re-anchors key-relative content
6098					# (degrees, romans, generated material) to the section /
6099					# form / composition tier in force — mode travels too.
6100					key = effective_key,
6101					scale = effective_scale,
6102					time_signature = composition_ref.time_signature,
6103					held_notes = composition_ref._sequencer._held_notes,
6104					harmony = harmony_view,
6105					section_motifs = composition_ref._section_motifs,
6106					energy = energy,
6107					# So p.scratch() can take a child stream keyed off this
6108					# pattern's, rather than drawing from the pattern's own.
6109					stream_seed = composition_ref._stream_seed(self._builder_fn.__name__),
6110				)
6111
6112				try:
6113
6114					if self._wants_chord:
6115
6116						# The two-parameter convention: the injected chord is
6117						# the cycle-start snapshot from the window (falling
6118						# back to the engine before the clock has run).
6119						chord = harmony_view.chord if harmony_view is not None else (
6120							composition_ref._harmonic_state.get_current_chord()
6121							if composition_ref._harmonic_state is not None else None
6122						)
6123
6124						if chord is not None:
6125							injected = _InjectedChord(
6126								chord,
6127								self._voice_leading_state,
6128								next_chord = harmony_view.next_chord if harmony_view is not None else None,
6129								beats_remaining = harmony_view.until_change if harmony_view is not None else None,
6130							)
6131							self._builder_fn(builder, injected)
6132						else:
6133							self._builder_fn(builder)
6134
6135					else:
6136						self._builder_fn(builder)
6137
6138				except Exception:
6139					# Discard whatever the builder placed before it raised —
6140					# otherwise a half-built pattern plays and the log lies.
6141					self.steps = {}
6142					self.cc_events = []
6143					self.osc_events = []
6144					self.raw_note_events = []
6145					logger.exception("Error in pattern builder '%s' (cycle %d) - pattern will be silent this cycle", self._builder_fn.__name__, current_cycle)
6146
6147				# Auto-apply global tuning if set and not already applied by the builder.
6148				if (
6149					composition_ref._tuning is not None
6150					and not builder._tuning_applied
6151					and not (composition_ref._tuning_exclude_drums and self._drum_note_map)
6152				):
6153					import subsequence.tuning as _tuning_mod
6154					_tuning_mod.apply_tuning_to_pattern(
6155						self,
6156						composition_ref._tuning,
6157						bend_range=composition_ref._tuning_bend_range,
6158						channels=composition_ref._tuning_channels,
6159						reference_note=composition_ref._tuning_reference_note,
6160					)
6161
6162			def on_reschedule (self) -> None:
6163
6164				"""
6165				Rebuild the pattern from the builder function before the next cycle.
6166				"""
6167
6168				self._rebuild()
6169
6170		return _DecoratorPattern(pending, rng)