subsequence

1023class Composition:
1024
1025	"""
1026	The top-level controller for a musical piece.
1027	
1028	The `Composition` object manages the global clock (Sequencer), the harmonic
1029	progression (HarmonicState), the song structure (subsequence.form_state.FormState), and all MIDI patterns.
1030	It serves as the main entry point for defining your music.
1031	
1032	Typical workflow:
1033	1. Initialize `Composition` with BPM and Key.
1034	2. Define harmony and form (optional).
1035	3. Register patterns using the `@composition.pattern` decorator.
1036	4. Call `composition.play()` to start the music.
1037	"""
1038
1039	def __init__ (
1040		self,
1041		output_device: typing.Optional[str] = None,
1042		bpm: float = 120,
1043		time_signature: typing.Tuple[int, int] = (4, 4),
1044		key: typing.Optional[str] = None,
1045		scale: typing.Optional[str] = None,
1046		seed: typing.Optional[int] = None,
1047		record: bool = False,
1048		record_filename: typing.Optional[str] = None,
1049		zero_indexed_channels: bool = False,
1050		latency_ms: float = 0.0
1051	) -> None:
1052
1053		"""
1054		Initialize a new composition.
1055
1056		Parameters:
1057			output_device: The exact name of the MIDI output port to use,
1058				as reported by ``mido.get_output_names()``. Matching is
1059				strict — the string must equal an entry in that list
1060				verbatim. On Linux/ALSA, names include the client and
1061				port IDs (e.g.
1062				``"Scarlett 2i4 USB:Scarlett 2i4 USB MIDI 1 16:0"``); the
1063				trailing ``:client:port`` digits are assigned in
1064				connection order and can change between reboots or when
1065				a virtual port is recreated. To look up the current
1066				names::
1067
1068				    import mido
1069				    for n in mido.get_output_names(): print(n)
1070
1071				If `None`, Subsequence auto-discovers — uses the only
1072				available device, or prompts to choose if several exist.
1073			bpm: Initial tempo in beats per minute (default 120).
1074			key: The root key of the piece (e.g., "C", "F#", "Bb").
1075				Required if you plan to use `harmony()`.
1076			scale: The scale/mode of the piece (e.g. "minor", "dorian",
1077				or any registered scale name).  Used to resolve scale
1078				degrees in motifs; defaults to major (ionian) when unset.
1079			seed: An optional integer for deterministic randomness. When set,
1080				every random decision (chord choices, drum probability, etc.)
1081				will be identical on every run.
1082			record: When True, record all MIDI events to a file.
1083			record_filename: Optional filename for the recording (defaults to timestamp).
1084			zero_indexed_channels: When False (default), MIDI channels use
1085				1-based numbering (1-16) matching instrument labelling.
1086				Channel 10 is drums, the way musicians and hardware panels
1087				show it. When True, channels use 0-based numbering (0-15)
1088				matching the raw MIDI protocol.
1089			latency_ms: Physical output latency of the primary device in
1090				milliseconds, for delay compensation (default 0.0, must be
1091				non-negative). Set this when the primary output sounds late
1092				(e.g. a software sampler) so Subsequence delays faster
1093				devices to line everything up. See ``midi_output()`` for
1094				additional devices.
1095
1096		Example:
1097			```python
1098			comp = subsequence.Composition(bpm=128, key="Eb", seed=123)
1099			```
1100		"""
1101
1102		if latency_ms < 0:
1103			raise ValueError(f"latency_ms must be non-negative — got {latency_ms}")
1104
1105		self.output_device = output_device
1106		self.bpm = bpm
1107		self.time_signature = time_signature
1108		self.key = key
1109		self.scale = scale
1110		self._seed: typing.Optional[int] = seed
1111		self._zero_indexed_channels: bool = zero_indexed_channels
1112		self._output_latency_ms: float = latency_ms
1113
1114		# Determinism plumbing: named-stream derivation state.  Build-time
1115		# consumers draw per-call-salted streams (freeze:1, harmony:2, ...) so
1116		# adding one call never shifts another's stream; play-time pattern
1117		# streams are name-keyed in _build_pattern_from_pending.
1118		self._freeze_count: int = 0
1119		self._harmony_count: int = 0
1120		self._form_count: int = 0
1121		self._reroll_nonces: typing.Dict[str, int] = {}
1122		self._locked_names: typing.Set[str] = set()
1123
1124		self._sequencer = subsequence.sequencer.Sequencer(
1125			output_device_name = output_device,
1126			initial_bpm = bpm,
1127			time_signature = time_signature,
1128			record = record,
1129			record_filename = record_filename
1130		)
1131
1132		self._harmonic_state: typing.Optional[subsequence.harmonic_state.HarmonicState] = None
1133		self._harmony_cycle_beats: typing.Optional[int] = None
1134		self._harmony_reschedule_lookahead: float = 1
1135		self._section_progressions: typing.Dict[str, Progression] = {}
1136		self._bound_progression: typing.Optional[Progression] = None
1137		self._pinned_chords: typing.Dict[int, typing.Any] = {}
1138		self._harmony_horizon = _HarmonyHorizon()
1139		self._section_motifs: typing.Dict[typing.Tuple[str, typing.Optional[str]], typing.Any] = {}
1140		self._pending_patterns: typing.List[_PendingPattern] = []
1141		# Names of patterns declared by the most recent live-reload exec (added by
1142		# pattern()/layer() as they run); the deletion diff in _apply_source_async
1143		# tears down any running pattern absent from this set.
1144		self._declared_names: typing.Set[str] = set()
1145		self._pending_scheduled: typing.List[_PendingScheduled] = []
1146		self._form_state: typing.Optional[subsequence.form_state.FormState] = None
1147		self._builder_bar: int = 0
1148		self._display: typing.Optional[subsequence.display.Display] = None
1149		self._live_server: typing.Optional[subsequence.live_server.LiveServer] = None
1150		self._live_reloader: typing.Optional[subsequence.live_reloader.LiveReloader] = None
1151		self._is_live: bool = False
1152		self._running_patterns: typing.Dict[str, typing.Any] = {}
1153		self._input_device: typing.Optional[str] = None
1154		self._input_device_alias: typing.Optional[str] = None
1155		self._clock_follow: bool = False
1156		self._clock_output: bool = False
1157		self._cc_mappings: typing.List[typing.Dict[str, typing.Any]] = []
1158		self._cc_forwards: typing.List[typing.Dict[str, typing.Any]] = []
1159		# Held-note input config from note_input() (None = not declared).
1160		self._note_input: typing.Optional[typing.Dict[str, typing.Any]] = None
1161		# Additional output devices registered with midi_output() after construction.
1162		self._additional_outputs: typing.List[_AdditionalOutput] = []
1163		# Additional input devices: (device_name: str, alias: Optional[str], clock_follow: bool)
1164		self._additional_inputs: typing.List[typing.Tuple[str, typing.Optional[str], bool]] = []
1165		# Maps alias/name → output device index (populated in _run after all devices are opened).
1166		self._output_device_names: typing.Dict[str, int] = {}
1167		# Maps alias/name → input device index (populated in _run after all input devices are opened).
1168		self._input_device_names: typing.Dict[str, int] = {}
1169		self.data: typing.Dict[str, typing.Any] = {}
1170		self._osc_server: typing.Optional[subsequence.osc.OscServer] = None
1171		self.conductor = subsequence.conductor.Conductor()
1172		self._web_ui_enabled: bool = False
1173		self._web_ui_http_host: str = "127.0.0.1"
1174		self._web_ui_ws_host: str = "127.0.0.1"
1175		self._web_ui_server: typing.Optional[subsequence.web_ui.WebUI] = None
1176		self._link_quantum: typing.Optional[float] = None
1177
1178		# Hotkey state — populated by hotkeys() and hotkey().
1179		self._hotkeys_enabled: bool = False
1180		self._hotkey_bindings: typing.Dict[str, HotkeyBinding] = {}
1181		self._pending_hotkey_actions: typing.List[_PendingHotkeyAction] = []
1182		self._keystroke_listener: typing.Optional[subsequence.keystroke.KeystrokeListener] = None
1183
1184		# Tuning state — populated by tuning().
1185		self._tuning: typing.Optional[typing.Any] = None       # subsequence.tuning.Tuning
1186		self._tuning_bend_range: float = 2.0
1187		self._tuning_channels: typing.Optional[typing.List[int]] = None
1188		self._tuning_reference_note: int = 60
1189		self._tuning_exclude_drums: bool = True
1190
1191	def _resolve_device_id (self, device: subsequence.midi_utils.DeviceId) -> int:
1192		"""Resolve an output device id (None/int/str) to an integer index.
1193
1194		``None`` → 0 (primary device).  ``int`` → returned as-is.
1195		``str`` → looked up in ``_output_device_names``; logs a warning and
1196		returns 0 if the name is unknown (called after all devices are opened
1197		in ``_run()``).
1198		"""
1199		if device is None:
1200			return 0
1201		if isinstance(device, int):
1202			return device
1203		idx = self._output_device_names.get(device)
1204		if idx is None:
1205			logger.warning(
1206				f"Unknown output device name '{device}' — routing to device 0. "
1207				f"Available names: {list(self._output_device_names.keys())}"
1208			)
1209			return 0
1210		return idx
1211
1212	def _resolve_input_device_id (self, device: subsequence.midi_utils.DeviceId) -> typing.Optional[int]:
1213		"""Resolve an input device id (None/int/str) to an integer index.
1214
1215		``None`` → ``None`` (matches any input device — existing behaviour).
1216		``int`` → returned as-is.  ``str`` → looked up in ``_input_device_names``;
1217		logs a warning and returns ``None`` if the name is unknown.
1218		Called after all input devices are opened in ``_run()``.
1219		"""
1220		if device is None:
1221			return None
1222		if isinstance(device, int):
1223			return device
1224		idx = self._input_device_names.get(device)
1225		if idx is None:
1226			logger.warning(
1227				f"Unknown input device name '{device}' — mapping will be ignored. "
1228				f"Available names: {list(self._input_device_names.keys())}"
1229			)
1230			return None
1231		return idx
1232
1233	def _resolve_pending_devices (self) -> None:
1234		"""Resolve name-based device ids on pending patterns now that all output devices are open."""
1235		for pending in self._pending_patterns:
1236			if isinstance(pending.raw_device, str):
1237				pending.device = self._resolve_device_id(pending.raw_device)
1238
1239	async def _activate_new_pending_patterns (self) -> None:
1240
1241		"""Build and schedule any pending patterns whose names are not yet running.
1242
1243		Used by ``LiveReloader._reload_async`` to bring NEW patterns added
1244		in a live reload into rotation mid-flight.  Existing patterns
1245		hot-swap via the decorator (their ``_builder_fn`` is replaced in
1246		place); only patterns whose names are not yet in ``_running_patterns``
1247		need this graduation step.
1248
1249		Newly-scheduled patterns start at the current sequencer pulse —
1250		they'll generate events from now onward, and the next reschedule
1251		will fire at the same offset as their primary cycle.
1252		"""
1253
1254		# Resolve any deferred string-device names against the now-open
1255		# device registry (no-op for int/None devices).
1256		self._resolve_pending_devices()
1257
1258		# Dedupe by name, last declaration wins — re-declaring a pattern in a
1259		# reloaded source must not schedule two copies.
1260		new_by_name: typing.Dict[str, _PendingPattern] = {}
1261
1262		for pending in self._pending_patterns:
1263			if pending.builder_fn.__name__ not in self._running_patterns:
1264				new_by_name[pending.builder_fn.__name__] = pending
1265
1266		new_pending = list(new_by_name.values())
1267
1268		if not new_pending:
1269			return
1270
1271		current_pulse = self._sequencer.pulse_count
1272
1273		for pending in new_pending:
1274
1275			pattern = self._build_pattern_from_pending(pending, start_pulse = current_pulse)
1276			await self._sequencer.schedule_pattern_repeating(pattern, start_pulse = current_pulse)
1277			self._running_patterns[pending.builder_fn.__name__] = pattern
1278
1279			logger.info(f"Live-reload: scheduled new pattern '{pending.builder_fn.__name__}'")
1280
1281		# Prune graduated (and stale duplicate) declarations: leaving them in
1282		# _pending_patterns resurrected deleted patterns on every later reload.
1283		self._pending_patterns = [
1284			pending for pending in self._pending_patterns
1285			if pending.builder_fn.__name__ not in self._running_patterns
1286		]
1287
1288	def _resolve_channel (self, channel: int) -> int:
1289
1290		"""
1291		Convert a user-supplied MIDI channel to the 0-indexed value used internally.
1292
1293		When ``zero_indexed_channels`` is False (default), the channel is
1294		validated as 1-16 and decremented by one. When True (0-indexed), the
1295		channel is validated as 0-15 and returned unchanged.
1296		"""
1297
1298		if self._zero_indexed_channels:
1299			if not 0 <= channel <= 15:
1300				raise ValueError(f"MIDI channel must be 0-15 (zero_indexed_channels=True), got {channel}")
1301			return channel
1302		else:
1303			if not 1 <= channel <= 16:
1304				raise ValueError(f"MIDI channel must be 1-16, got {channel}")
1305			return channel - 1
1306
1307	def _resolve_mirrors (
1308		self,
1309		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]],
1310		primary: typing.Optional[typing.Tuple[int, int]] = None,
1311	) -> typing.List[subsequence.pattern.MirrorSpec]:
1312
1313		"""
1314		Validate and normalise a list of mirror destinations.
1315
1316		Each entry is a 2- or 3-element sequence — ``(device_idx, channel)`` or
1317		``(device_idx, channel, drum_note_map)`` — as a tuple, list, or any such
1318		iterable.  ``channel`` is expressed in the user's channel-numbering
1319		convention (1-16 by default, 0-15 when ``zero_indexed_channels=True``);
1320		this method converts it to canonical 0-indexed form and rejects
1321		malformed entries.  The optional ``drum_note_map`` is preserved verbatim
1322		so the sequencer can re-resolve mirrored drum names per device.
1323
1324		String device names are NOT supported here; users wanting a named
1325		device should pass the integer index returned from ``midi_output()``.
1326
1327		If ``primary=(device, channel)`` is supplied (canonical 0-indexed
1328		form), a mirror entry whose ``(device, channel)`` matches it triggers a
1329		``logger.warning`` — this is almost always a user error (every event
1330		would double-fire on the same destination).  The optional map is ignored
1331		for this comparison.  Skipped when ``primary`` is ``None``, since the
1332		runtime API call site supplies its own check.
1333		"""
1334
1335		if mirrors is None:
1336			return []
1337
1338		resolved: typing.List[subsequence.pattern.MirrorSpec] = []
1339
1340		for entry in mirrors:
1341
1342			# Accept any 2- or 3-element iterable (tuple, list, etc.) — config
1343			# files and JSON sources naturally produce lists.  Validate shape at
1344			# decoration time so bad inputs surface here instead of producing
1345			# inscrutable failures inside the sequencer.
1346			try:
1347				items = list(entry)
1348			except TypeError:
1349				raise ValueError(f"Mirror entry must be a (device, channel[, drum_note_map]) tuple — got {entry!r}")
1350
1351			if len(items) not in (2, 3):
1352				raise ValueError(f"Mirror entry must have 2 or 3 elements (device, channel[, drum_note_map]) — got {entry!r}")
1353
1354			device = items[0]
1355			channel = items[1]
1356			drum_map = items[2] if len(items) == 3 else None
1357
1358			if not isinstance(device, int) or isinstance(device, bool):
1359				raise ValueError(f"Mirror device must be an integer index — got {type(device).__name__} ({device!r})")
1360
1361			if not isinstance(channel, int) or isinstance(channel, bool):
1362				raise ValueError(f"Mirror channel must be an integer — got {type(channel).__name__} ({channel!r})")
1363
1364			if drum_map is not None and not isinstance(drum_map, dict):
1365				raise ValueError(f"Mirror drum_note_map must be a dict or None — got {type(drum_map).__name__} ({drum_map!r})")
1366
1367			resolved_channel = self._resolve_channel(channel)
1368
1369			if primary is not None and (device, resolved_channel) == primary:
1370				logger.warning(
1371					f"Mirror destination {(device, resolved_channel)} matches the pattern's primary destination "
1372					f"— every event will double-fire on this (device, channel).  This is almost "
1373					f"certainly unintended."
1374				)
1375
1376			resolved_entry: subsequence.pattern.MirrorSpec = (
1377				(device, resolved_channel)
1378				if drum_map is None
1379				else (device, resolved_channel, drum_map)
1380			)
1381			resolved.append(resolved_entry)
1382
1383		return resolved
1384
1385	@property
1386	def harmonic_state (self) -> typing.Optional[subsequence.harmonic_state.HarmonicState]:
1387		"""The active ``HarmonicState``, or ``None`` if ``harmony()`` has not been called."""
1388		return self._harmonic_state
1389
1390	def current_chord (self) -> typing.Optional[typing.Any]:
1391
1392		"""The chord sounding at the playhead, or ``None`` without harmony.
1393
1394		Reads the harmony window at the current pulse, so it stays accurate
1395		under variable harmonic rhythm and clock lookahead (the engine's
1396		``current_chord`` flips *lookahead* beats early — this does not).
1397		Falls back to the engine's chord before playback starts.  The chord
1398		may be a decorated wrapper (``Am9``, ``C/G``) when the sounding span
1399		is spiced; it duck-types the ``Chord`` voicing protocol either way.
1400		"""
1401
1402		if not self._harmony_horizon.is_empty:
1403			beat = self._sequencer.pulse_count / self._sequencer.pulses_per_beat
1404			chord = self._harmony_horizon.chord_at(beat)
1405			if chord is not None:
1406				return chord
1407
1408		if self._harmonic_state is not None:
1409			return self._harmonic_state.get_current_chord()
1410
1411		return None
1412
1413	@property
1414	def form_state (self) -> typing.Optional["subsequence.form_state.FormState"]:
1415		"""The active ``subsequence.form_state.FormState``, or ``None`` if ``form()`` has not been called."""
1416		return self._form_state
1417
1418	@property
1419	def sequencer (self) -> subsequence.sequencer.Sequencer:
1420		"""The underlying ``Sequencer`` instance."""
1421		return self._sequencer
1422
1423	@property
1424	def running_patterns (self) -> typing.Dict[str, typing.Any]:
1425		"""The currently active patterns, keyed by name."""
1426		return self._running_patterns
1427
1428	@property
1429	def builder_bar (self) -> int:
1430		"""Current bar index used by pattern builders."""
1431		return self._builder_bar
1432
1433	def _require_harmonic_state (self) -> subsequence.harmonic_state.HarmonicState:
1434		"""Return the active HarmonicState, raising ValueError if none is configured."""
1435		if self._harmonic_state is None:
1436			raise ValueError(
1437				"harmony() must be called before this action — "
1438				"no harmonic state has been configured."
1439			)
1440		return self._harmonic_state
1441
1442	def _coerce_progression (self, source: typing.Any, what: str) -> Progression:
1443
1444		"""Coerce a Progression / element list / preset name and resolve it against the key.
1445
1446		Binding freezes one realisation (the value type's identity), so
1447		key-relative content resolves here, at bind time, against the
1448		composition's key and scale.
1449		"""
1450
1451		value = source if isinstance(source, Progression) else subsequence.progressions.progression(source)
1452
1453		if not value.is_concrete:
1454			if self.key is None:
1455				raise ValueError(
1456					f"{what} contains key-relative chords (degrees/romans) — "
1457					"set key= on the Composition so they can resolve"
1458				)
1459			value = value.resolve(self.key, self.scale or "ionian")
1460
1461		return value
1462
1463	def harmony (
1464		self,
1465		style: typing.Optional[typing.Union[str, subsequence.chord_graphs.ChordGraph]] = None,
1466		cycle_beats: int = 4,
1467		dominant_7th: bool = True,
1468		gravity: float = 1.0,
1469		nir_strength: float = 0.5,
1470		minor_turnaround_weight: float = 0.0,
1471		root_diversity: float = subsequence.harmonic_state.DEFAULT_ROOT_DIVERSITY,
1472		reschedule_lookahead: float = 1,
1473		progression: typing.Optional[typing.Any] = None,
1474	) -> None:
1475
1476		"""
1477		Configure the harmonic logic and chord change intervals.
1478
1479		Two sources, combinable: a **bound progression** (``progression=`` — a
1480		:class:`Progression` value, an element list like ``[1, 6, 3, "bVII7"]``,
1481		or chord names) walked span by span on the global clock; and/or a
1482		**graph style** stepping live chords.  With only a progression bound,
1483		it loops on exhaustion; with a style configured too, exhaustion falls
1484		through to live stepping (the frozen-replay bridge).  Calling with
1485		neither argument keeps today's default live engine
1486		(``style="functional_major"``).
1487
1488		Parameters:
1489			style: The harmonic style to use. Built-in: "functional_major"
1490				(alias "diatonic_major"), "turnaround", "aeolian_minor",
1491				"phrygian_minor", "lydian_major", "dorian_minor",
1492				"chromatic_mediant", "suspended", "mixolydian", "whole_tone",
1493				"diminished". See README for full descriptions.
1494			cycle_beats: How many beats each live chord lasts (default 4).
1495				Bound progressions carry their own harmonic rhythm in their
1496				spans, so this applies to live stepping only.
1497			dominant_7th: Whether to include V7 chords (default True).
1498			gravity: Key gravity (0.0 to 1.0). High values stay closer to the root chord.
1499			nir_strength: Melodic inertia (0.0 to 1.0). Influences chord movement
1500				expectations.
1501			minor_turnaround_weight: For "turnaround" style, influences major vs minor feel.
1502			root_diversity: Root-repetition damping (0.0 to 1.0). Each recent
1503				chord sharing a candidate's root reduces the weight to 40% at
1504				the default (0.4). Set to 1.0 to disable.
1505			reschedule_lookahead: How many beats in advance to calculate the
1506				next chord.
1507			progression: A progression to bind to the global clock.  Key-
1508				relative content resolves now, against the composition key
1509				and scale (binding freezes one realisation).
1510
1511		Example:
1512			```python
1513			# A moody minor progression that changes every 8 beats
1514			comp.harmony(style="aeolian_minor", cycle_beats=8, gravity=0.4)
1515
1516			# Manual harmony driving everything — loops forever
1517			comp.harmony(progression=subsequence.progression([1, 6, 3, 7]))
1518			```
1519		"""
1520
1521		if style is None and progression is None:
1522			style = "functional_major"
1523
1524		if style is not None:
1525
1526			if self.key is None:
1527				raise ValueError("Cannot configure harmony without a key - set key in the Composition constructor")
1528
1529			preserved_history: typing.List[subsequence.chords.Chord] = []
1530			preserved_current: typing.Optional[subsequence.chords.Chord] = None
1531
1532			if self._harmonic_state is not None:
1533				preserved_history = self._harmonic_state.history.copy()
1534				preserved_current = self._harmonic_state.current_chord
1535
1536			# Per-call salted build stream (harmony:1, harmony:2, ...): a re-call
1537			# gets its own deterministic stream while history and current chord
1538			# are preserved above, and adding a re-call never shifts any other
1539			# consumer's stream.
1540			self._harmony_count += 1
1541
1542			self._harmonic_state = subsequence.harmonic_state.HarmonicState(
1543				key_name = self.key,
1544				graph_style = style,
1545				include_dominant_7th = dominant_7th,
1546				key_gravity_blend = gravity,
1547				nir_strength = nir_strength,
1548				minor_turnaround_weight = minor_turnaround_weight,
1549				root_diversity = root_diversity,
1550				rng = self._stream(f"harmony:{self._harmony_count}")
1551			)
1552
1553			if preserved_history:
1554				self._harmonic_state.history = preserved_history
1555			if preserved_current is not None and self._harmonic_state.graph.get_transitions(preserved_current):
1556				self._harmonic_state.current_chord = preserved_current
1557
1558		if progression is not None:
1559			self._bound_progression = self._coerce_progression(progression, "harmony(progression=)")
1560
1561		self._harmony_cycle_beats = cycle_beats
1562		self._harmony_reschedule_lookahead = reschedule_lookahead
1563
1564		# A re-call invalidates whatever the horizon had planned.
1565		self._harmony_horizon.invalidate_future()
1566
1567	def freeze (
1568		self,
1569		bars: int,
1570		end: typing.Optional[typing.Any] = None,
1571		pins: typing.Optional[typing.Dict[int, typing.Any]] = None,
1572		avoid: typing.Optional[typing.Sequence[typing.Any]] = None,
1573	) -> "Progression":
1574
1575		"""Capture a chord progression from the live harmony engine.
1576
1577		Runs the harmony engine forward by *bars* chord changes, records each
1578		chord, and returns it as a :class:`Progression` that can be bound to a
1579		form section with :meth:`section_chords`.
1580
1581		The engine state **advances** — successive ``freeze()`` calls produce a
1582		continuing compositional journey so section progressions feel like parts
1583		of a whole rather than isolated islands.
1584
1585		The hybrid constraints compile into the walk: ``end=`` fixes the last
1586		bar ("end on V at bar 8"), ``pins=`` fix any 1-based bar, ``avoid=``
1587		excludes chords throughout.  Specs follow the progression-element
1588		grammar (ints where diatonic, roman/name strings where chromatic) and
1589		resolve against the composition key and scale.  A backward
1590		feasibility pass guarantees satisfiability before any chord is drawn;
1591		the forward walk keeps the engine's real history-dependent weighting.
1592		Bar 1 is always the engine's current chord — the journey continues —
1593		so ``pins={1: ...}`` may only name it redundantly.
1594
1595		Parameters:
1596			bars: Number of chords to capture (one per harmony cycle).
1597			end: The chord at the final bar — ``end="V"`` is the cadential
1598				major dominant in minor.
1599			pins: ``{bar: chord}`` — 1-based fiat positions.
1600			avoid: Chords excluded from the walk.
1601
1602		Returns:
1603			A :class:`Progression` with the captured chords and trailing
1604			history for NIR continuity.
1605
1606		Raises:
1607			ValueError: If :meth:`harmony` has not been called first, or the
1608				constraints are contradictory or unsatisfiable.
1609
1610		Example::
1611
1612			composition.harmony(style="functional_major", cycle_beats=4)
1613			verse  = composition.freeze(8, end="V")   # the verse sets up the chorus
1614			chorus = composition.freeze(4)            # next 4 chords, continuing on
1615			composition.section_chords("verse",  verse)
1616			composition.section_chords("chorus", chorus)
1617		"""
1618
1619		hs = self._require_harmonic_state()
1620
1621		if bars < 1:
1622			raise ValueError("bars must be at least 1")
1623
1624		scale = self.scale or "ionian"
1625		key_pc = subsequence.chords.key_name_to_pc(self.key) if self.key is not None else hs.key_root_pc
1626
1627		resolved_pins = {
1628			position: subsequence.progressions.resolve_constraint(spec, key_pc, scale, f"pins[{position}]")
1629			for position, spec in (pins or {}).items()
1630		}
1631		resolved_end = subsequence.progressions.resolve_constraint(end, key_pc, scale, "end") if end is not None else None
1632		resolved_avoid = [subsequence.progressions.resolve_constraint(spec, key_pc, scale, "avoid") for spec in (avoid or [])]
1633
1634		if 1 in resolved_pins and resolved_pins[1] != hs.current_chord:
1635			raise ValueError(
1636				f"pins[1]={resolved_pins[1].name()} conflicts with the engine's current chord "
1637				f"({hs.current_chord.name()}) — bar 1 of a freeze continues the journey; "
1638				"pin a later bar, or use pin_chord() for playback fiat"
1639			)
1640
1641		# Per-call salted stream (freeze:1, freeze:2, ...): each call's draws
1642		# are independent of every other consumer, so frozen progressions are
1643		# reproducible WITHOUT play() and adding a call cannot shift a
1644		# neighbour's output.  Engine state still advances normally — chord
1645		# continuity comes from current_chord/history, randomness from the
1646		# salted stream (swap-and-restore keeps hs.rng for play untouched).
1647		self._freeze_count += 1
1648		stream = self._stream(f"freeze:{self._freeze_count}")
1649		saved_rng = hs.rng
1650
1651		if stream is not None:
1652			hs.rng = stream
1653
1654		try:
1655			# The kernel with the engine's own hooks is draw-for-draw the old
1656			# step() loop when unconstrained — one walk path for both.
1657			def _commit (chosen: subsequence.chords.Chord) -> None:
1658				hs.current_chord = chosen
1659
1660			collected = subsequence.sequence_utils.constrained_walk(
1661				hs.graph,
1662				hs.current_chord,
1663				bars,
1664				rng = hs.rng,
1665				pins = resolved_pins,
1666				end = resolved_end,
1667				avoid = resolved_avoid,
1668				weight_modifier = hs._transition_weight,
1669				before_choice = hs._record_transition_source,
1670				after_choice = _commit,
1671			)
1672
1673			# Advance past the last captured chord so the next freeze() call or
1674			# live playback does not duplicate it.
1675			hs.step()
1676
1677		finally:
1678			hs.rng = saved_rng
1679
1680		span_beats = float(self._harmony_cycle_beats or 4)
1681
1682		return Progression(
1683			spans = tuple(
1684				subsequence.progressions.ChordSpan(chord = chord, beats = span_beats)
1685				for chord in collected
1686			),
1687			trailing_history = tuple(hs.history),
1688		)
1689
1690	def section_chords (self, section_name: str, progression: typing.Any) -> None:
1691
1692		"""Bind a :class:`Progression` to a named form section.
1693
1694		Every time *section_name* plays, the harmonic clock walks the
1695		progression's spans instead of calling the live engine.  Sections
1696		without a bound progression continue generating live chords.
1697
1698		Accepts a :class:`Progression` value (from :meth:`freeze`, the
1699		``progression()`` factory, or hand-built) or anything the factory
1700		accepts — an element list like ``[1, 6, 3, "bVII7"]`` or chord
1701		names.  Key-relative content resolves now, against the composition
1702		key and scale.
1703
1704		On exhaustion mid-section the progression loops when no graph style
1705		is configured (and always when it contains a
1706		:class:`~subsequence.progressions.PitchSet`); with a live engine,
1707		exhaustion falls through to live stepping until the section changes.
1708
1709		Parameters:
1710			section_name: Name of the section as defined in :meth:`form`.
1711			progression: The progression to bind.
1712
1713		Raises:
1714			ValueError: If a graph-based form has been configured and
1715				*section_name* is not one of its sections.  List and generator
1716				forms yield names lazily, so they cannot be validated here.
1717
1718		Example::
1719
1720			composition.section_chords("verse",  verse_progression)
1721			composition.section_chords("chorus", [1, 6, 3, 7])
1722			# "bridge" is not bound — it generates live chords
1723		"""
1724
1725		if (
1726			self._form_state is not None
1727			and self._form_state._section_bars is not None
1728			and section_name not in self._form_state._section_bars
1729		):
1730			known = ", ".join(sorted(self._form_state._section_bars))
1731			raise ValueError(
1732				f"Section '{section_name}' not found in form. "
1733				f"Known sections: {known}"
1734			)
1735
1736		self._section_progressions[section_name] = self._coerce_progression(
1737			progression, f"section_chords({section_name!r})"
1738		)
1739		self._harmony_horizon.invalidate_future()
1740
1741	def pin_chord (self, bar: int, chord: typing.Optional[typing.Any]) -> None:
1742
1743		"""Force the chord sounding at a bar — fiat over live generation.
1744
1745		Whatever the harmonic source (live walk, bound progression, section
1746		progression) produces for *bar*, the pinned chord overrides it.
1747		Pass ``None`` to remove a pin.
1748
1749		Parameters:
1750			bar: 1-based bar number (the musician count).
1751			chord: A chord name, int degree, roman string, ``Chord``,
1752				``PitchSet``, or ``None`` to unpin.  Key-relative specs
1753				resolve now, against the composition key and scale.
1754
1755		Example::
1756
1757			composition.pin_chord(8, "E7")    # the turnaround lands on E7
1758			composition.pin_chord(8, None)    # let it walk again
1759		"""
1760
1761		if not isinstance(bar, int) or isinstance(bar, bool) or bar < 1:
1762			raise ValueError(f"bars are 1-based ints, got {bar!r}")
1763
1764		if chord is None:
1765			self._pinned_chords.pop(bar, None)
1766		else:
1767			span = subsequence.progressions.parse_element(chord, beats = float(self.time_signature[0]))
1768
1769			if not span.is_concrete:
1770				if self.key is None:
1771					raise ValueError("pin_chord with a key-relative spec needs key= on the Composition")
1772				span = span.resolve(subsequence.chords.key_name_to_pc(self.key), self.scale or "ionian")
1773
1774			self._pinned_chords[bar] = _span_chord(span)
1775
1776		self._harmony_horizon.invalidate_future()
1777
1778	def section_motifs (self, section_name: str, value: typing.Any, part: typing.Optional[str] = None) -> None:
1779
1780		"""Bind a Motif or Phrase to a named form section (per optional part).
1781
1782		Patterns read the binding back with ``p.section_motif(part)`` (or use
1783		the one-call :meth:`phrase_part`); a section with no binding for the
1784		part is silent for that part — bind material or don't, no fallback
1785		guessing.  Re-binding is idempotent, so the call is safe in a live
1786		file: re-executing on save is the desired rebind.
1787
1788		Parameters:
1789			section_name: Name of the section as defined in :meth:`form`.
1790			value: A ``Motif`` or ``Phrase`` (anything exposing
1791				``.length``/``.slice`` places).
1792			part: Optional part label, so one section can carry several
1793				bindings (``"lead"``, ``"bass"``, ...).
1794
1795		Raises:
1796			ValueError: If a graph-based form has been configured and
1797				*section_name* is not one of its sections.
1798
1799		Example::
1800
1801			composition.section_motifs("verse",  verse_line,  part="lead")
1802			composition.section_motifs("chorus", chorus_line, part="lead")
1803		"""
1804
1805		if not hasattr(value, "length") or not hasattr(value, "slice"):
1806			raise TypeError(
1807				f"section_motifs() binds Motif/Phrase values (.length/.slice) — got {type(value).__name__}"
1808			)
1809
1810		if (
1811			self._form_state is not None
1812			and self._form_state._section_bars is not None
1813			and section_name not in self._form_state._section_bars
1814		):
1815			known = ", ".join(sorted(self._form_state._section_bars))
1816			raise ValueError(
1817				f"Section '{section_name}' not found in form. "
1818				f"Known sections: {known}"
1819			)
1820
1821		self._section_motifs[(section_name, part)] = value
1822
1823	def on_event (self, event_name: str, callback: typing.Callable[..., typing.Any]) -> None:
1824
1825		"""
1826		Register a callback for a sequencer event (e.g., "bar", "start", "stop").
1827		"""
1828
1829		self._sequencer.on_event(event_name, callback)
1830
1831
1832	# -----------------------------------------------------------------------
1833	# Hotkey API
1834	# -----------------------------------------------------------------------
1835
1836	def hotkeys (self, enabled: bool = True) -> None:
1837
1838		"""Enable or disable the global hotkey listener.
1839
1840		Must be called **before** :meth:`play` to take effect.  When enabled, a
1841		background thread reads single keystrokes from stdin without requiring
1842		Enter.  The ``?`` key is always reserved and lists all active bindings.
1843
1844		Hotkeys have zero impact on playback when disabled — the listener
1845		thread is never started.
1846
1847		Args:
1848		    enabled: ``True`` (default) to enable hotkeys; ``False`` to disable.
1849
1850		Example::
1851
1852		    composition.hotkeys()
1853		    composition.hotkey("a", lambda: composition.form_jump("chorus"))
1854		    composition.play()
1855		"""
1856
1857		self._hotkeys_enabled = enabled
1858
1859
1860	def hotkey (
1861		self,
1862		key:      str,
1863		action:   typing.Callable[[], None],
1864		quantize: int = 0,
1865		label:    typing.Optional[str] = None,
1866	) -> None:
1867
1868		"""Register a single-key shortcut that fires during playback.
1869
1870		The listener must be enabled first with :meth:`hotkeys`.
1871
1872		Most actions — form jumps, ``composition.data`` writes, and
1873		:meth:`tweak` calls — should use ``quantize=0`` (the default).  Their
1874		musical effect is naturally delayed to the next pattern rebuild cycle,
1875		which provides automatic musical quantization without extra configuration.
1876
1877		Use ``quantize=N`` for actions where you want an explicit bar-boundary
1878		guarantee, such as :meth:`mute` / :meth:`unmute`.
1879
1880		The ``?`` key is reserved and cannot be overridden.
1881
1882		Args:
1883		    key: A single character trigger (e.g. ``"a"``, ``"1"``, ``" "``).
1884		    action: Zero-argument callable to execute.
1885		    quantize: ``0`` = execute immediately (default).  ``N`` = execute
1886		        on the next global bar number divisible by *N*.
1887		    label: Display name for the ``?`` help listing.  Auto-derived from
1888		        the function name or lambda body if omitted.
1889
1890		Raises:
1891		    ValueError: If ``key`` is the reserved ``?`` character, or if
1892		        ``key`` is not exactly one character.
1893
1894		Example::
1895
1896		    composition.hotkeys()
1897
1898		    # Immediate — musical effect happens at next pattern rebuild
1899		    composition.hotkey("a", lambda: composition.form_jump("chorus"))
1900		    composition.hotkey("1", lambda: composition.data.update({"mode": "chill"}))
1901
1902		    # Explicit 4-bar phrase boundary
1903		    composition.hotkey("s", lambda: composition.mute("drums"), quantize=4)
1904
1905		    # Named function — label is derived automatically
1906		    def drop_to_breakdown ():
1907		        composition.form_jump("breakdown")
1908		        composition.mute("lead")
1909
1910		    composition.hotkey("d", drop_to_breakdown)
1911
1912		    composition.play()
1913		"""
1914
1915		if len(key) != 1:
1916			raise ValueError(f"hotkey key must be a single character, got {key!r}")
1917
1918		if key == _HOTKEY_RESERVED:
1919			raise ValueError(f"'{_HOTKEY_RESERVED}' is reserved for listing active hotkeys.")
1920
1921		derived = label if label is not None else _derive_label(action)
1922
1923		self._hotkey_bindings[key] = HotkeyBinding(
1924			key      = key,
1925			action   = action,
1926			quantize = quantize,
1927			label    = derived,
1928		)
1929
1930
1931	def form_jump (self, section_name: str) -> None:
1932
1933		"""Jump the form to a named section immediately.
1934
1935		Delegates to :meth:`subsequence.form_state.FormState.jump_to`.  Only works when the
1936		composition uses graph-mode form (a dict passed to :meth:`form`).
1937
1938		The musical effect is heard at the *next pattern rebuild cycle* — already-
1939		queued MIDI notes are unaffected.  This natural delay means ``form_jump``
1940		is effective without needing explicit quantization.
1941
1942		Args:
1943		    section_name: The section to jump to.
1944
1945		Raises:
1946		    ValueError: If no form is configured, or the form is not in graph
1947		        mode, or *section_name* is unknown.
1948
1949		Example::
1950
1951		    composition.hotkey("c", lambda: composition.form_jump("chorus"))
1952		"""
1953
1954		if self._form_state is None:
1955			raise ValueError("form_jump() requires a form to be configured via composition.form().")
1956
1957		self._form_state.jump_to(section_name)
1958
1959		# The harmony horizon planned against the old section — revoke it.
1960		self._harmony_horizon.invalidate_future()
1961
1962
1963	def form_next (self, section_name: str) -> None:
1964
1965		"""Queue the next section — takes effect when the current section ends.
1966
1967		Unlike :meth:`form_jump`, this does not interrupt the current section.
1968		The queued section replaces the automatically pre-decided next section
1969		and takes effect at the natural section boundary.  The performer can
1970		change their mind by calling ``form_next`` again before the boundary.
1971
1972		Delegates to :meth:`subsequence.form_state.FormState.queue_next`.  Only works when the
1973		composition uses graph-mode form (a dict passed to :meth:`form`).
1974
1975		Args:
1976		    section_name: The section to queue.
1977
1978		Raises:
1979		    ValueError: If no form is configured, or the form is not in graph
1980		        mode, or *section_name* is unknown.
1981
1982		Example::
1983
1984		    composition.hotkey("c", lambda: composition.form_next("chorus"))
1985		"""
1986
1987		if self._form_state is None:
1988			raise ValueError("form_next() requires a form to be configured via composition.form().")
1989
1990		self._form_state.queue_next(section_name)
1991
1992		# The harmony horizon planned against the old continuation — revoke it.
1993		self._harmony_horizon.invalidate_future()
1994
1995
1996	def _list_hotkeys (self) -> None:
1997
1998		"""Log all active hotkey bindings (triggered by the ``?`` key).
1999
2000		Output appears via the standard logger so it scrolls cleanly above
2001		the :class:`~subsequence.display.Display` status line.
2002		"""
2003
2004		lines = ["Active hotkeys:"]
2005		for key in sorted(self._hotkey_bindings):
2006			b = self._hotkey_bindings[key]
2007			quant_str = "immediate" if b.quantize == 0 else f"quantize={b.quantize}"
2008			lines.append(f"  {key}  \u2192  {b.label}  ({quant_str})")
2009		lines.append(f"  ?  \u2192  list hotkeys")
2010		logger.info("\n".join(lines))
2011
2012
2013	def _process_hotkeys (self, bar: int) -> None:
2014
2015		"""Drain pending keystrokes and execute due actions.
2016
2017		Called on every ``"bar"`` event by the sequencer when hotkeys are
2018		enabled.  Handles both immediate (``quantize=0``) and quantized actions.
2019
2020		Both kinds run here, on the bar-event callback (the event loop): the
2021		keystroke listener thread only enqueues keypresses (``drain()``), it
2022		never executes actions.  Immediate (``quantize=0``) bindings fire as soon
2023		as the key is drained; quantized ones wait for their next boundary.
2024
2025		Args:
2026		    bar: The current global bar number from the sequencer.
2027		"""
2028
2029		if self._keystroke_listener is None:
2030			return
2031
2032		# Process newly arrived keys.
2033		for key in self._keystroke_listener.drain():
2034
2035			if key == _HOTKEY_RESERVED:
2036				self._list_hotkeys()
2037				continue
2038
2039			binding = self._hotkey_bindings.get(key)
2040			if binding is None:
2041				continue
2042
2043			if binding.quantize == 0:
2044				# Immediate — execute now (we're on the bar-event callback,
2045				# which is safe for all mutation methods).
2046				try:
2047					binding.action()
2048					logger.info(f"Hotkey '{key}' \u2192 {binding.label}")
2049				except Exception as exc:
2050					logger.warning(f"Hotkey '{key}' action raised: {exc}")
2051			else:
2052				# Defer until the next quantize boundary.
2053				self._pending_hotkey_actions.append(
2054					_PendingHotkeyAction(binding=binding)
2055				)
2056
2057		# Fire any pending actions whose bar boundary has arrived.
2058		still_pending: typing.List[_PendingHotkeyAction] = []
2059
2060		for pending in self._pending_hotkey_actions:
2061			if bar % pending.binding.quantize == 0:
2062				try:
2063					pending.binding.action()
2064					logger.info(
2065						f"Hotkey '{pending.binding.key}' \u2192 {pending.binding.label} "
2066						f"(bar {bar})"
2067					)
2068				except Exception as exc:
2069					logger.warning(
2070						f"Hotkey '{pending.binding.key}' action raised: {exc}"
2071					)
2072			else:
2073				still_pending.append(pending)
2074
2075		self._pending_hotkey_actions = still_pending
2076
2077	@property
2078	def seed (self) -> typing.Optional[int]:
2079
2080		"""
2081		The composition's random seed, or None when unseeded.
2082
2083		When set, every random decision derives deterministically from this
2084		value through named streams (see ``seed_for()``), so the same script
2085		produces the same music on every run.  Assign to set it::
2086
2087			comp.seed = 42
2088
2089		(Formerly the method ``comp.seed(42)`` — the call form is a hard
2090		break per the pre-1.0 rename policy.)
2091		"""
2092
2093		return self._seed
2094
2095	@seed.setter
2096	def seed (self, value: typing.Optional[int]) -> None:
2097
2098		"""Set the composition seed (``comp.seed = 42``)."""
2099
2100		self._seed = value
2101
2102	def _stream_seed (self, name: str) -> typing.Optional[int]:
2103
2104		"""
2105		Derive the effective integer seed for a named random stream.
2106
2107		The derivation is ``zlib.crc32(f"{seed}:{name}")`` — crc32 rather
2108		than ``hash()`` because it is stable across processes — plus the
2109		per-name nonce when ``reroll()`` has been called.  Returns None when
2110		the composition is unseeded.
2111		"""
2112
2113		if self._seed is None:
2114			return None
2115
2116		nonce = self._reroll_nonces.get(name, 0)
2117		key = f"{self._seed}:{name}" if nonce == 0 else f"{self._seed}:{name}:{nonce}"
2118		return zlib.crc32(key.encode())
2119
2120	def _stream (self, name: str) -> typing.Optional[random.Random]:
2121
2122		"""A fresh ``random.Random`` for a named stream, or None when unseeded."""
2123
2124		stream_seed = self._stream_seed(name)
2125		return None if stream_seed is None else random.Random(stream_seed)
2126
2127	def seed_for (self, name: str) -> typing.Optional[int]:
2128
2129		"""
2130		Surface the effective derived seed for a named stream.
2131
2132		Works for pattern names and equally for any name you invent for a
2133		standalone value generator (``seed=composition.seed_for("hook")``),
2134		so its randomness keys off the composition seed without sharing any
2135		other consumer's stream.  Reflects ``reroll()`` nonces.  Returns None
2136		when the composition is unseeded.
2137
2138		Example:
2139			```python
2140			hook_seed = composition.seed_for("hook")
2141			```
2142		"""
2143
2144		return self._stream_seed(name)
2145
2146	def reroll (self, name: str) -> None:
2147
2148		"""
2149		Deal a named stream a fresh deterministic seed — try a new variation.
2150
2151		Bumps the per-name nonce and prints the new effective seed.  The
2152		nonce lives only in this process, so the printed seed is what lets a
2153		variation you like survive a restart: note it down, or ``lock()`` the
2154		name to pin it for the session.  Refuses on locked names.
2155
2156		Parameters:
2157			name: The stream name — usually a pattern name.
2158
2159		Example:
2160			```python
2161			comp.reroll("lead")    # prints: reroll('lead') -> effective seed ...
2162			```
2163		"""
2164
2165		if name in self._locked_names:
2166			print(f"reroll('{name}') refused: '{name}' is locked - call unlock('{name}') first")
2167			return
2168
2169		self._reroll_nonces[name] = self._reroll_nonces.get(name, 0) + 1
2170		effective = self._stream_seed(name)
2171
2172		if effective is None:
2173			print(f"reroll('{name}'): composition has no seed - randomness is unseeded")
2174			return
2175
2176		running = self._running_patterns.get(name)
2177
2178		if running is not None and hasattr(running, "_rng"):
2179			running._rng = random.Random(effective)
2180
2181		print(f"reroll('{name}') -> effective seed {effective} (nonce {self._reroll_nonces[name]})")
2182
2183	def lock (self, name: str) -> None:
2184
2185		"""
2186		Pin a named stream: keep its current effective seed and realization.
2187
2188		Engine-side state, so it survives live reload (it is never a builder
2189		swap): a locked pattern re-deals its stream from the same effective
2190		seed on every rebuild, so every cycle realizes identically, and
2191		``reroll()`` refuses with a message until ``unlock()``.
2192
2193		Parameters:
2194			name: The stream name — usually a pattern name.
2195		"""
2196
2197		self._locked_names.add(name)
2198
2199	def unlock (self, name: str) -> None:
2200
2201		"""Release a ``lock()``: the stream runs free and ``reroll()`` works again."""
2202
2203		self._locked_names.discard(name)
2204
2205	def tuning (
2206		self,
2207		source: typing.Optional[typing.Union[str, "os.PathLike"]] = None,
2208		*,
2209		cents: typing.Optional[typing.List[float]] = None,
2210		ratios: typing.Optional[typing.List[float]] = None,
2211		equal: typing.Optional[int] = None,
2212		bend_range: float = 2.0,
2213		channels: typing.Optional[typing.List[int]] = None,
2214		reference_note: int = 60,
2215		exclude_drums: bool = True,
2216	) -> None:
2217
2218		"""Set a global microtonal tuning for the composition.
2219
2220		The tuning is applied automatically after each pattern rebuild (before
2221		the pattern is scheduled).  Drum patterns (those registered with a
2222		``drum_note_map``) are excluded by default.
2223
2224		Supply exactly one of the source parameters:
2225
2226		- ``source``: path to a Scala ``.scl`` file.
2227		- ``cents``: list of cent offsets for degrees 1..N (degree 0 = 0.0 is implicit).
2228		- ``ratios``: list of frequency ratios (e.g., ``[9/8, 5/4, 4/3, 3/2, 2]``).
2229		- ``equal``: integer for N-tone equal temperament (e.g., ``equal=19``).
2230
2231		For polyphonic parts, supply a ``channels`` pool.  Notes are spread
2232		across those MIDI channels so each can carry an independent pitch bend.
2233		The synth must be configured to match ``bend_range`` (its pitch-bend range
2234		setting in semitones).
2235
2236		Parameters:
2237			source: Path to a ``.scl`` file.
2238			cents: Cent offsets for scale degrees 1..N.
2239			ratios: Frequency ratios for scale degrees 1..N.
2240			equal: Number of equal divisions of the period.
2241			bend_range: Synth pitch-bend range in semitones (default ±2).
2242			channels: Channel pool for polyphonic rotation.
2243			reference_note: MIDI note mapped to scale degree 0 (default 60 = C4).
2244			exclude_drums: When True (default), skip patterns that have a
2245			    ``drum_note_map`` (they use fixed GM pitches, not tuned ones).
2246
2247		Example:
2248			```python
2249			# Quarter-comma meantone from a Scala file
2250			comp.tuning("meanquar.scl")
2251
2252			# Just intonation from ratios
2253			comp.tuning(ratios=[9/8, 5/4, 4/3, 3/2, 5/3, 15/8, 2])
2254
2255			# 19-TET, monophonic
2256			comp.tuning(equal=19, bend_range=2.0)
2257
2258			# 31-TET with channel rotation for polyphony (channels 1-6)
2259			comp.tuning("31tet.scl", channels=[0, 1, 2, 3, 4, 5])
2260			```
2261		"""
2262		import subsequence.tuning as _tuning_mod
2263
2264		given = sum(x is not None for x in [source, cents, ratios, equal])
2265		if given == 0:
2266			raise ValueError("composition.tuning() requires one of: source, cents, ratios, or equal")
2267		if given > 1:
2268			raise ValueError("composition.tuning() accepts only one source parameter")
2269
2270		if source is not None:
2271			t = _tuning_mod.Tuning.from_scl(source)
2272		elif cents is not None:
2273			t = _tuning_mod.Tuning.from_cents(cents)
2274		elif ratios is not None:
2275			t = _tuning_mod.Tuning.from_ratios(ratios)
2276		else:
2277			t = _tuning_mod.Tuning.equal(equal)  # type: ignore[arg-type]
2278
2279		self._tuning = t
2280		self._tuning_bend_range = bend_range
2281		self._tuning_channels = channels
2282		self._tuning_reference_note = reference_note
2283		self._tuning_exclude_drums = exclude_drums
2284
2285	def display (self, enabled: bool = True, grid: bool = False, grid_scale: float = 1.0) -> None:
2286
2287		"""
2288		Enable or disable the live terminal dashboard.
2289
2290		When enabled, Subsequence uses a safe logging handler that allows a
2291		persistent status line (BPM, Key, Bar, Section, Chord) to stay at
2292		the bottom of the terminal while logs scroll above it.
2293
2294		Parameters:
2295			enabled: Whether to show the display (default True).
2296			grid: When True, render an ASCII grid visualisation of all
2297				running patterns above the status line. The grid updates
2298				once per bar, showing which steps have notes and at what
2299				velocity.
2300			grid_scale: Horizontal zoom factor for the grid (default
2301				``1.0``).  Higher values add visual columns between
2302				grid steps, revealing micro-timing from swing and groove.
2303				Snapped to the nearest integer internally for uniform
2304				marker spacing.
2305		"""
2306
2307		if enabled:
2308			self._display = subsequence.display.Display(self, grid=grid, grid_scale=grid_scale)
2309		else:
2310			self._display = None
2311
2312	def web_ui (self, http_host: str = "127.0.0.1", ws_host: str = "127.0.0.1") -> None:
2313
2314		"""
2315		Enable the realtime Web UI Dashboard.
2316
2317		When enabled, Subsequence instantiates a WebSocket server that broadcasts
2318		the current state, signals, and active patterns (with high-res timing and
2319		note data) to any connected browser clients.
2320
2321		Both servers bind to localhost by default.  Pass ``http_host`` / ``ws_host``
2322		(e.g. "0.0.0.0") to opt into LAN exposure — the dashboard is read-only but
2323		broadcasts full composition state, so only do so on a trusted network.
2324		"""
2325
2326		self._web_ui_enabled = True
2327		self._web_ui_http_host = http_host
2328		self._web_ui_ws_host = ws_host
2329
2330	def midi_input (self, device: str, clock_follow: bool = False, name: typing.Optional[str] = None) -> None:
2331
2332		"""
2333		Configure a MIDI input device for external sync and MIDI messages.
2334
2335		May be called multiple times to register additional input devices.
2336		The first call sets the primary input (device 0).  Subsequent calls
2337		add additional input devices (device 1, 2, …).  Only one device may
2338		have ``clock_follow=True``.
2339
2340		Parameters:
2341			device: The name of the MIDI input port.
2342			clock_follow: If True, Subsequence will slave its clock to incoming
2343				MIDI Ticks. It will also follow MIDI Start/Stop/Continue
2344				commands. Only one device can have this enabled at a time.
2345			name: Optional alias for use with ``cc_map(input_device=…)`` and
2346				``cc_forward(input_device=…)``.  When omitted, the raw device
2347				name is used.
2348
2349		Example:
2350			```python
2351			# Single controller (unchanged usage)
2352			comp.midi_input("Scarlett 2i4", clock_follow=True)
2353
2354			# Multiple controllers
2355			comp.midi_input("Arturia KeyStep", name="keys")
2356			comp.midi_input("Faderfox EC4", name="faders")
2357			```
2358		"""
2359
2360		if clock_follow:
2361			if self.is_clock_following:
2362				raise ValueError("Only one input device can be configured to follow external clock (clock_follow=True)")
2363
2364		if self._input_device is None:
2365			# First call: set primary input device (device 0)
2366			self._input_device = device
2367			self._input_device_alias = name
2368			self._clock_follow = clock_follow
2369		else:
2370			# Subsequent calls: register additional input devices
2371			self._additional_inputs.append((device, name, clock_follow))
2372
2373	def midi_output (self, device: str, name: typing.Optional[str] = None, latency_ms: float = 0.0) -> int:
2374
2375		"""
2376		Register an additional MIDI output device.
2377
2378		The first output device is always the one passed to
2379		``Composition(output_device=…)`` — that is device 0.
2380		Each call to ``midi_output()`` adds the next device (1, 2, …).
2381
2382		Parameters:
2383			device: The exact name of the MIDI output port, as reported
2384				by ``mido.get_output_names()``. Matching is strict —
2385				partial names and substrings are rejected. See
2386				``Composition.__init__`` for the lookup snippet and a
2387				note on ALSA name stability on Linux.
2388			name: Optional alias for use with ``pattern(device=…)``,
2389				``cc_forward(output_device=…)``, etc.  When omitted, the raw
2390				device name is used.
2391			latency_ms: Physical output latency of this device in
2392				milliseconds, for delay compensation (default 0.0, must be
2393				non-negative). Set this when the device sounds late (e.g. a
2394				software sampler) so Subsequence delays faster devices to
2395				line everything up.
2396
2397		Returns:
2398			The integer device index assigned (1, 2, 3, …).
2399
2400		Example:
2401			```python
2402			comp = subsequence.Composition(bpm=120, output_device="MOTU Express")
2403
2404			# Returns 1 — use as device=1 or device="integra"
2405			comp.midi_output("Roland Integra", name="integra")
2406
2407			# A software sampler that sounds 20ms late
2408			comp.midi_output("Subsample", name="sampler", latency_ms=20)
2409
2410			@comp.pattern(channel=1, beats=4, device="integra")
2411			def strings (p):
2412				p.note(60, beat=0)
2413			```
2414		"""
2415
2416		if latency_ms < 0:
2417			raise ValueError(f"latency_ms must be non-negative — got {latency_ms}")
2418
2419		idx = 1 + len(self._additional_outputs)  # device 0 is always the primary
2420		self._additional_outputs.append(_AdditionalOutput(device=device, alias=name, latency_ms=latency_ms))
2421		return idx
2422
2423	def _warn_if_high_latency (self) -> None:
2424
2425		"""Warn if delay compensation adds a large whole-rig latency.
2426
2427		The slowest device defines the alignment point — every faster device is
2428		delayed up to that amount — so a large maximum means the whole rig
2429		responds late to live input.  Emitted once at startup.
2430		"""
2431
2432		candidates: typing.List[typing.Tuple[str, float]] = [("primary output", self._output_latency_ms)]
2433		candidates += [(out.alias or out.device, out.latency_ms) for out in self._additional_outputs]
2434
2435		slow_name, max_ms = max(candidates, key=lambda c: c[1])
2436
2437		if max_ms > _LATENCY_WARN_THRESHOLD_MS:
2438			logger.warning(
2439				"Device latency compensation: '%s' is the slowest at %.0fms, so faster "
2440				"devices are delayed up to %.0fms to stay aligned — live-input feel may suffer.",
2441				slow_name, max_ms, max_ms,
2442			)
2443
2444	def clock_output (self, enabled: bool = True) -> None:
2445
2446		"""
2447		Send MIDI timing clock to connected hardware.
2448
2449		When enabled, Subsequence acts as a MIDI clock master and sends
2450		standard clock messages on the output port: a Start message (0xFA)
2451		when playback begins, a Clock tick (0xF8) on every pulse (24 PPQN),
2452		and a Stop message (0xFC) when playback ends.
2453
2454		This allows hardware synthesizers, drum machines, and effect units to
2455		slave their tempo to Subsequence automatically.
2456
2457		**Note:** Clock output is automatically disabled when ``midi_input()``
2458		is called with ``clock_follow=True``, to prevent a clock feedback loop.
2459
2460		Parameters:
2461			enabled: Whether to send MIDI clock (default True).
2462
2463		Example:
2464			```python
2465			comp = subsequence.Composition(bpm=120, output_device="...")
2466			comp.clock_output()   # hardware will follow Subsequence tempo
2467			```
2468		"""
2469
2470		self._clock_output = enabled
2471
2472
2473	def link (self, quantum: float = 4.0) -> "Composition":
2474
2475		"""
2476		Enable Ableton Link tempo and phase synchronisation.
2477
2478		When enabled, Subsequence joins the local Link session and slaves its
2479		clock to the shared network tempo and beat phase.  All other Link-enabled
2480		apps on the same LAN — Ableton Live, iOS synths, other Subsequence
2481		instances — will automatically stay in time.
2482
2483		Playback starts on the next bar boundary aligned to the Link quantum,
2484		so downbeats stay in sync across all participants.
2485
2486		Requires the ``link`` optional extra::
2487
2488		    pip install subsequence[link]
2489
2490		Parameters:
2491			quantum: Beat cycle length.  ``4.0`` (default) = one bar in 4/4 time.
2492			         Change this if your composition uses a different meter.
2493
2494		Example::
2495
2496		    comp = subsequence.Composition(bpm=120, key="C")
2497		    comp.link()          # join the Link session
2498		    comp.play()
2499
2500		    # On another machine / instance:
2501		    comp2 = subsequence.Composition(bpm=120)
2502		    comp2.link()         # tempo and phase will lock to comp
2503		    comp2.play()
2504
2505		Note:
2506		    ``set_bpm()`` proposes the new tempo to the Link network when Link
2507		    is active.  The network-authoritative tempo is applied on the next
2508		    pulse, so there may be a brief lag before the change is visible.
2509		"""
2510
2511		# Eagerly check that aalink is installed — fail early with a clear message.
2512		subsequence.link_clock._require_aalink()
2513
2514		self._link_quantum = quantum
2515		return self
2516
2517
2518	def cc_map (
2519		self,
2520		cc: int,
2521		data_key: str,
2522		channel: typing.Optional[int] = None,
2523		min_val: float = 0.0,
2524		max_val: float = 1.0,
2525		input_device: subsequence.midi_utils.DeviceId = None,
2526	) -> None:
2527
2528		"""
2529		Map an incoming MIDI CC to a ``composition.data`` key.
2530
2531		When the composition receives a CC message on the configured MIDI
2532		input port, the value is scaled from the CC range (0–127) to
2533		*[min_val, max_val]* and stored in ``composition.data[data_key]``.
2534
2535		This lets hardware knobs, faders, and expression pedals control live
2536		parameters without writing any callback code.
2537
2538		**Requires** ``midi_input()`` to be called first to open an input port.
2539
2540		Parameters:
2541			cc: MIDI Control Change number (0–127).
2542			data_key: The ``composition.data`` key to write.
2543			channel: If given, only respond to CC messages on this channel.
2544				Uses the same numbering convention as ``pattern()`` (1-16
2545				by default, or 0-15 with ``zero_indexed_channels=True``).
2546				``None`` matches any channel (default).
2547			min_val: Scaled minimum — written when CC value is 0 (default 0.0).
2548			max_val: Scaled maximum — written when CC value is 127 (default 1.0).
2549			input_device: Only respond to CC messages from this input device
2550				(index or name).  ``None`` responds to any input device (default).
2551
2552		Example:
2553			```python
2554			comp.midi_input("Arturia KeyStep")
2555			comp.cc_map(74, "filter_cutoff")           # knob → 0.0–1.0
2556			comp.cc_map(7, "volume", min_val=0, max_val=127)  # volume fader
2557
2558			# Multi-device: only listen to CC 74 from the "faders" controller
2559			comp.cc_map(74, "filter", input_device="faders")
2560			```
2561		"""
2562
2563		resolved_channel = self._resolve_channel(channel) if channel is not None else None
2564
2565		self._cc_mappings.append({
2566			'cc': cc,
2567			'data_key': data_key,
2568			'channel': resolved_channel,
2569			'min_val': min_val,
2570			'max_val': max_val,
2571			'input_device': input_device,  # resolved to int index in _run()
2572		})
2573
2574
2575	def note_input (
2576		self,
2577		channel: typing.Optional[int] = None,
2578		release_ms: float = 30.0,
2579		latch: bool = False,
2580		input_device: subsequence.midi_utils.DeviceId = None,
2581	) -> None:
2582
2583		"""Track notes held on a MIDI keyboard for live arpeggiation.
2584
2585		Incoming note-on/note-off messages build a live "currently held" set
2586		that any pattern reads via ``p.held_notes()`` — typically fed straight
2587		to ``p.arpeggio()``.  The composition still authors the rhythm and
2588		motion; the player's hands supply the pitch set.  This is a live
2589		*performance* layer over the deterministic, seeded composition: when
2590		rendering headlessly there is no input, so ``p.held_notes()`` is empty
2591		and seeded output is unchanged.
2592
2593		**Requires** ``midi_input()`` to be called first to open an input port.
2594
2595		Parameters:
2596			channel: If given, only track notes on this channel.  Uses the same
2597				numbering convention as ``pattern()`` (1-16 by default, or 0-15
2598				with ``zero_indexed_channels=True``).  ``None`` tracks any
2599				channel (default).
2600			release_ms: How long (milliseconds) a released note keeps counting
2601				as held.  This smooths the momentary all-keys-up gap during a
2602				hand-position change so the arp does not drop to silence.
2603				Default 30.0; set 0.0 to release instantly.  Ignored when
2604				``latch`` is True.
2605			latch: When True, the held set persists after you lift your hands
2606				until you play a new chord (the first key after every key is up
2607				replaces it) — like a hardware arp's latch.
2608			input_device: Only track notes from this input device (index or
2609				name).  ``None`` tracks any input device (default).
2610
2611		Example:
2612			```python
2613			comp.midi_input("Arturia KeyStep")
2614			comp.note_input(channel=1, release_ms=30)
2615
2616			@comp.pattern(channel=6, beats=4)
2617			def arp (p):
2618			    p.arpeggio(p.held_notes(), direction="up")  # rests when silent
2619			```
2620		"""
2621
2622		if self._note_input is not None:
2623			raise RuntimeError("only one note_input source is supported — named multi-source is not yet available")
2624
2625		resolved_channel = self._resolve_channel(channel) if channel is not None else None
2626
2627		self._note_input = {
2628			'channel': resolved_channel,
2629			'release_ms': release_ms,
2630			'latch': latch,
2631			'input_device': input_device,  # resolved to int index in _run()
2632		}
2633
2634
2635	@staticmethod
2636	def _make_cc_forward_transform (
2637		output: typing.Union[str, typing.Callable],
2638		cc: int,
2639		output_channel: typing.Optional[int],
2640	) -> typing.Callable:
2641
2642		"""Build a transform callable from a preset string or user-supplied callable.
2643
2644		The returned callable has signature ``(value: int, channel: int) -> Optional[mido.Message]``
2645		where ``channel`` is the 0-indexed incoming channel.
2646		"""
2647
2648		import mido as _mido
2649
2650		def _out_ch (incoming: int) -> int:
2651			return output_channel if output_channel is not None else incoming
2652
2653		if callable(output):
2654			if output_channel is None:
2655				return output
2656			def _wrapped (value: int, channel: int) -> typing.Optional[typing.Any]:
2657				msg = output(value, channel)
2658
2659				if msg is None:
2660					return None
2661
2662				# copy() re-channels without rebuilding: reconstructing from
2663				# __dict__ passed 'type' twice and raised TypeError on every
2664				# message, so callable+output_channel never forwarded anything.
2665				return msg.copy(channel=output_channel)
2666			return _wrapped
2667
2668		if output == 'cc':
2669			def _cc_identity (value: int, channel: int) -> typing.Any:
2670				return _mido.Message('control_change', channel=_out_ch(channel), control=cc, value=value)
2671			return _cc_identity
2672
2673		if output.startswith('cc:'):
2674			try:
2675				target_cc = int(output[3:])
2676			except ValueError:
2677				raise ValueError(f"cc_forward(): invalid preset '{output}' — expected 'cc:N' where N is 0–127")
2678			if not 0 <= target_cc <= 127:
2679				raise ValueError(f"cc_forward(): CC number {target_cc} out of range 0–127")
2680			def _cc_remap (value: int, channel: int) -> typing.Any:
2681				return _mido.Message('control_change', channel=_out_ch(channel), control=target_cc, value=value)
2682			return _cc_remap
2683
2684		if output == 'pitchwheel':
2685			def _pitchwheel (value: int, channel: int) -> typing.Any:
2686				pitch = int(value / 127 * 16383) - 8192
2687				return _mido.Message('pitchwheel', channel=_out_ch(channel), pitch=pitch)
2688			return _pitchwheel
2689
2690		raise ValueError(
2691			f"cc_forward(): unknown preset '{output}'. "
2692			"Use 'cc', 'cc:N' (e.g. 'cc:74'), 'pitchwheel', or a callable."
2693		)
2694
2695
2696	def cc_forward (
2697		self,
2698		cc: int,
2699		output: typing.Union[str, typing.Callable],
2700		*,
2701		channel: typing.Optional[int] = None,
2702		output_channel: typing.Optional[int] = None,
2703		mode: str = "instant",
2704		input_device: subsequence.midi_utils.DeviceId = None,
2705		output_device: subsequence.midi_utils.DeviceId = None,
2706	) -> None:
2707
2708		"""
2709		Forward an incoming MIDI CC to the MIDI output in real-time.
2710
2711		Unlike ``cc_map()`` which writes incoming CC values to ``composition.data``
2712		for use at pattern rebuild time, ``cc_forward()`` routes the signal
2713		directly to the MIDI output — bypassing the pattern cycle entirely.
2714
2715		Both ``cc_map()`` and ``cc_forward()`` may be registered for the same CC
2716		number; they operate independently.
2717
2718		Parameters:
2719			cc: Incoming CC number to listen for (0–127).
2720			output: What to send. Either a **preset string**:
2721
2722				- ``"cc"`` — identity forward, same CC number and value.
2723				- ``"cc:N"`` — forward as CC number N (e.g. ``"cc:74"``).
2724				- ``"pitchwheel"`` — scale 0–127 to -8192..8191 and send as pitch bend.
2725
2726				Or a **callable** with signature
2727				``(value: int, channel: int) -> Optional[mido.Message]``.
2728				Return a fully formed ``mido.Message`` to send, or ``None`` to suppress.
2729				``channel`` is 0-indexed (the incoming channel).
2730			channel: If given, only respond to CC messages on this channel.
2731				Uses the same numbering convention as ``cc_map()``.
2732				``None`` matches any channel (default).
2733			output_channel: Override the output channel. ``None`` uses the
2734				incoming channel. Uses the same numbering convention as ``pattern()``.
2735			mode: Dispatch mode:
2736
2737				- ``"instant"`` *(default)* — send immediately on the MIDI input
2738				  callback thread. Lowest latency (~1–5 ms). Instant forwards are
2739				  **not** recorded when recording is enabled.
2740				- ``"queued"`` — inject into the sequencer event queue and send at
2741				  the next pulse boundary (~0–20 ms at 120 BPM). Queued forwards
2742				  **are** recorded when recording is enabled.
2743
2744		Example:
2745			```python
2746			comp.midi_input("Arturia KeyStep")
2747
2748			# CC 1 → CC 1 (identity, instant)
2749			comp.cc_forward(1, "cc")
2750
2751			# CC 1 → pitch bend on channel 1, queued (recordable)
2752			comp.cc_forward(1, "pitchwheel", output_channel=1, mode="queued")
2753
2754			# CC 1 → CC 74, custom channel
2755			comp.cc_forward(1, "cc:74", output_channel=2)
2756
2757			# Custom transform — remap CC range 0–127 to CC 74 range 40–100
2758			import subsequence.midi as midi
2759			comp.cc_forward(1, lambda v, ch: midi.cc(74, int(v / 127 * 60) + 40, channel=ch))
2760
2761			# Forward AND map to data simultaneously — both active on the same CC
2762			comp.cc_map(1, "mod_wheel")
2763			comp.cc_forward(1, "cc:74")
2764			```
2765		"""
2766
2767		if not 0 <= cc <= 127:
2768			raise ValueError(f"cc_forward(): cc {cc} out of range 0–127")
2769
2770		if mode not in ('instant', 'queued'):
2771			raise ValueError(f"cc_forward(): mode must be 'instant' or 'queued', got '{mode}'")
2772
2773		resolved_in_channel = self._resolve_channel(channel) if channel is not None else None
2774		resolved_out_channel = self._resolve_channel(output_channel) if output_channel is not None else None
2775
2776		transform = self._make_cc_forward_transform(output, cc, resolved_out_channel)
2777
2778		self._cc_forwards.append({
2779			'cc': cc,
2780			'channel': resolved_in_channel,
2781			'output_channel': resolved_out_channel,
2782			'mode': mode,
2783			'transform': transform,
2784			'input_device': input_device,   # resolved to int index in _run()
2785			'output_device': output_device, # resolved to int index in _run()
2786		})
2787
2788
2789	def live (self, port: int = 5555) -> None:
2790
2791		"""
2792		Enable the live coding eval server.
2793
2794		This allows you to connect to a running composition using the
2795		`subsequence.live_client` REPL and hot-swap pattern code or
2796		modify variables in real-time.
2797
2798		Security:
2799			The server executes arbitrary Python in this process — it is **not** a
2800			sandbox.  It binds to localhost only and is opt-in, but any process on
2801			the same machine that can reach the port gains full code execution here.
2802			Do not enable it on shared or multi-user hosts, and never expose the
2803			port to a network.
2804
2805		Parameters:
2806			port: The TCP port to listen on (default 5555).
2807		"""
2808
2809		self._live_server = subsequence.live_server.LiveServer(self, port=port)
2810		self._is_live = True
2811
2812	def watch (self, path: typing.Union[str, pathlib.Path], poll_interval: float = 0.25) -> None:
2813
2814		"""Watch a Python file and reload it into the composition on every save.
2815
2816		The watched file is exec'd into a namespace with ``composition`` and
2817		``subsequence`` available.  ``@composition.pattern`` decorators inside
2818		the file hot-swap their corresponding running patterns in place;
2819		patterns whose function bodies have been deleted from the file are
2820		unregistered automatically on the next reload (notes stopped,
2821		removed from the running-pattern set).
2822
2823		An **initial synchronous load** happens here — if the file has a
2824		``SyntaxError`` or doesn't exist at this moment, the exception
2825		propagates so the user knows immediately.  Subsequent reloads
2826		happen on the composition's event loop and tolerate transient
2827		errors (logged, skipped).
2828
2829		Call BEFORE ``composition.play()``.  Reloads happen on the
2830		composition's event loop, so all mutations are thread-safe.
2831
2832		See the "Live coding via file watching" section of the README for
2833		the recommended wrapper-script + live-file split.
2834
2835		Parameters:
2836			path: Path to the Python file to watch.
2837			poll_interval: Seconds between ``mtime`` polls (default 0.25 s).
2838
2839		Example::
2840
2841			# live_init.py — runs once
2842			composition = subsequence.Composition(bpm=120, key="E")
2843			composition.harmony(style="aeolian_minor")
2844			composition.watch("live_patterns.py")
2845			composition.play()
2846		"""
2847
2848		# Required for the decorator hot-swap path to fire on re-decoration.
2849		self._is_live = True
2850
2851		# Detect the single-file workflow: if watch() is called from inside
2852		# the very file being watched, the outer Python script execution will
2853		# already register the patterns (the decorators sit at module level
2854		# below ``watch(__file__)``).  In that case, _load_initial's re-exec
2855		# would double-register every pattern, so skip it.  For the two-file
2856		# workflow (path != caller's __file__) the initial exec is essential
2857		# — it's the only way the watched file's patterns ever reach the
2858		# composition.
2859		caller_file = self._caller_module_file()
2860		self_watch = False
2861		if caller_file is not None:
2862			try:
2863				self_watch = pathlib.Path(caller_file).resolve() == pathlib.Path(path).resolve()
2864			except OSError:
2865				self_watch = False
2866
2867		self._live_reloader = subsequence.live_reloader.LiveReloader(
2868			composition = self,
2869			path = path,
2870			poll_interval = poll_interval,
2871			skip_initial_exec = self_watch,
2872		)
2873		self._live_reloader.start()
2874
2875	@staticmethod
2876	def _caller_module_file () -> typing.Optional[str]:
2877
2878		"""Return ``__file__`` of the module that invoked the caller, if available.
2879
2880		Walks one frame up the call stack — the immediate caller is
2881		``watch()``, so ``f_back`` is the user's code.  Returns the
2882		module-level ``__file__`` of that frame's globals; ``None`` when
2883		the caller has no ``__file__`` (REPL, exec'd context, etc.).
2884		"""
2885
2886		frame = inspect.currentframe()
2887		if frame is None or frame.f_back is None or frame.f_back.f_back is None:
2888			return None
2889		# f_back = watch(); f_back.f_back = user code calling watch().
2890		return frame.f_back.f_back.f_globals.get("__file__")
2891
2892	def load_patterns (
2893		self,
2894		source:       str,
2895		source_label: str = "<string>",
2896	) -> None:
2897
2898		"""Compile and apply a pattern-source string to the composition.
2899
2900		Equivalent to one ``watch()`` reload triggered by save, but with the
2901		source presented in-memory rather than on disk.  Useful for web /
2902		REST handlers that accept pattern uploads from a trusted contributor,
2903		or for one-shot session loads with no file backing.
2904
2905		Behaviour mirrors ``watch()``:
2906		* The source is exec'd into a fresh namespace with ``composition``
2907		  and ``subsequence`` in scope.
2908		* ``@composition.pattern`` decorators in the source hot-swap their
2909		  corresponding running patterns in place.
2910		* Patterns currently running but **not** declared in the source are
2911		  unregistered — the source is treated as the full new truth.
2912		* If the composition is already playing, the swap happens on the
2913		  event loop thread; the call blocks until it completes.
2914		* If the composition has not yet called ``play()``, the source runs
2915		  on the caller's thread; decorators populate ``_pending_patterns``
2916		  and ``play()`` picks them up in the usual way.
2917
2918		Errors are raised so the caller can act on them:
2919		* ``SyntaxError`` if ``source`` fails to compile.
2920		* The exception raised inside ``exec()`` for any runtime error.
2921		* ``RuntimeError`` if called from inside the composition's own
2922		  event loop thread (would deadlock — see Threading below).
2923
2924		In either failure case, existing composition state is preserved —
2925		the diff-and-unregister phase is skipped if exec raised, so a
2926		half-broken upload cannot tear down working patterns.
2927
2928		Threading:
2929			Designed to be called from a thread DIFFERENT from the
2930			composition's event loop — typically a web-handler worker.
2931			Cannot be called from inside the loop itself (a pattern
2932			callback, an asyncio task spawned by the composition).  From
2933			there, ``await composition._apply_source_async(...)`` directly.
2934
2935		SECURITY WARNING: ``exec()`` is not sandboxed.  The source has full
2936		Python access in this process.  Only pass source from trusted
2937		senders.  The built-in blocklist (``help``, ``input``, ``breakpoint``,
2938		``exit``, ``quit``) prevents calls that would stall the event loop;
2939		it is not a security boundary.
2940
2941		Parameters:
2942			source:       Python source declaring ``@composition.pattern``
2943				functions.
2944			source_label: Identifier used in compile errors and tracebacks
2945				(appears as the filename in ``SyntaxError`` and ``__file__``-
2946				style traceback lines).  Default ``"<string>"``.
2947		"""
2948
2949		# Required for the decorator hot-swap path to fire on re-decoration.
2950		self._is_live = True
2951
2952		# Compile on the caller's thread so SyntaxError comes back fast,
2953		# before any cross-thread scheduling.
2954		compiled = compile(source, source_label, "exec")
2955		namespace = self._build_live_namespace(source_label = source_label)
2956
2957		loop = self._sequencer._event_loop
2958
2959		if loop is not None and loop.is_running():
2960
2961			# Refuse to deadlock: calling load_patterns() from inside the
2962			# composition's own event loop (e.g. from a pattern callback or
2963			# an asyncio task spawned by the composition) would have us
2964			# block waiting for a coroutine that can only run when this
2965			# thread yields.  Tell the caller exactly what to do instead.
2966			try:
2967				current_loop: typing.Optional[asyncio.AbstractEventLoop] = asyncio.get_running_loop()
2968			except RuntimeError:
2969				current_loop = None
2970
2971			if current_loop is loop:
2972				raise RuntimeError(
2973					"load_patterns() cannot be called from inside the composition's "
2974					"event loop thread — it would deadlock waiting for the "
2975					"scheduled coroutine to run on the very thread that's blocked. "
2976					"From a worker thread, call it normally.  From an async "
2977					"coroutine already on the loop, "
2978					"`await composition._apply_source_async(compile(source, label, 'exec'), "
2979					"composition._build_live_namespace())` instead."
2980				)
2981
2982			# Composition is playing — mutation must happen on the loop thread.
2983			# future.result() blocks the caller until the coroutine finishes
2984			# and re-raises any exception it threw.
2985			future = asyncio.run_coroutine_threadsafe(
2986				self._apply_source_async(compiled, namespace),
2987				loop = loop,
2988			)
2989			future.result()
2990
2991		else:
2992			# Pre-play: no event loop yet.  Decorators populate
2993			# _pending_patterns; play() graduates them in the usual way.
2994			# Diff-and-unregister is unnecessary here — nothing is running.
2995			exec(compiled, namespace)
2996
2997	async def _apply_source_async (
2998		self,
2999		compiled:  types.CodeType,
3000		namespace: typing.Dict[str, typing.Any],
3001	) -> None:
3002
3003		"""Execute pre-compiled live source against the running composition.
3004
3005		Runs on the event loop thread.  Performs ``exec()``, graduates any
3006		newly-decorated patterns into ``_running_patterns``, then unregisters
3007		any patterns that were running but absent from the source.
3008
3009		Raises whatever ``exec()`` raises.  When that happens, the diff-and-
3010		unregister phase is skipped — the namespace is incomplete, so any
3011		patterns the source failed to reach would be misinterpreted as
3012		deletions and torn down.
3013
3014		Called from two places:
3015		* ``Composition.load_patterns()`` via ``run_coroutine_threadsafe``.
3016		* ``LiveReloader._reload_async`` directly (already on the loop).
3017		"""
3018
3019		# Track which patterns the source declares this exec.  pattern() and
3020		# layer() add their (resolved) names to _declared_names as they run, so
3021		# this covers decorated patterns AND layer()/merged patterns — the latter
3022		# have no module-level callable to match against by name, which is why the
3023		# old namespace-based diff tore layers down on every reload.
3024		self._declared_names = set()
3025
3026		# Bail before any state mutation if exec raises — propagates to
3027		# the caller (load_patterns re-raises; LiveReloader catches + logs).
3028		exec(compiled, namespace)
3029
3030		# Graduate newly-decorated patterns from _pending_patterns into
3031		# _running_patterns so they start firing on the next reschedule.
3032		# Patterns that hot-swapped via the decorator/layer path don't appear
3033		# in _pending_patterns and don't need this step.
3034		await self._activate_new_pending_patterns()
3035
3036		# Detect deletions: anything currently running but NOT declared by the
3037		# just-exec'd source has been removed by the user and should be torn
3038		# down.  Decorators/layer() do NOT remove from _running_patterns when a
3039		# definition disappears from the source.
3040		for name in list(self._running_patterns.keys()):
3041			if name not in self._declared_names:
3042				self.unregister(name)
3043
3044	def _build_live_namespace (self, source_label: str = "<live>") -> typing.Dict[str, typing.Any]:
3045
3046		"""Build a fresh namespace dict for exec'ing live source.
3047
3048		Provides ``composition`` (this Composition), ``subsequence`` (the
3049		package), and a safe builtins set with ``help``, ``input``,
3050		``breakpoint``, ``exit``, ``quit`` blocked.
3051
3052		Also injects two dunder globals that make the single-file live-coding
3053		workflow ergonomic:
3054
3055		* ``__name__ = "__live_reload__"`` — so ``if __name__ == "__main__":``
3056		  blocks in the watched file are *skipped* during live reload.  The
3057		  same file run directly with ``python my_session.py`` sees
3058		  ``__name__ == "__main__"`` and runs setup; saves trigger reload
3059		  with ``__name__ == "__live_reload__"``, skipping setup and only
3060		  re-running pattern definitions.
3061		* ``__file__ = source_label`` — so ``composition.watch(__file__)``
3062		  and any user code referencing ``__file__`` works inside the live
3063		  namespace.  Set to the file path for ``LiveReloader``, the
3064		  user-supplied ``source_label`` for ``Composition.load_patterns``,
3065		  and ``"<live>"`` for ``LiveServer``.
3066
3067		Single source of truth: ``live_reloader`` (file watching),
3068		``live_server`` (TCP REPL), and ``load_patterns`` (string source)
3069		all call this so live source sees the same environment from any
3070		entry point.
3071
3072		The blocklist prevents calls that would stall the async event loop
3073		running the sequencer.  It is **not** a security sandbox — exec'd
3074		code can still do anything Python allows.
3075
3076		Parameters:
3077			source_label: Value to bind to ``__file__`` in the namespace.
3078				Defaults to ``"<live>"``.
3079		"""
3080
3081		import subsequence  # local import: this module is imported during subsequence init
3082
3083		safe_builtins = {name: getattr(builtins, name) for name in dir(builtins)}
3084
3085		blocked = {"help", "input", "breakpoint", "exit", "quit"}
3086
3087		for name in blocked:
3088			safe_builtins[name] = _live_blocked(name)
3089
3090		return {
3091			"__builtins__": safe_builtins,
3092			"__name__":     "__live_reload__",
3093			"__file__":     source_label,
3094			"composition":  self,
3095			"subsequence":  subsequence,
3096		}
3097
3098	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:
3099
3100		"""
3101		Enable bi-directional Open Sound Control (OSC).
3102
3103		Subsequence will listen for commands (like `/bpm` or `/mute`) and
3104		broadcast its internal state (like `/chord` or `/bar`) over UDP.
3105
3106		Parameters:
3107			receive_port: Port to listen for incoming OSC messages (default 9000).
3108			send_port: Port to send state updates to (default 9001).
3109			send_host: The IP address to send updates to (default "127.0.0.1").
3110			receive_host: Interface to listen on (default "0.0.0.0" — all
3111				interfaces, so external OSC controllers on the LAN can reach it).
3112				The listener can change tempo, mute patterns, and write data, so on
3113				an untrusted network restrict it with ``receive_host="127.0.0.1"``.
3114		"""
3115
3116		self._osc_server = subsequence.osc.OscServer(
3117			self,
3118			receive_port = receive_port,
3119			send_port = send_port,
3120			send_host = send_host,
3121			receive_host = receive_host
3122		)
3123
3124	def osc_map (self, address: str, handler: typing.Callable) -> None:
3125
3126		"""
3127		Register a custom OSC handler.
3128
3129		Must be called after :meth:`osc` has been configured.
3130
3131		Parameters:
3132			address: OSC address pattern to match (e.g. ``"/my/param"``).
3133			handler: Callable invoked with ``(address, *args)`` when a
3134				matching message arrives.
3135
3136		Example::
3137
3138			composition.osc()
3139
3140			def on_intensity (address, value):
3141				composition.data["intensity"] = float(value)
3142
3143			composition.osc_map("/intensity", on_intensity)
3144		"""
3145
3146		if self._osc_server is None:
3147			raise RuntimeError("Call composition.osc() before composition.osc_map()")
3148
3149		self._osc_server.map(address, handler)
3150
3151	def set_bpm (self, bpm: float) -> None:
3152
3153		"""
3154		Instantly change the tempo.
3155
3156		Parameters:
3157			bpm: The new tempo in beats per minute.
3158
3159		When Ableton Link is active, this proposes the new tempo to the Link
3160		network instead of applying it locally.  The network-authoritative tempo
3161		is picked up on the next pulse.
3162		"""
3163
3164		self._sequencer.set_bpm(bpm)
3165
3166		if not self.is_clock_following and self._link_quantum is None:
3167			self.bpm = bpm
3168
3169	def target_bpm (self, bpm: float, bars: int, shape: str = "linear") -> None:
3170
3171		"""
3172		Smoothly ramp the tempo to a target value over a number of bars.
3173
3174		Parameters:
3175			bpm: Target tempo in beats per minute.
3176			bars: Duration of the transition in bars.
3177			shape: Easing curve name.  Defaults to ``"linear"``.
3178			       ``"ease_in_out"`` or ``"s_curve"`` are recommended for natural-
3179			       sounding tempo changes.  See :mod:`subsequence.easing` for all
3180			       available shapes.
3181
3182		Example:
3183			```python
3184			# Accelerate to 140 BPM over the next 8 bars with a smooth S-curve
3185			comp.target_bpm(140, bars=8, shape="ease_in_out")
3186			```
3187
3188		Note:
3189			Ignored while Ableton Link is active — the shared session tempo is
3190			authoritative.  Use ``set_bpm()`` to propose a tempo to the Link network.
3191		"""
3192
3193		self._sequencer.set_target_bpm(bpm, bars, shape)
3194
3195	def live_info (self) -> typing.Dict[str, typing.Any]:
3196
3197		"""
3198		Return a dictionary containing the current state of the composition.
3199		
3200		Includes BPM, key, current bar, active section, current chord, 
3201		running patterns, and custom data.
3202		"""
3203
3204		section_info = None
3205		if self._form_state is not None:
3206			section = self._form_state.get_section_info()
3207			if section is not None:
3208				section_info = {
3209					"name": section.name,
3210					"bar": section.bar,
3211					"bars": section.bars,
3212					"progress": section.progress
3213				}
3214
3215		chord_name = None
3216		sounding_chord = self.current_chord()
3217		if sounding_chord is not None:
3218			chord_name = sounding_chord.name()
3219
3220		pattern_list = []
3221		channel_offset = 0 if self._zero_indexed_channels else 1
3222		for name, pat in self._running_patterns.items():
3223			pattern_list.append({
3224				"name": name,
3225				"channel": pat.channel + channel_offset,
3226				"length": pat.length,
3227				"cycle": pat._cycle_count,
3228				"muted": pat._muted,
3229				"tweaks": dict(pat._tweaks)
3230			})
3231
3232		return {
3233			"bpm": self._sequencer.current_bpm,
3234			"key": self.key,
3235			"bar": self._builder_bar,
3236			"section": section_info,
3237			"chord": chord_name,
3238			"patterns": pattern_list,
3239			"input_device": self._input_device,
3240			"clock_follow": self.is_clock_following,
3241			"data": self.data
3242		}
3243
3244	def mute (self, name: str) -> None:
3245
3246		"""
3247		Mute a running pattern by name.
3248		
3249		The pattern continues to 'run' and increment its cycle count in 
3250		the background, but it will not produce any MIDI notes until unmuted.
3251
3252		Parameters:
3253			name: The function name of the pattern to mute.
3254		"""
3255
3256		if name not in self._running_patterns:
3257			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3258
3259		self._running_patterns[name]._muted = True
3260		logger.info(f"Muted pattern: {name}")
3261
3262	def unmute (self, name: str) -> None:
3263
3264		"""
3265		Unmute a previously muted pattern.
3266		"""
3267
3268		if name not in self._running_patterns:
3269			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3270
3271		self._running_patterns[name]._muted = False
3272		logger.info(f"Unmuted pattern: {name}")
3273
3274	def unregister (self, name: str) -> None:
3275
3276		"""Fully remove a running pattern from rotation.
3277
3278		Unlike ``mute()`` (which keeps the pattern alive but silent),
3279		``unregister()`` tears the pattern down entirely.  It sets
3280		``pattern._removed = True`` so the sequencer's reschedule loop
3281		skips re-adding it on the next pulse; sends ``note_off`` for any
3282		of the pattern's currently-sounding notes on the primary
3283		destination AND on every mirror destination (so drones and
3284		sustaining notes stop immediately); and removes the entry from
3285		``_running_patterns`` so it no longer appears in ``live_info()``,
3286		the terminal grid, or any other consumer that enumerates running
3287		patterns.
3288
3289		Already-queued events in the sequencer's event queue play out —
3290		note_offs are paired with their note_ons at queue time, so notes
3291		end at their natural duration; only drones rely on the targeted
3292		``_stop_pattern_notes`` pass.
3293
3294		Idempotent: silently logs a ``debug`` and returns if the pattern
3295		is already absent.  Useful from both the live REPL
3296		(``composition.live()``) and the file watcher
3297		(``composition.watch()``), which calls this for any pattern
3298		removed from the watched file between reloads.
3299
3300		Parameters:
3301			name: Function name of the pattern to remove.
3302		"""
3303
3304		if name not in self._running_patterns:
3305			logger.debug(f"unregister() no-op: pattern '{name}' not running")
3306			return
3307
3308		pattern = self._running_patterns[name]
3309
3310		# Mark for removal first so the reschedule loop sees the flag even if
3311		# it fires concurrently with the note-off pass below.
3312		pattern._removed = True
3313
3314		# Stop sustaining notes (including drones) on every destination this
3315		# pattern outputs to.  Fire-and-forget across threads via the event
3316		# loop; ``_stop_pattern_notes`` acquires the queue lock internally.
3317		if self._sequencer._event_loop is not None:
3318			asyncio.run_coroutine_threadsafe(
3319				self._sequencer._stop_pattern_notes(pattern),
3320				loop = self._sequencer._event_loop,
3321			)
3322
3323		def _finalise_removal () -> None:
3324			self._running_patterns.pop(name, None)
3325
3326			# Forget any pending (not-yet-graduated) declaration too, so a
3327			# later live reload cannot resurrect the pattern.
3328			self._pending_patterns = [
3329				pending for pending in self._pending_patterns
3330				if pending.builder_fn.__name__ != name
3331			]
3332
3333			logger.info(f"Unregistered pattern: {name}")
3334
3335		# The running-patterns dict is iterated by the display, web UI, and
3336		# reschedule loop on the event loop thread — mutate it there when this
3337		# call arrives from another thread (e.g. the live TCP server).
3338		loop = self._sequencer._event_loop
3339
3340		try:
3341			on_loop = loop is not None and asyncio.get_running_loop() is loop
3342		except RuntimeError:
3343			on_loop = False
3344
3345		if loop is not None and loop.is_running() and not on_loop:
3346			loop.call_soon_threadsafe(_finalise_removal)
3347		else:
3348			_finalise_removal()
3349
3350	def mirror (self, name: str, device: int, channel: int, drum_note_map: typing.Optional[typing.Dict[str, int]] = None) -> None:
3351
3352		"""
3353		Add a mirror destination to a running pattern.
3354
3355		Every note, CC, pitch bend, NRPN/RPN, program change, SysEx, and drone
3356		event the pattern emits will also be sent to ``(device, channel)``,
3357		starting from the next cycle rebuild.  Idempotent on ``(device, channel)``
3358		— calling with the same destination twice does not double-fan; calling
3359		again with a different ``drum_note_map`` re-points it in place.
3360
3361		Parameters:
3362			name: Function name of the pattern to mirror.
3363			device: Output device index (the integer returned from
3364				``midi_output()``; 0 = primary device).
3365			channel: MIDI channel using this composition's numbering convention
3366				(1-16 by default; 0-15 if ``zero_indexed_channels=True``).
3367			drum_note_map: Optional per-destination drum map.  When set, mirrored
3368				drum hits are re-resolved by name through it, so a named voice
3369				lands on this device's own note number — see the README
3370				"MIDI mirroring" section.
3371
3372		Bandwidth: each mirror adds another full copy of the pattern's events.
3373		See the README "MIDI mirroring" section for the tradeoffs.
3374		"""
3375
3376		if name not in self._running_patterns:
3377			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3378
3379		resolved_channel = self._resolve_channel(channel)
3380		prefix = (device, resolved_channel)
3381		entry: subsequence.pattern.MirrorSpec = prefix if drum_note_map is None else (device, resolved_channel, drum_note_map)
3382
3383		pattern = self._running_patterns[name]
3384
3385		# Mirror-to-self check: comparing the (device, channel) prefix against the
3386		# live pattern's resolved destination.  Unlike the decorator path this is
3387		# always concrete.
3388		if prefix == (pattern.device, pattern.channel):
3389			logger.warning(
3390				f"Mirror destination {prefix} matches '{name}'s primary destination "
3391				f"— every event will double-fire on this (device, channel).  This is almost "
3392				f"certainly unintended."
3393			)
3394
3395		# Idempotent on (device, channel): replace any existing entry for the same
3396		# destination (so its map can be re-pointed), else append.
3397		existing_index = next((idx for idx, e in enumerate(pattern.mirrors) if (e[0], e[1]) == prefix), None)
3398		if existing_index is None:
3399			pattern.mirrors.append(entry)
3400			logger.info(f"Mirror added: {name} -> device={device}, channel={resolved_channel}")
3401		elif pattern.mirrors[existing_index] != entry:
3402			pattern.mirrors[existing_index] = entry
3403			logger.info(f"Mirror updated: {name} -> device={device}, channel={resolved_channel}")
3404		else:
3405			logger.debug(f"Mirror already present on {name}: device={device}, channel={resolved_channel}")
3406
3407	def unmirror (self, name: str, device: int, channel: int) -> None:
3408
3409		"""
3410		Remove a single mirror destination from a running pattern.
3411
3412		Matches on ``(device, channel)`` only — any attached ``drum_note_map`` is
3413		ignored.  Idempotent: silently does nothing if the destination is not
3414		currently mirrored.  The change applies on the next cycle rebuild.
3415		"""
3416
3417		if name not in self._running_patterns:
3418			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3419
3420		resolved_channel = self._resolve_channel(channel)
3421		prefix = (device, resolved_channel)
3422
3423		pattern = self._running_patterns[name]
3424
3425		filtered = [e for e in pattern.mirrors if (e[0], e[1]) != prefix]
3426		if len(filtered) != len(pattern.mirrors):
3427			pattern.mirrors[:] = filtered
3428			logger.info(f"Mirror removed: {name} -> device={device}, channel={resolved_channel}")
3429		else:
3430			logger.debug(f"unmirror() no-op on {name}: device={device}, channel={resolved_channel} not in mirrors")
3431
3432	def unmirror_all (self, name: str) -> None:
3433
3434		"""
3435		Remove every mirror destination from a running pattern.
3436		"""
3437
3438		if name not in self._running_patterns:
3439			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3440
3441		pattern = self._running_patterns[name]
3442
3443		if pattern.mirrors:
3444			pattern.mirrors.clear()
3445			logger.info(f"All mirrors cleared on pattern: {name}")
3446
3447	def tweak (self, name: str, **kwargs: typing.Any) -> None:
3448
3449		"""Override parameters for a running pattern.
3450
3451		Values set here are available inside the pattern's builder
3452		function via ``p.param()``.  They persist across rebuilds
3453		until explicitly changed or cleared.  Changes take effect
3454		on the next rebuild cycle.
3455
3456		Parameters:
3457			name: The function name of the pattern.
3458			**kwargs: Parameter names and their new values.
3459
3460		Example (from the live REPL)::
3461
3462			composition.tweak("bass", pitches=[48, 52, 55, 60])
3463		"""
3464
3465		if name not in self._running_patterns:
3466			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3467
3468		self._running_patterns[name]._tweaks.update(kwargs)
3469		logger.info(f"Tweaked pattern '{name}': {list(kwargs.keys())}")
3470
3471	def clear_tweak (self, name: str, *param_names: str) -> None:
3472
3473		"""Remove tweaked parameters from a running pattern.
3474
3475		If no parameter names are given, all tweaks for the pattern
3476		are cleared and every ``p.param()`` call reverts to its
3477		default.
3478
3479		Parameters:
3480			name: The function name of the pattern.
3481			*param_names: Specific parameter names to clear.  If
3482				omitted, all tweaks are removed.
3483		"""
3484
3485		if name not in self._running_patterns:
3486			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3487
3488		if not param_names:
3489			self._running_patterns[name]._tweaks.clear()
3490			logger.info(f"Cleared all tweaks for pattern '{name}'")
3491		else:
3492			for param_name in param_names:
3493				self._running_patterns[name]._tweaks.pop(param_name, None)
3494			logger.info(f"Cleared tweaks for pattern '{name}': {list(param_names)}")
3495
3496	def get_tweaks (self, name: str) -> typing.Dict[str, typing.Any]:
3497
3498		"""Return a copy of the current tweaks for a running pattern.
3499
3500		Parameters:
3501			name: The function name of the pattern.
3502		"""
3503
3504		if name not in self._running_patterns:
3505			raise ValueError(f"Pattern '{name}' not found. Available: {list(self._running_patterns.keys())}")
3506
3507		return dict(self._running_patterns[name]._tweaks)
3508
3509	def schedule (self, fn: typing.Callable, cycle_beats: int, reschedule_lookahead: int = 1, wait_for_initial: bool = False, defer: bool = False) -> None:
3510
3511		"""
3512		Register a custom function to run on a repeating beat-based cycle.
3513
3514		Subsequence automatically runs synchronous functions in a thread pool
3515		so they don't block the timing-critical MIDI clock. Async functions
3516		are run directly on the event loop.
3517
3518		Parameters:
3519			fn: The function to call.
3520			cycle_beats: How often to call it (e.g., 4 = every bar).
3521			reschedule_lookahead: How far in advance to schedule the next call.
3522			wait_for_initial: If True, run the function once during startup
3523				and wait for it to complete before playback begins. This
3524				ensures ``composition.data`` is populated before patterns
3525				first build. Implies ``defer=True`` for the repeating
3526				schedule.
3527			defer: If True, skip the pulse-0 fire and defer the first
3528				repeating call to just before the second cycle boundary.
3529
3530		Raises:
3531			RuntimeError: If called after ``play()`` has started — scheduled
3532				tasks register at startup, so a late registration would be
3533				silently ignored otherwise.
3534		"""
3535
3536		if self._sequencer.running:
3537			raise RuntimeError("schedule() must be called before play() - scheduled tasks register at startup")
3538
3539		self._pending_scheduled.append(_PendingScheduled(fn, cycle_beats, reschedule_lookahead, wait_for_initial, defer))
3540
3541	def form (
3542		self,
3543		sections: typing.Union[
3544			typing.List[typing.Tuple[str, int]],
3545			typing.Iterator[typing.Tuple[str, int]],
3546			typing.Dict[str, typing.Tuple[int, typing.Optional[typing.List[typing.Tuple[str, int]]]]]
3547		],
3548		loop: bool = False,
3549		start: typing.Optional[str] = None
3550	) -> None:
3551
3552		"""
3553		Define the structure (sections) of the composition.
3554
3555		You can define form in three ways:
3556		1. **Graph (Dict)**: Dynamic transitions based on weights.
3557		2. **Sequence (List)**: A fixed order of sections.
3558		3. **Generator**: A Python generator that yields `(name, bars)` pairs.
3559
3560		Parameters:
3561			sections: The form definition (Dict, List, or Generator).
3562			loop: Whether to cycle back to the start (List mode only).
3563			start: The section to start with (Graph mode only).
3564
3565		Example:
3566			```python
3567			# A simple pop structure
3568			comp.form([
3569				("verse", 8),
3570				("chorus", 8),
3571				("verse", 8),
3572				("chorus", 16)
3573			])
3574			```
3575		"""
3576
3577		# Seed FormState at form() time (per-call salt) so build-time walks —
3578		# the frozen clones form_freeze will take — are deterministic without
3579		# play(); the play-time stream is re-dealt name-keyed in _run().
3580		self._form_count += 1
3581
3582		self._form_state = subsequence.form_state.FormState(
3583			sections,
3584			loop = loop,
3585			start = start,
3586			rng = self._stream(f"form:{self._form_count}")
3587		)
3588
3589	@staticmethod
3590	def _resolve_length (
3591		beats: typing.Optional[float],
3592		bars: typing.Optional[float],
3593		steps: typing.Optional[float],
3594		step_duration: typing.Optional[float],
3595		default: float = 4.0,
3596		beats_per_bar: int = 4,
3597	) -> typing.Tuple[float, int]:
3598
3599		"""
3600		Resolve the beat_length and default_grid from the duration parameters.
3601
3602		Two modes:
3603		- **Duration mode** (no ``step_duration``): specify ``beats=`` or ``bars=``.
3604		  ``beats=4`` = 4 quarter notes; ``bars=2`` = 8 beats.
3605		- **Step mode** (with ``step_duration``): specify ``steps=`` and ``step_duration=``.
3606		  ``steps=6, step_duration=dur.SIXTEENTH`` = 6 sixteenth notes = 1.5 beats.
3607
3608		Constraints:
3609		- ``beats`` and ``bars`` are mutually exclusive.
3610		- ``steps`` requires ``step_duration``; ``step_duration`` requires ``steps``.
3611		- ``steps`` cannot be combined with ``beats`` or ``bars``.
3612
3613		Returns:
3614			(beat_length, default_grid) — beat_length in beats (quarter notes);
3615			default_grid the number of grid steps (16th-notes in beat mode, or the
3616			explicit ``steps`` value directly in step mode).
3617		"""
3618
3619		if beats is not None and bars is not None:
3620			raise ValueError("Specify only one of beats= or bars=")
3621
3622		if steps is not None and (beats is not None or bars is not None):
3623			raise ValueError("steps= cannot be combined with beats= or bars=")
3624
3625		if step_duration is not None and steps is None:
3626			raise ValueError("step_duration= requires steps= (e.g. steps=6, step_duration=dur.SIXTEENTH)")
3627
3628		if steps is not None:
3629			if step_duration is None:
3630				raise ValueError("steps= requires step_duration= (e.g. step_duration=dur.SIXTEENTH)")
3631			return steps * step_duration, int(steps)
3632
3633		if bars is not None:
3634			raw = bars * beats_per_bar
3635		elif beats is not None:
3636			raw = beats
3637		else:
3638			raw = default
3639
3640		return raw, round(raw / subsequence.constants.durations.SIXTEENTH)
3641
3642	def pattern (
3643		self,
3644		channel: int,
3645		beats: typing.Optional[float] = None,
3646		bars: typing.Optional[float] = None,
3647		steps: typing.Optional[float] = None,
3648		step_duration: typing.Optional[float] = None,
3649		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
3650		cc_name_map: typing.Optional[typing.Dict[str, int]] = None,
3651		nrpn_name_map: typing.Optional[typing.Dict[str, int]] = None,
3652		reschedule_lookahead: float = 1,
3653		voice_leading: bool = False,
3654		device: subsequence.midi_utils.DeviceId = None,
3655		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
3656	) -> typing.Callable:
3657
3658		"""
3659		Register a function as a repeating MIDI pattern.
3660
3661		The decorated function will be called once per cycle to 'rebuild' its
3662		content. This allows for generative logic that evolves over time.
3663
3664		Two ways to specify pattern length:
3665
3666		- **Duration mode** (default): use ``beats=`` or ``bars=``.
3667		  The grid defaults to sixteenth-note resolution.
3668		- **Step mode**: use ``steps=`` paired with ``step_duration=``.
3669		  The grid equals the step count, so ``p.hit_steps()`` indices map
3670		  directly to steps.
3671
3672		Parameters:
3673			channel: MIDI channel. By default uses 1-based numbering (1-16).
3674				Set ``zero_indexed_channels=True`` on the ``Composition`` to use
3675				0-based numbering (0-15), matching the raw MIDI protocol, instead.
3676			beats: Duration in beats (quarter notes). ``beats=4`` = 1 bar.
3677			bars: Duration in bars (uses the composition's time signature — 4 beats each in 4/4). ``bars=2`` = 8 beats.
3678			steps: Step count for step mode. Requires ``step_duration=``.
3679			step_duration: Duration of one step in beats (e.g. ``dur.SIXTEENTH``).
3680				Requires ``steps=``.
3681			drum_note_map: Optional mapping for drum instruments.
3682			cc_name_map: Optional mapping of CC names to MIDI CC numbers.
3683				Enables string-based CC names in ``p.cc()`` and ``p.cc_ramp()``.
3684			nrpn_name_map: Optional mapping of NRPN parameter names (strings) to
3685				14-bit parameter numbers (0–16383).  Enables string-based names
3686				in ``p.nrpn()`` and ``p.nrpn_ramp()`` — typically a
3687				device-specific dictionary (e.g. Sequential Take 5's
3688				``Osc1FreqFine`` → 9).
3689			reschedule_lookahead: Beats in advance to compute the next cycle.
3690			voice_leading: If True, chords in this pattern will automatically
3691				use inversions that minimize voice movement.
3692			mirrors: Optional list of additional ``(device, channel)`` destinations
3693				to duplicate every event from this pattern onto.  Notes, CCs, pitch
3694				bend, NRPN/RPN bursts, program changes, SysEx, and drone events are
3695				all mirrored; OSC events are not (OSC is not bound to a MIDI port).
3696				``device`` is the integer index returned by ``midi_output()`` (0 =
3697				primary).  ``channel`` follows this composition's channel-numbering
3698				convention.  See also ``mirror()`` / ``unmirror()`` for live toggling.
3699
3700		Example:
3701			```python
3702			@comp.pattern(channel=1, beats=4)
3703			def chords (p):
3704				p.chord([60, 64, 67], beat=0, velocity=80, duration=3.9)
3705
3706			@comp.pattern(channel=1, bars=2)
3707			def long_phrase (p):
3708				...
3709
3710			@comp.pattern(channel=1, steps=6, step_duration=dur.SIXTEENTH)
3711			def riff (p):
3712				p.sequence(steps=[0, 1, 3, 5], pitches=60)
3713			```
3714		"""
3715
3716		channel = self._resolve_channel(channel)
3717
3718		beat_length, default_grid = self._resolve_length(beats, bars, steps, step_duration, beats_per_bar=self.time_signature[0])
3719
3720		# Resolve device string name to index if possible now; otherwise store
3721		# the raw DeviceId and resolve it in _run() once all devices are open.
3722		resolved_device: subsequence.midi_utils.DeviceId = device
3723
3724		# Mirror-to-self check is only reliable when the primary device is a
3725		# concrete integer at decoration time.  ``None`` resolves to device 0
3726		# downstream, so we treat it as 0 here too.  Strings are deferred to
3727		# ``_run()`` and we skip the check for them.
3728		primary: typing.Optional[typing.Tuple[int, int]]
3729		if isinstance(resolved_device, str):
3730			primary = None
3731		else:
3732			primary = (resolved_device if resolved_device is not None else 0, channel)
3733		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
3734
3735		def decorator (fn: typing.Callable) -> typing.Callable:
3736
3737			"""
3738			Wrap the builder function and register it as a pending pattern.
3739			During live sessions, hot-swap an existing pattern's builder instead.
3740			"""
3741
3742			# Record this declaration so the live-reload deletion diff knows the
3743			# pattern is still present in the source (see _apply_source_async).
3744			self._declared_names.add(fn.__name__)
3745
3746			# Hot-swap: if we're live and a pattern with this name exists, replace its builder.
3747			if self._is_live and fn.__name__ in self._running_patterns:
3748				running = self._running_patterns[fn.__name__]
3749				running._builder_fn = fn
3750				running._wants_chord = _fn_has_parameter(fn, "chord")
3751				logger.info(f"Hot-swapped pattern: {fn.__name__}")
3752				return fn
3753
3754			# Names key the seeded stream, mutes, tweaks, and reroll/lock — a
3755			# duplicate means two scheduled copies sharing one stream with
3756			# only one reachable by name.  Warn loudly at registration.
3757			if any(existing.builder_fn.__name__ == fn.__name__ for existing in self._pending_patterns):
3758				logger.warning(
3759					f"Duplicate pattern name '{fn.__name__}': both copies will be "
3760					f"scheduled, they share one seeded stream, and only one is "
3761					f"reachable by name — rename one of them."
3762				)
3763
3764			pending = _PendingPattern(
3765				builder_fn = fn,
3766				channel = channel,  # already resolved to 0-indexed
3767				length = beat_length,
3768				default_grid = default_grid,
3769				drum_note_map = drum_note_map,
3770				cc_name_map = cc_name_map,
3771				nrpn_name_map = nrpn_name_map,
3772				reschedule_lookahead = reschedule_lookahead,
3773				voice_leading = voice_leading,
3774				# For int/None: resolve immediately.  For str: store 0 as
3775				# placeholder; _resolve_pending_devices() fixes it in _run().
3776				device = 0 if (resolved_device is None or isinstance(resolved_device, str)) else resolved_device,
3777				raw_device = resolved_device,
3778				mirrors = resolved_mirrors,
3779			)
3780
3781			self._pending_patterns.append(pending)
3782
3783			return fn
3784
3785		return decorator
3786
3787	def layer (
3788		self,
3789		*builder_fns: typing.Callable,
3790		channel: int,
3791		beats: typing.Optional[float] = None,
3792		bars: typing.Optional[float] = None,
3793		steps: typing.Optional[float] = None,
3794		step_duration: typing.Optional[float] = None,
3795		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
3796		cc_name_map: typing.Optional[typing.Dict[str, int]] = None,
3797		nrpn_name_map: typing.Optional[typing.Dict[str, int]] = None,
3798		reschedule_lookahead: float = 1,
3799		voice_leading: bool = False,
3800		device: subsequence.midi_utils.DeviceId = None,
3801		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
3802	) -> None:
3803
3804		"""
3805		Combine multiple functions into a single MIDI pattern.
3806
3807		This is useful for composing complex patterns out of reusable
3808		building blocks (e.g., a 'kick' function and a 'snare' function).
3809
3810		See ``pattern()`` for the full description of ``beats``, ``bars``,
3811		``steps``, and ``step_duration``.
3812
3813		Parameters:
3814			builder_fns: One or more pattern builder functions.
3815			channel: MIDI channel (1-16, or 0-15 with ``zero_indexed_channels=True``).
3816			beats: Duration in beats (quarter notes).
3817			bars: Duration in bars (uses the composition's time signature — 4 beats each in 4/4).
3818			steps: Step count for step mode. Requires ``step_duration=``.
3819			step_duration: Duration of one step in beats. Requires ``steps=``.
3820			drum_note_map: Optional mapping for drum instruments.
3821			cc_name_map: Optional mapping of CC names to MIDI CC numbers.
3822			nrpn_name_map: Optional mapping of NRPN parameter names to 14-bit
3823				parameter numbers.
3824			reschedule_lookahead: Beats in advance to compute the next cycle.
3825			voice_leading: If True, chords use smooth voice leading.
3826			mirrors: Optional list of additional ``(device, channel)`` destinations
3827				to duplicate every event onto.  See ``pattern()`` for details.
3828		"""
3829
3830		beat_length, default_grid = self._resolve_length(beats, bars, steps, step_duration, beats_per_bar=self.time_signature[0])
3831
3832		# Resolve channel up-front so the mirror-to-self check has the canonical
3833		# primary form to compare against.
3834		resolved_channel = self._resolve_channel(channel)
3835
3836		# See pattern() for the same comment about None / str handling.
3837		primary: typing.Optional[typing.Tuple[int, int]]
3838		if isinstance(device, str):
3839			primary = None
3840		else:
3841			primary = (device if device is not None else 0, resolved_channel)
3842		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
3843
3844		wants_chord = any(_fn_has_parameter(fn, "chord") for fn in builder_fns)
3845
3846		if wants_chord:
3847
3848			def merged_builder (p: subsequence.pattern_builder.PatternBuilder, chord: _InjectedChord) -> None:
3849
3850				for fn in builder_fns:
3851					if _fn_has_parameter(fn, "chord"):
3852						fn(p, chord)
3853					else:
3854						fn(p)
3855
3856		else:
3857
3858			def merged_builder (p: subsequence.pattern_builder.PatternBuilder) -> None:  # type: ignore[misc]
3859
3860				for fn in builder_fns:
3861					fn(p)
3862
3863		# Give the merged builder a stable, unique name derived from its
3864		# components so multiple layer() calls don't all register under
3865		# "merged_builder" and collide in _running_patterns (which made
3866		# mute/tweak/unregister/live_info reach only the LAST layer).  "+" can't
3867		# appear in a Python identifier, so this never clashes with a real
3868		# pattern function's name.
3869		base_name = ("+".join(fn.__name__ for fn in builder_fns) or "layer") + f"@ch{resolved_channel}"
3870		merged_name = base_name
3871		suffix = 2
3872
3873		# Two layers with the same components (e.g. on different saves of a
3874		# live file) must map to the same names pass-over-pass, while two
3875		# DIFFERENT layers sharing components in one pass must not collide.
3876		while merged_name in self._declared_names:
3877			merged_name = f"{base_name}#{suffix}"
3878			suffix += 1
3879
3880		merged_builder.__name__ = merged_name
3881
3882		# Record the declaration for the live-reload deletion diff, and hot-swap
3883		# in place when this layer is already running so a reload picks up edits
3884		# to the component functions without losing the pattern's cycle count,
3885		# tweaks, or mirrors (mirrors the pattern() decorator's hot-swap).
3886		self._declared_names.add(merged_builder.__name__)
3887
3888		if self._is_live and merged_builder.__name__ in self._running_patterns:
3889			running = self._running_patterns[merged_builder.__name__]
3890			running._builder_fn = merged_builder
3891			running._wants_chord = wants_chord
3892			logger.info(f"Hot-swapped layer: {merged_builder.__name__}")
3893			return
3894
3895		pending = _PendingPattern(
3896			builder_fn = merged_builder,
3897			channel = resolved_channel,  # already resolved to 0-indexed above
3898			length = beat_length,
3899			default_grid = default_grid,
3900			drum_note_map = drum_note_map,
3901			cc_name_map = cc_name_map,
3902			nrpn_name_map = nrpn_name_map,
3903			reschedule_lookahead = reschedule_lookahead,
3904			voice_leading = voice_leading,
3905			mirrors = resolved_mirrors,
3906			device = 0 if (device is None or isinstance(device, str)) else device,
3907			raw_device = device,
3908		)
3909
3910		self._pending_patterns.append(pending)
3911
3912	def chords (
3913		self,
3914		*,
3915		channel: int,
3916		progression: subsequence.progressions.ProgressionSource,
3917		harmonic_rhythm: subsequence.progressions.HarmonicRhythmSpec,
3918		bars: typing.Optional[float] = None,
3919		beats: typing.Optional[float] = None,
3920		voicing: subsequence.progressions.VoicingSpec = (3, 4),
3921		velocity: typing.Union[int, typing.Tuple[int, int]] = subsequence.constants.velocity.DEFAULT_CHORD_VELOCITY,
3922		detached: typing.Optional[float] = None,
3923		root: int = 60,
3924		key: typing.Optional[str] = None,
3925		seed: typing.Optional[int] = None,
3926		device: subsequence.midi_utils.DeviceId = None,
3927		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
3928	) -> subsequence.progressions.Progression:
3929
3930		"""Declare a self-contained chord part: a progression at a chosen harmonic rhythm.
3931
3932		The one-call form of ``p.progression()`` — it registers a pattern on
3933		*channel* that plays *progression* across *bars* (or *beats*), each chord
3934		lasting a length drawn from *harmonic_rhythm* (the musical term for how often
3935		the chords change).  It needs no ``composition.harmony()`` call and, with an
3936		explicit chord list or a ``key=``, no composition key either — so a
3937		drums-plus-one-chord-part sketch stays simple.
3938
3939		The progression is realised once, up front, and the same timeline plays every
3940		cycle (a stable phrase).  That timeline is returned so you can see exactly what
3941		was chosen — ``print(comp.chords(...))``.
3942
3943		Parameters:
3944			channel: MIDI channel for the chord part.
3945			progression: A chord-graph style name to generate from, or an explicit list
3946				of chords (``Chord`` objects or names like ``["Cm7", "Dbmaj7"]``).
3947			harmonic_rhythm: How long each chord lasts — a number, a list of lengths,
3948				or ``between(low, high, step=...)``.  See ``p.progression()``.
3949			bars / beats: Length of the part (defaults to 4 beats if neither is given).  ``bars`` uses the
3950				composition's time signature.
3951			voicing: Notes per chord — an int, or a ``(low, high)`` range (e.g. ``(3, 4)``).
3952			velocity: MIDI velocity, or a ``(low, high)`` tuple for per-voice humanisation.
3953			detached: Beats of silence before each next chord (``duration = length - detached``).
3954			root: MIDI root the voicings are centred on (e.g. 48 = C3).
3955			key: Key for a generated progression; defaults to the composition key.
3956			seed: Seed for the (otherwise fixed) realisation; defaults to the
3957				composition seed, so the part is reproducible.
3958			device: Optional output-device override.
3959			mirrors: Optional additional ``(device, channel)`` destinations.
3960
3961		Returns:
3962			The realised :class:`~subsequence.progressions.Progression`.
3963		"""
3964
3965		beat_length, default_grid = self._resolve_length(beats, bars, None, None, beats_per_bar=self.time_signature[0])
3966		resolved_channel = self._resolve_channel(channel)
3967		resolved_key = key if key is not None else self.key
3968
3969		rng = random.Random(seed if seed is not None else self._seed)
3970		timeline = subsequence.progressions.realize(
3971			source = progression,
3972			harmonic_rhythm = harmonic_rhythm,
3973			key = resolved_key,
3974			length = beat_length,
3975			rng = rng,
3976			scale = self.scale or "ionian",
3977		)
3978
3979		captured_root = root
3980		captured_velocity = velocity
3981		captured_detached = detached
3982		captured_voicing = voicing
3983
3984		def chords_builder (p: subsequence.pattern_builder.PatternBuilder) -> None:
3985
3986			"""Replay the realised timeline as block chords each cycle (voicing per chord)."""
3987
3988			for chord, start, length in timeline:
3989				ring = length - captured_detached if (captured_detached and captured_detached < length) else length
3990				voices = subsequence.progressions.resolve_voices(captured_voicing, p.rng)
3991				p.chord(chord, root=captured_root, beat=start, duration=ring, count=voices, velocity=captured_velocity)
3992
3993		# Unique, stable name so multiple chord parts don't collide in
3994		# _running_patterns — including two parts on the SAME channel, which
3995		# get a deterministic #2/#3 suffix in declaration order.
3996		base_name = f"chords@ch{resolved_channel}"
3997		chords_name = base_name
3998		suffix = 2
3999
4000		while chords_name in self._declared_names:
4001			chords_name = f"{base_name}#{suffix}"
4002			suffix += 1
4003
4004		chords_builder.__name__ = chords_name
4005		self._declared_names.add(chords_name)
4006
4007		primary: typing.Optional[typing.Tuple[int, int]]
4008		if isinstance(device, str):
4009			primary = None
4010		else:
4011			primary = (device if device is not None else 0, resolved_channel)
4012		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
4013
4014		self._declared_names.add(chords_builder.__name__)
4015
4016		if self._is_live and chords_builder.__name__ in self._running_patterns:
4017			running = self._running_patterns[chords_builder.__name__]
4018			running._builder_fn = chords_builder
4019			running._wants_chord = False
4020			logger.info(f"Hot-swapped chords: {chords_builder.__name__}")
4021			return timeline
4022
4023		pending = _PendingPattern(
4024			builder_fn = chords_builder,
4025			channel = resolved_channel,
4026			length = beat_length,
4027			default_grid = default_grid,
4028			drum_note_map = None,
4029			reschedule_lookahead = 1,
4030			voice_leading = False,
4031			mirrors = resolved_mirrors,
4032			device = 0 if (device is None or isinstance(device, str)) else device,
4033			raw_device = device,
4034		)
4035		self._pending_patterns.append(pending)
4036		return timeline
4037
4038	def phrase_part (
4039		self,
4040		*,
4041		channel: int,
4042		part: typing.Optional[str] = None,
4043		root: int = 60,
4044		bars: typing.Optional[float] = None,
4045		beats: typing.Optional[float] = None,
4046		velocity: typing.Optional[typing.Union[int, typing.Tuple[int, int]]] = None,
4047		fit: typing.Optional[float] = None,
4048		device: subsequence.midi_utils.DeviceId = None,
4049		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
4050	) -> None:
4051
4052		"""Declare a part that plays each section's bound Motif/Phrase.
4053
4054		The one-call consumer for :meth:`section_motifs` — it registers a
4055		pattern on *channel* that walks whatever value is bound to the
4056		current section for *part* (stateless position from the cycle
4057		counter, via ``p.phrase()``).  A section with no binding for the
4058		part is **silent** for that part — bind material or don't; no
4059		fallback guessing.
4060
4061		Parameters:
4062			channel: MIDI channel for the part.
4063			part: The part label to read from the registry (``None`` = the
4064				unlabelled binding).
4065			root: Register anchor for degree resolution.
4066			bars / beats: Cycle length of the part (defaults to 4 beats);
4067				the phrase is sliced one cycle window at a time.
4068			velocity: Optional override applied to every note.
4069			fit: Passed through (active with the melody engine stage).
4070			device: Optional output-device override.
4071			mirrors: Optional additional ``(device, channel)`` destinations.
4072
4073		Example::
4074
4075			composition.section_motifs("verse",  verse_line,  part="lead")
4076			composition.section_motifs("chorus", chorus_line, part="lead")
4077			composition.phrase_part(channel=4, part="lead", root=72, bars=2)
4078		"""
4079
4080		beat_length, default_grid = self._resolve_length(beats, bars, None, None, beats_per_bar=self.time_signature[0])
4081		resolved_channel = self._resolve_channel(channel)
4082
4083		captured_part = part
4084		captured_root = root
4085		captured_velocity = velocity
4086		captured_fit = fit
4087
4088		def phrase_builder (p: subsequence.pattern_builder.PatternBuilder) -> None:
4089
4090			"""Walk the current section's bound value (silent when unbound)."""
4091
4092			value = p.section_motif(captured_part)
4093
4094			if value is None:
4095				return	# unbound section: silence for this part, by design
4096
4097			p.phrase(value, root=captured_root, velocity=captured_velocity, fit=captured_fit)
4098
4099		# Unique, stable name so multiple phrase parts don't collide —
4100		# including two parts on the SAME channel (deterministic #2/#3
4101		# suffixes in declaration order, the chords() convention).
4102		base_name = f"phrase@{captured_part}@ch{resolved_channel}" if captured_part else f"phrase@ch{resolved_channel}"
4103		phrase_name = base_name
4104		suffix = 2
4105
4106		while phrase_name in self._declared_names:
4107			phrase_name = f"{base_name}#{suffix}"
4108			suffix += 1
4109
4110		phrase_builder.__name__ = phrase_name
4111		self._declared_names.add(phrase_name)
4112
4113		primary: typing.Optional[typing.Tuple[int, int]]
4114		if isinstance(device, str):
4115			primary = None
4116		else:
4117			primary = (device if device is not None else 0, resolved_channel)
4118		resolved_mirrors = self._resolve_mirrors(mirrors, primary=primary)
4119
4120		if self._is_live and phrase_builder.__name__ in self._running_patterns:
4121			running = self._running_patterns[phrase_builder.__name__]
4122			running._builder_fn = phrase_builder
4123			running._wants_chord = False
4124			logger.info(f"Hot-swapped phrase part: {phrase_builder.__name__}")
4125			return
4126
4127		pending = _PendingPattern(
4128			builder_fn = phrase_builder,
4129			channel = resolved_channel,
4130			length = beat_length,
4131			default_grid = default_grid,
4132			drum_note_map = None,
4133			reschedule_lookahead = 1,
4134			voice_leading = False,
4135			mirrors = resolved_mirrors,
4136			device = 0 if (device is None or isinstance(device, str)) else device,
4137			raw_device = device,
4138		)
4139		self._pending_patterns.append(pending)
4140
4141	def trigger (
4142		self,
4143		fn: typing.Callable,
4144		channel: int,
4145		beats: typing.Optional[float] = None,
4146		bars: typing.Optional[float] = None,
4147		steps: typing.Optional[float] = None,
4148		step_duration: typing.Optional[float] = None,
4149		quantize: float = 0,
4150		drum_note_map: typing.Optional[typing.Dict[str, int]] = None,
4151		cc_name_map: typing.Optional[typing.Dict[str, int]] = None,
4152		nrpn_name_map: typing.Optional[typing.Dict[str, int]] = None,
4153		chord: bool = False,
4154		device: subsequence.midi_utils.DeviceId = None,
4155		mirrors: typing.Optional[typing.Iterable[subsequence.pattern.MirrorSpec]] = None,
4156	) -> None:
4157
4158		"""
4159		Trigger a one-shot pattern immediately or on a quantized boundary.
4160
4161		This is useful for real-time response to sensors, OSC messages, or other
4162		external events. The builder function is called immediately with a fresh
4163		PatternBuilder, and the generated events are injected into the queue at
4164		the specified quantize boundary.
4165
4166		The builder function has the same API as a ``@composition.pattern``
4167		decorated function and can use all PatternBuilder methods: ``p.note()``,
4168		``p.euclidean()``, ``p.arpeggio()``, and so on.
4169
4170		See ``pattern()`` for the full description of ``beats``, ``bars``,
4171		``steps``, and ``step_duration``. Default is 1 beat.
4172
4173		Parameters:
4174			fn: The pattern builder function (same signature as ``@comp.pattern``).
4175			channel: MIDI channel (1-16, or 0-15 with ``zero_indexed_channels=True``).
4176			beats: Duration in beats (quarter notes, default 1).
4177			bars: Duration in bars (uses the composition's time signature — 4 beats each in 4/4).
4178			steps: Step count for step mode. Requires ``step_duration=``.
4179			step_duration: Duration of one step in beats. Requires ``steps=``.
4180			quantize: Snap the trigger to a beat boundary: ``0`` = immediate (default),
4181				``1`` = next beat (quarter note), ``4`` = next bar. Use ``dur.*``
4182				constants from ``subsequence.constants.durations``.
4183			drum_note_map: Optional drum name mapping for this pattern.
4184			cc_name_map: Optional mapping of CC names to MIDI CC numbers.
4185			nrpn_name_map: Optional mapping of NRPN parameter names to
4186				14-bit parameter numbers.
4187			chord: If ``True``, the builder function receives the current chord as
4188				a second parameter (same as ``@composition.pattern``).
4189			mirrors: Optional list of additional ``(device, channel)`` destinations
4190				to fire this one-shot onto in parallel with the primary destination.
4191
4192		Example:
4193			```python
4194			# Immediate single note (channels are 1-16 by default)
4195			composition.trigger(
4196				lambda p: p.note(60, beat=0, velocity=100, duration=0.5),
4197				channel=1
4198			)
4199
4200			# Quantized fill (next bar) — channel 10 is the GM drum channel
4201			import subsequence.constants.durations as dur
4202			composition.trigger(
4203				lambda p: p.euclidean("snare", pulses=7, velocity=90),
4204				channel=10,
4205				drum_note_map=gm_drums.GM_DRUM_MAP,
4206				quantize=dur.WHOLE
4207			)
4208
4209			# With chord context — the builder receives the chord as a second
4210			# argument when chord=True.
4211			composition.trigger(
4212				lambda p, chord: p.arpeggio(chord.tones(root=60), spacing=dur.SIXTEENTH),
4213				channel=1,
4214				quantize=dur.QUARTER,
4215				chord=True
4216			)
4217			```
4218		"""
4219
4220		# Resolve channel numbering
4221		resolved_channel = self._resolve_channel(channel)
4222
4223		beat_length, default_grid = self._resolve_length(beats, bars, steps, step_duration, default=1.0, beats_per_bar=self.time_signature[0])
4224
4225		# Resolve device index — for trigger() this is always concrete by call time,
4226		# so the mirror-to-self check has the full primary tuple available.
4227		resolved_device_idx = self._resolve_device_id(device)
4228		resolved_mirrors = self._resolve_mirrors(mirrors, primary=(resolved_device_idx, resolved_channel))
4229
4230		# Create a temporary Pattern
4231		pattern = subsequence.pattern.Pattern(channel=resolved_channel, length=beat_length, device=resolved_device_idx, mirrors=resolved_mirrors)
4232
4233		# Create a PatternBuilder
4234		builder = subsequence.pattern_builder.PatternBuilder(
4235			pattern=pattern,
4236			cycle=0,  # One-shot patterns don't rebuild, so cycle is always 0
4237			drum_note_map=drum_note_map,
4238			cc_name_map=cc_name_map,
4239			nrpn_name_map=nrpn_name_map,
4240			section=self._form_state.get_section_info() if self._form_state else None,
4241			bar=self._builder_bar,
4242			conductor=self.conductor,
4243			rng=random.Random(),  # Fresh random state for each trigger
4244			tweaks={},
4245			default_grid=default_grid,
4246			data=self.data,
4247			held_notes=self._sequencer._held_notes
4248		)
4249
4250		# Call the builder function
4251		try:
4252
4253			current_chord = self.current_chord() if chord else None
4254
4255			if current_chord is not None:
4256				injected = _InjectedChord(current_chord, None)  # No voice leading for one-shots
4257				fn(builder, injected)
4258
4259			else:
4260				fn(builder)
4261
4262		except Exception:
4263			logger.exception("Error in trigger builder — pattern will be silent")
4264			return
4265
4266		# Calculate the start pulse based on quantize
4267		current_pulse = self._sequencer.pulse_count
4268		pulses_per_beat = subsequence.constants.MIDI_QUARTER_NOTE
4269
4270		if quantize == 0:
4271			# Immediate: use current pulse
4272			start_pulse = current_pulse
4273
4274		else:
4275			# Quantize to the next multiple of (quantize * pulses_per_beat)
4276			quantize_pulses = int(quantize * pulses_per_beat)
4277			start_pulse = ((current_pulse // quantize_pulses) + 1) * quantize_pulses
4278
4279		# Schedule the pattern for one-shot execution
4280		try:
4281			# Probe only: raises RuntimeError when not on the event loop.
4282			asyncio.get_running_loop()
4283			asyncio.create_task(self._sequencer.schedule_pattern(pattern, start_pulse))
4284
4285		except RuntimeError:
4286			# Not on the event loop — hand the coroutine to the loop thread.
4287			if self._sequencer._event_loop is not None:
4288				asyncio.run_coroutine_threadsafe(
4289					self._sequencer.schedule_pattern(pattern, start_pulse),
4290					loop=self._sequencer._event_loop
4291				)
4292			else:
4293				logger.warning("trigger() called before playback started; pattern ignored")
4294
4295	@property
4296	def is_clock_following (self) -> bool:
4297
4298		"""True if either the primary or any additional device is following external clock."""
4299
4300		return self._clock_follow or any(cf for _, _, cf in self._additional_inputs)
4301
4302
4303	def play (self) -> None:
4304
4305		"""
4306		Start the composition.
4307
4308		This call blocks until the program is interrupted (e.g., via Ctrl+C).
4309		It initializes the MIDI hardware, launches the background sequencer,
4310		and begins playback.
4311		"""
4312
4313		try:
4314			asyncio.run(self._run())
4315
4316		except KeyboardInterrupt:
4317			pass
4318
4319
4320	def render (self, bars: typing.Optional[int] = None, filename: str = "render.mid", max_minutes: typing.Optional[float] = 60.0) -> None:
4321
4322		"""Render the composition to a MIDI file without real-time playback.
4323
4324		Runs the sequencer as fast as possible (no timing delays) and stops
4325		when the first active limit is reached.  The result is saved as a
4326		standard MIDI file that can be imported into any DAW.
4327
4328		All patterns, scheduled callbacks, and harmony logic run exactly as
4329		they would during live playback — BPM transitions, generative fills,
4330		and probabilistic gates all work in render mode.  The only difference
4331		is that time is simulated rather than wall-clock driven.
4332
4333		Parameters:
4334			bars: Number of bars to render, or ``None`` for no bar limit
4335			      (default ``None``).  When both *bars* and *max_minutes* are
4336			      active, playback stops at whichever limit is reached first.
4337			filename: Output MIDI filename (default ``"render.mid"``).
4338			max_minutes: Safety cap on the length of rendered MIDI in minutes
4339			             (default ``60.0``).  Pass ``None`` to disable the time
4340			             cap — you must then provide an explicit *bars* value.
4341
4342		Raises:
4343			ValueError: If both *bars* and *max_minutes* are ``None``, which
4344			            would produce an infinite render.
4345
4346		Examples:
4347			```python
4348			# Default: renders up to 60 minutes of MIDI content.
4349			composition.render()
4350
4351			# Render exactly 64 bars (time cap still active as backstop).
4352			composition.render(bars=64, filename="demo.mid")
4353
4354			# Render up to 5 minutes of an infinite generative composition.
4355			composition.render(max_minutes=5, filename="five_min.mid")
4356
4357			# Remove the time cap — must supply bars instead.
4358			composition.render(bars=128, max_minutes=None, filename="long.mid")
4359			```
4360		"""
4361
4362		if bars is None and max_minutes is None:
4363			raise ValueError(
4364				"render() requires at least one limit: provide bars=, max_minutes=, or both. "
4365				"Passing both as None would produce an infinite render."
4366			)
4367
4368		self._sequencer.recording = True
4369		self._sequencer.record_filename = filename
4370		self._sequencer.render_mode = True
4371		self._sequencer.render_bars = bars if bars is not None else 0
4372		self._sequencer.render_max_seconds = max_minutes * 60.0 if max_minutes is not None else None
4373		asyncio.run(self._run())
4374
4375	def _broadcast_osc_status (self, bar: int) -> None:
4376
4377		"""
4378		Send the per-bar OSC status snapshot: bar number, current tempo,
4379		and (when active) the current chord name and form section.
4380		"""
4381
4382		if self._osc_server:
4383			self._osc_server.send("/bar", bar)
4384			self._osc_server.send("/bpm", self._sequencer.current_bpm)
4385
4386			sounding = self.current_chord()
4387			if sounding is not None:
4388				self._osc_server.send("/chord", sounding.name())
4389
4390			if self._form_state:
4391				info = self._form_state.get_section_info()
4392				if info:
4393					self._osc_server.send("/section", info.name)
4394
4395	async def _run (self) -> None:
4396
4397		"""
4398		Async entry point that schedules all patterns and runs the sequencer.
4399		"""
4400
4401		# 1. Pre-calculate MIDI input indices and configure sequencer clock follow.
4402		if self._input_device is not None:
4403			self._sequencer.input_device_name = self._input_device
4404			self._sequencer.clock_follow = self._clock_follow
4405			self._sequencer.clock_device_idx = 0
4406
4407			if not self._clock_follow:
4408				# Find first additional input that wants to be the clock master.
4409				for idx, (_, _, cf) in enumerate(self._additional_inputs, start=1):
4410					if cf:
4411						self._sequencer.clock_follow = True
4412						self._sequencer.clock_device_idx = idx
4413						break
4414
4415		# Populate input device name mapping early (before opening ports) so we can
4416		# resolve CC mappings to integer device indices immediately.
4417		if self._sequencer.input_device_name:
4418			self._input_device_names[self._sequencer.input_device_name] = 0
4419			if self._input_device_alias is not None:
4420				self._input_device_names[self._input_device_alias] = 0
4421
4422		for idx, (dev_name, alias, _) in enumerate(self._additional_inputs, start=1):
4423			self._input_device_names[dev_name] = idx
4424			if alias:
4425				self._input_device_names[alias] = idx
4426
4427		# 2. Pre-calculate output device names.
4428		if self._sequencer.output_device_name:
4429			self._output_device_names[self._sequencer.output_device_name] = 0
4430			# Primary device (index 0) is open by now (_init_midi_output ran in
4431			# the Sequencer constructor), so its latency can be set safely here.
4432			if self._output_latency_ms:
4433				self._sequencer.set_device_latency(0, self._output_latency_ms)
4434
4435		# 3. Resolve name-based INPUT device ids in cc_map/cc_forward early — the
4436		# input-names map is fully populated above, and the callback thread needs
4437		# integer indices as soon as ports open.  OUTPUT names (cc_forward
4438		# output_device=, pattern device=) resolve after the additional outputs
4439		# are opened below; resolving them here matched against a map containing
4440		# only the primary and silently routed everything to device 0.
4441		for mapping in self._cc_mappings:
4442			raw = mapping.get('input_device')
4443			if isinstance(raw, str):
4444				mapping['input_device'] = self._resolve_input_device_id(raw)
4445		for fwd in self._cc_forwards:
4446			raw_in = fwd.get('input_device')
4447			if isinstance(raw_in, str):
4448				fwd['input_device'] = self._resolve_input_device_id(raw_in)
4449
4450		# 4. Share CC input mappings, forwards, and a reference to composition.data
4451		# with the sequencer BEFORE opening the ports. This ensures that any initial
4452		# messages in the OS buffer are correctly mapped as soon as the port opens.
4453		self._sequencer.cc_mappings = self._cc_mappings
4454		self._sequencer.cc_forwards = self._cc_forwards
4455		self._sequencer._composition_data = self.data
4456
4457		# Held-note input: create the tracker and resolve its channel/device
4458		# filter so the callback thread can buffer matching note events.
4459		if self._note_input is not None:
4460			if self._input_device is None and not self._additional_inputs:
4461				raise RuntimeError("note_input() requires a MIDI input — call composition.midi_input(device) first")
4462			raw_dev = self._note_input.get('input_device')
4463			if isinstance(raw_dev, str):
4464				raw_dev = self._resolve_input_device_id(raw_dev)
4465			self._sequencer._note_input_channel = self._note_input['channel']
4466			self._sequencer._note_input_device = raw_dev
4467			self._sequencer._held_notes = subsequence.held_notes.HeldNotes(
4468				release_ms = self._note_input['release_ms'],
4469				latch = self._note_input['latch'],
4470			)
4471
4472		# 5. Open MIDI input ports early. Even without a deliberate sleep, opening
4473		# them before pattern building minimizes the window for missed messages.
4474		# Primary input
4475		self._sequencer._open_midi_inputs()
4476
4477		# Additional inputs
4478		for idx, (dev_name, alias, cf) in enumerate(self._additional_inputs, start=1):
4479			# Use the pre-calculated index
4480			callback = self._sequencer._make_input_callback(idx)
4481			open_name, port = subsequence.midi_utils.select_input_device(dev_name, callback)
4482			if open_name and port is not None:
4483				self._sequencer.add_input_device(open_name, port)
4484			else:
4485				logger.warning(f"Could not open additional input device '{dev_name}'")
4486
4487		# 6. Open additional MIDI output devices.
4488		for out in self._additional_outputs:
4489			open_name, port = subsequence.midi_utils.select_output_device(out.device)
4490			if open_name and port is not None:
4491				idx = self._sequencer.add_output_device(open_name, port, out.latency_ms)
4492				self._output_device_names[open_name] = idx
4493				if out.alias is not None:
4494					self._output_device_names[out.alias] = idx
4495			else:
4496				logger.warning(f"Could not open additional output device '{out.device}'")
4497
4498		# Warn if latency compensation adds noticeable whole-rig delay: the
4499		# slowest device defines the alignment point, so every faster device is
4500		# delayed up to that amount and live-input feel suffers.
4501		self._warn_if_high_latency()
4502
4503		# Resolve any name-based output device IDs on patterns that may have been added
4504		# for additional output devices.
4505		self._resolve_pending_devices()
4506
4507		# Resolve cc_forward output-device names now that every output port and
4508		# alias is registered (resolving earlier silently routed to device 0).
4509		for fwd in self._cc_forwards:
4510			raw_out = fwd.get('output_device')
4511			if isinstance(raw_out, str):
4512				fwd['output_device'] = self._resolve_device_id(raw_out)
4513
4514		# Pass clock output flag (suppressed automatically when clock_follow=True).
4515		self._sequencer.clock_output = self._clock_output and not self.is_clock_following
4516
4517		# Create Ableton Link clock if comp.link() was called.
4518		if self._link_quantum is not None:
4519			self._sequencer._link_clock = subsequence.link_clock.LinkClock(
4520				bpm = self.bpm,
4521				quantum = self._link_quantum,
4522				loop = asyncio.get_running_loop(),
4523			)
4524
4525		# Deal play-time streams.  Every stream is NAME-keyed (crc32 of
4526		# "seed:name", see _stream_seed) rather than dealt from one master in
4527		# registration order: adding or removing one consumer can never shift
4528		# another's stream, and patterns added live derive identically in
4529		# _build_pattern_from_pending.  When no seed is set, components keep
4530		# their own unseeded RNGs (existing behaviour).
4531		if self._seed is not None:
4532
4533			harmony_stream = self._stream("play:harmony")
4534			if self._harmonic_state is not None and harmony_stream is not None:
4535				self._harmonic_state.rng = harmony_stream
4536
4537			form_stream = self._stream("play:form")
4538			if self._form_state is not None and form_stream is not None:
4539				self._form_state._rng = form_stream
4540
4541		# The clocks fire BEFORE pattern rebuilds at the same pulse, and their
4542		# lookahead is RAISED to the maximum pattern lookahead (never patterns
4543		# clamped down): when a pattern rebuilds for its next cycle, the form
4544		# state and the harmony window already describe that cycle.
4545		bar_beats = float(self.time_signature[0])
4546
4547		pattern_lookaheads = [pending.reschedule_lookahead for pending in self._pending_patterns]
4548		pattern_lookaheads += [pattern.reschedule_lookahead for pattern in self._running_patterns.values()]
4549		max_pattern_lookahead = max(pattern_lookaheads, default = 1)
4550
4551		clock_lookahead = max(1.0, float(self._harmony_reschedule_lookahead), float(max_pattern_lookahead))
4552
4553		if clock_lookahead > bar_beats:
4554			logger.warning(
4555				"A pattern's reschedule_lookahead (%.2g beats) exceeds the bar length (%.2g) — "
4556				"the harmony/form clocks fire at most one bar ahead, so that pattern may "
4557				"rebuild before the window covers its cycle start.",
4558				clock_lookahead, bar_beats,
4559			)
4560			clock_lookahead = bar_beats
4561
4562		# Minimum span >= maximum lookahead: the clock cannot prepare a chord
4563		# boundary that arrives sooner than it fires.  Harmonic motion faster
4564		# than this floor stays available at the part level (p.progression),
4565		# where placement is not clock-bound.
4566		def _check_span_floor (progression: typing.Optional[Progression], label: str) -> None:
4567			if progression is None:
4568				return
4569			shortest = min(span.beats for span in progression.spans)
4570			if shortest < clock_lookahead - 1e-9:
4571				raise ValueError(
4572					f"{label}: shortest chord span ({shortest:g} beats) is below the clock "
4573					f"lookahead ({clock_lookahead:g} beats — the largest pattern lookahead). "
4574					"Lengthen the span, lower the pattern lookaheads, or place fast harmony "
4575					"at the part level with p.progression()."
4576				)
4577
4578		_check_span_floor(self._bound_progression, "harmony(progression=)")
4579		for section_name, section_progression in self._section_progressions.items():
4580			_check_span_floor(section_progression, f"section_chords({section_name!r})")
4581
4582		# The form clock MUST be registered before the harmonic clock: same-pulse
4583		# fixed callbacks fire in registration order (and all fixed callbacks fire
4584		# before callback sequences), and on a section-boundary bar the harmonic
4585		# clock reads the current section (via _get_section_progression) to decide
4586		# whether to walk that section's chords.  Registering harmony first would
4587		# make it read the OLD section on every boundary, shifting section_chords()
4588		# replays by one bar and bleeding them across sections.
4589		if self._form_state is not None:
4590
4591			await schedule_form(
4592				sequencer = self._sequencer,
4593				form_state = self._form_state,
4594				reschedule_lookahead = clock_lookahead
4595			)
4596
4597		self._harmony_horizon.reset()
4598
4599		if self._harmonic_state is not None or self._bound_progression is not None or self._section_progressions:
4600
4601			def _get_section_progression () -> typing.Optional[typing.Tuple[str, int, typing.Optional[Progression]]]:
4602				"""Return (section_name, section_index, Progression|None) for the current section, or None."""
4603				if self._form_state is None:
4604					return None
4605				info = self._form_state.get_section_info()
4606				if info is None:
4607					return None
4608				prog = self._section_progressions.get(info.name)
4609				return (info.name, info.index, prog)
4610
4611			await schedule_harmonic_clock(
4612				sequencer = self._sequencer,
4613				get_harmonic_state = lambda: self._harmonic_state,
4614				horizon = self._harmony_horizon,
4615				bar_beats = bar_beats,
4616				cycle_beats = self._harmony_cycle_beats or 4,
4617				get_bound_progression = lambda: self._bound_progression,
4618				get_section_progression = _get_section_progression,
4619				get_pinned = self._pinned_chords.get,
4620				reschedule_lookahead = clock_lookahead,
4621			)
4622
4623		# Bar counter - always active so p.bar is available to all builders.
4624		def _advance_builder_bar (pulse: int) -> None:
4625			self._builder_bar += 1
4626
4627		first_bar_pulse = int(self.time_signature[0] * self._sequencer.pulses_per_beat)
4628
4629		await self._sequencer.schedule_callback_repeating(
4630			callback = _advance_builder_bar,
4631			interval_beats = self.time_signature[0],
4632			start_pulse = first_bar_pulse,
4633			reschedule_lookahead = 1
4634		)
4635
4636		# Run wait_for_initial=True scheduled functions and block until all complete.
4637		# This ensures composition.data is populated before patterns build.
4638		initial_tasks = [t for t in self._pending_scheduled if t.wait_for_initial]
4639
4640		if initial_tasks:
4641
4642			names = ", ".join(getattr(t.fn, '__name__', repr(t.fn)) for t in initial_tasks)
4643			logger.info(f"Waiting for initial scheduled {'function' if len(initial_tasks) == 1 else 'functions'} before start: {names}")
4644
4645			async def _run_initial (fn: typing.Callable) -> None:
4646
4647				accepts_ctx = _fn_has_parameter(fn, "p")
4648				ctx = ScheduleContext(cycle=0)
4649
4650				try:
4651					if inspect.iscoroutinefunction(fn):
4652						await (fn(ctx) if accepts_ctx else fn())
4653					else:
4654						loop = asyncio.get_running_loop()
4655						call = (lambda: fn(ctx)) if accepts_ctx else fn
4656						await loop.run_in_executor(None, call)
4657				except Exception as exc:
4658					logger.warning(f"Initial run of {getattr(fn, '__name__', repr(fn))!r} failed: {exc}")
4659
4660			await asyncio.gather(*[_run_initial(t.fn) for t in initial_tasks])
4661
4662		for pending_task in self._pending_scheduled:
4663
4664			accepts_ctx = _fn_has_parameter(pending_task.fn, "p")
4665
4666			# A wait_for_initial task already ran once as cycle 0 (the blocking
4667			# pre-roll above), so its repeating wrapper starts at cycle 1 — keeping
4668			# ScheduleContext.cycle monotonic across the initial and repeating runs.
4669			wrapped = _make_safe_callback(
4670				pending_task.fn,
4671				accepts_context = accepts_ctx,
4672				start_cycle = 1 if pending_task.wait_for_initial else 0,
4673			)
4674
4675			# wait_for_initial=True implies defer — no point firing at pulse 0
4676			# after the blocking run just completed.  defer=True skips the
4677			# backshift fire so the first repeating call happens one full cycle
4678			# later.
4679			if pending_task.wait_for_initial or pending_task.defer:
4680				start_pulse = int(pending_task.cycle_beats * self._sequencer.pulses_per_beat)
4681			else:
4682				start_pulse = 0
4683
4684			await self._sequencer.schedule_callback_repeating(
4685				callback = wrapped,
4686				interval_beats = pending_task.cycle_beats,
4687				start_pulse = start_pulse,
4688				reschedule_lookahead = pending_task.reschedule_lookahead
4689			)
4690
4691		# Build Pattern objects from pending registrations.
4692		patterns: typing.List[subsequence.pattern.Pattern] = []
4693
4694		for i, pending in enumerate(self._pending_patterns):
4695
4696			pattern = self._build_pattern_from_pending(pending)
4697			patterns.append(pattern)
4698
4699		await schedule_patterns(
4700			sequencer = self._sequencer,
4701			patterns = patterns,
4702			start_pulse = 0
4703		)
4704
4705		# Populate the running patterns dict for live hot-swap and mute/unmute.
4706		for i, pending in enumerate(self._pending_patterns):
4707			name = pending.builder_fn.__name__
4708			self._running_patterns[name] = patterns[i]
4709
4710		# Everything pending is running now; drop the declarations so a later
4711		# live reload cannot graduate stale copies.
4712		self._pending_patterns = []
4713
4714		if self._display is not None and not self._sequencer.render_mode:
4715			self._display.start()
4716			self._sequencer.on_event("bar",  self._display.update)
4717			self._sequencer.on_event("beat", self._display.update)
4718
4719		if self._live_server is not None:
4720			await self._live_server.start()
4721
4722		if self._osc_server is not None:
4723			await self._osc_server.start()
4724			self._sequencer.osc_server = self._osc_server
4725			self._sequencer.on_event("bar", self._broadcast_osc_status)
4726
4727		# Start keystroke listener if hotkeys are enabled and not in render mode.
4728		if self._hotkeys_enabled and not self._sequencer.render_mode:
4729			self._keystroke_listener = subsequence.keystroke.KeystrokeListener()
4730			self._keystroke_listener.start()
4731
4732			if self._keystroke_listener.active:
4733				# Listener started successfully — register the bar handler
4734				# and show all bindings so the user knows what's available.
4735				self._sequencer.on_event("bar", self._process_hotkeys)
4736				self._list_hotkeys()
4737			# If not active, KeystrokeListener.start() already logged a warning.
4738
4739		if self._web_ui_enabled and not self._sequencer.render_mode:
4740			self._web_ui_server = subsequence.web_ui.WebUI(self, http_host=self._web_ui_http_host, ws_host=self._web_ui_ws_host)
4741			self._web_ui_server.start()
4742
4743		try:
4744			await run_until_stopped(self._sequencer)
4745		finally:
4746			# Tear down every service even if run_until_stopped (or an earlier
4747			# stop) raised, and guard each individually, so one failure can't
4748			# strand the rest — most importantly the keystroke listener's
4749			# terminal restore.
4750			if self._web_ui_server is not None:
4751				try:
4752					self._web_ui_server.stop()
4753				except Exception:
4754					logger.exception("Error stopping web UI")
4755
4756			if self._live_server is not None:
4757				try:
4758					await self._live_server.stop()
4759				except Exception:
4760					logger.exception("Error stopping live server")
4761
4762			if self._live_reloader is not None:
4763				try:
4764					self._live_reloader.stop()
4765				except Exception:
4766					logger.exception("Error stopping live reloader")
4767
4768			if self._osc_server is not None:
4769				try:
4770					await self._osc_server.stop()
4771				except Exception:
4772					logger.exception("Error stopping OSC server")
4773				self._sequencer.osc_server = None
4774
4775			if self._display is not None:
4776				try:
4777					self._display.stop()
4778				except Exception:
4779					logger.exception("Error stopping display")
4780
4781			if self._keystroke_listener is not None:
4782				try:
4783					self._keystroke_listener.stop()
4784				except Exception:
4785					logger.exception("Error stopping keystroke listener")
4786				self._keystroke_listener = None
4787
4788	def _build_pattern_from_pending (self, pending: _PendingPattern, start_pulse: int = 0) -> subsequence.pattern.Pattern:
4789
4790		"""
4791		Create a Pattern from a pending registration using a temporary subclass.
4792
4793		The pattern's play stream is dealt here, keyed by NAME (crc32 of
4794		"seed:name" plus any reroll nonce), so registration order is
4795		irrelevant and a pattern added live gets exactly the stream it would
4796		have had at startup.  ``start_pulse`` anchors the first cycle on the
4797		beat axis so the initial build reads the harmony window at the right
4798		place (the sequencer keeps the anchor current on every reschedule).
4799		"""
4800
4801		composition_ref = self
4802		rng = self._stream(pending.builder_fn.__name__)
4803
4804		class _DecoratorPattern (subsequence.pattern.Pattern):
4805
4806			"""
4807			Pattern subclass that delegates to a builder function on each reschedule.
4808			"""
4809
4810			def __init__ (self, pending: _PendingPattern, pattern_rng: typing.Optional[random.Random] = None) -> None:
4811
4812				"""
4813				Initialize the decorator pattern from pending registration details.
4814				"""
4815
4816				super().__init__(
4817					channel = pending.channel,
4818					length = pending.length,
4819					reschedule_lookahead = pending.reschedule_lookahead,
4820					device = pending.device,
4821					mirrors = pending.mirrors,
4822				)
4823
4824				self._builder_fn = pending.builder_fn
4825				self._drum_note_map = pending.drum_note_map
4826				self._cc_name_map = pending.cc_name_map
4827				self._nrpn_name_map = pending.nrpn_name_map
4828				self._default_grid: int = pending.default_grid
4829				self._wants_chord = _fn_has_parameter(pending.builder_fn, "chord")
4830				self._cycle_count = 0
4831				self._rng = pattern_rng
4832				self._muted = False
4833				self._voice_leading_state: typing.Optional[subsequence.voicings.VoiceLeadingState] = (
4834					subsequence.voicings.VoiceLeadingState() if pending.voice_leading else None
4835				)
4836				self._tweaks: typing.Dict[str, typing.Any] = {}
4837
4838				# Anchor of the cycle being built, on the absolute pulse axis.
4839				# The sequencer updates this on every reschedule; the initial
4840				# value is the pattern's first scheduled start.
4841				self._cycle_start_pulse = start_pulse
4842
4843				self._rebuild()
4844
4845			def _rebuild (self) -> None:
4846
4847				"""
4848				Clear steps and call the builder function to repopulate.
4849				"""
4850
4851				self.steps = {}
4852				self.cc_events = []
4853				self.osc_events = []
4854				self.raw_note_events = []
4855				current_cycle = self._cycle_count
4856				self._cycle_count += 1
4857
4858				# lock(): re-deal the stream from its effective seed every
4859				# rebuild so a locked pattern realizes identically each cycle.
4860				# Checked here (engine-side) so it survives live reload.
4861				if self._builder_fn.__name__ in composition_ref._locked_names:
4862					locked_seed = composition_ref._stream_seed(self._builder_fn.__name__)
4863					if locked_seed is not None:
4864						self._rng = random.Random(locked_seed)
4865
4866				if self._muted:
4867					return
4868
4869				# The harmony view for this cycle, anchored at its start beat —
4870				# under variable harmonic rhythm the window, not the engine's
4871				# mutating singleton, is the source of truth.
4872				harmony_view: typing.Optional[HarmonyView] = None
4873
4874				if not composition_ref._harmony_horizon.is_empty:
4875					origin_beat = self._cycle_start_pulse / composition_ref._sequencer.pulses_per_beat
4876					harmony_view = HarmonyView(composition_ref._harmony_horizon, origin_beat)
4877
4878				builder = subsequence.pattern_builder.PatternBuilder(
4879					pattern = self,
4880					cycle = current_cycle,
4881					drum_note_map = self._drum_note_map,
4882					cc_name_map = self._cc_name_map,
4883					nrpn_name_map = self._nrpn_name_map,
4884					section = composition_ref._form_state.get_section_info() if composition_ref._form_state else None,
4885					bar = composition_ref._builder_bar,
4886					conductor = composition_ref.conductor,
4887					rng = self._rng,
4888					tweaks = self._tweaks,
4889					default_grid = self._default_grid,
4890					data = composition_ref.data,
4891					key = composition_ref.key,
4892					scale = composition_ref.scale,
4893					time_signature = composition_ref.time_signature,
4894					held_notes = composition_ref._sequencer._held_notes,
4895					harmony = harmony_view,
4896					section_motifs = composition_ref._section_motifs
4897				)
4898
4899				try:
4900
4901					if self._wants_chord:
4902
4903						# The two-parameter convention: the injected chord is
4904						# the cycle-start snapshot from the window (falling
4905						# back to the engine before the clock has run).
4906						chord = harmony_view.chord if harmony_view is not None else (
4907							composition_ref._harmonic_state.get_current_chord()
4908							if composition_ref._harmonic_state is not None else None
4909						)
4910
4911						if chord is not None:
4912							injected = _InjectedChord(
4913								chord,
4914								self._voice_leading_state,
4915								next_chord = harmony_view.next_chord if harmony_view is not None else None,
4916								beats_remaining = harmony_view.until_change if harmony_view is not None else None,
4917							)
4918							self._builder_fn(builder, injected)
4919						else:
4920							self._builder_fn(builder)
4921
4922					else:
4923						self._builder_fn(builder)
4924
4925				except Exception:
4926					logger.exception("Error in pattern builder '%s' (cycle %d) - pattern will be silent this cycle", self._builder_fn.__name__, current_cycle)
4927
4928				# Auto-apply global tuning if set and not already applied by the builder.
4929				if (
4930					composition_ref._tuning is not None
4931					and not builder._tuning_applied
4932					and not (composition_ref._tuning_exclude_drums and self._drum_note_map)
4933				):
4934					import subsequence.tuning as _tuning_mod
4935					_tuning_mod.apply_tuning_to_pattern(
4936						self,
4937						composition_ref._tuning,
4938						bend_range=composition_ref._tuning_bend_range,
4939						channels=composition_ref._tuning_channels,
4940						reference_note=composition_ref._tuning_reference_note,
4941					)
4942
4943			def on_reschedule (self) -> None:
4944
4945				"""
4946				Rebuild the pattern from the builder function before the next cycle.
4947				"""
4948
4949				self._rebuild()
4950
4951		return _DecoratorPattern(pending, rng)