subsequence 0.6.4__py3-none-any.whl

subsequence/midi.py

@@ -0,0 +1,97 @@
+"""
+Lightweight MIDI message constructors.
+
+Provides factory functions that return ``mido.Message`` objects without
+requiring users to import or interact with mido directly.  Intended for use
+with ``composition.cc_forward()`` callable transforms and any other context
+where a ``mido.Message`` is needed as a return value.
+
+Example::
+
+    import subsequence.midi as midi
+
+    composition.cc_forward(1,
+        lambda v, ch: midi.cc(74, int(v / 127 * 60) + 40, channel=ch)
+    )
+"""
+
+import typing
+import mido
+
+
+def cc (
+	control: int,
+	value: int,
+	channel: int = 0,
+) -> mido.Message:
+
+	"""Create a MIDI Control Change message.
+
+	Parameters:
+		control: CC number (0–127).
+		value: CC value (0–127).
+		channel: MIDI channel (0-indexed, 0–15).  Defaults to 0.
+
+	Returns:
+		A ``mido.Message`` of type ``control_change``.
+
+	Example:
+		```python
+		import subsequence.midi as midi
+
+		# Forward CC 1 to CC 74, scaling range to 40–100
+		composition.cc_forward(1,
+		    lambda v, ch: midi.cc(74, int(v / 127 * 60) + 40, channel=ch)
+		)
+		```
+	"""
+
+	return mido.Message('control_change', channel=channel, control=control, value=value)
+
+
+def pitchwheel (
+	pitch: int,
+	channel: int = 0,
+) -> mido.Message:
+
+	"""Create a MIDI Pitch Wheel message.
+
+	Parameters:
+		pitch: Pitch bend value (-8192 to 8191).  0 is centre (no bend).
+		       Out-of-range values are clamped to the valid range.
+		channel: MIDI channel (0-indexed, 0–15).  Defaults to 0.
+
+	Returns:
+		A ``mido.Message`` of type ``pitchwheel``.
+
+	Example:
+		```python
+		import subsequence.midi as midi
+
+		# Forward CC 1 as pitch bend, scaled to upper half only (0 to +8191)
+		composition.cc_forward(1,
+		    lambda v, ch: midi.pitchwheel(int(v / 127 * 8191), channel=ch)
+		)
+		```
+	"""
+
+	pitch = max(-8192, min(8191, pitch))
+	return mido.Message('pitchwheel', channel=channel, pitch=pitch)
+
+
+def program_change (
+	program: int,
+	channel: int = 0,
+) -> mido.Message:
+
+	"""Create a MIDI Program Change message.
+
+	Parameters:
+		program: Program number (0–127).
+		channel: MIDI channel (0-indexed, 0–15).  Defaults to 0.
+
+	Returns:
+		A ``mido.Message`` of type ``program_change``.
+	"""
+
+	return mido.Message('program_change', channel=channel, program=program)

subsequence/midi_utils.py

@@ -0,0 +1,329 @@
+"""
+MIDI device plumbing — discovering, opening, and registering hardware ports.
+
+Provides interactive/automatic output and input device selection, the
+multi-device registry used by the sequencer, and the ``bank_select()``
+helper for addressing synth banks beyond the first 128 programs.
+"""
+
+import logging
+import typing
+import mido
+
+logger = logging.getLogger(__name__)
+
+
+# Type alias for device identifiers: index (int), name (str), or None (device 0).
+DeviceId = typing.Union[int, str, None]
+
+
+class MidiDeviceRegistry:
+
+	"""Ordered registry of named MIDI ports (output or input).
+
+	Devices are stored in insertion order.  Index 0 is always the first
+	(or only) device — the default for all APIs that do not specify a device.
+	Devices can be looked up by integer index or by name string.
+	``None`` always resolves to index 0.
+
+	The registry is intended to be append-only once playback has started.
+	All registered port objects must already be open.
+	"""
+
+	def __init__ (self) -> None:
+
+		"""
+		Create an empty registry; populate it with add().
+		"""
+
+		self._ports: typing.List[typing.Tuple[str, typing.Any]] = []
+		self._name_to_index: typing.Dict[str, int] = {}
+		# Per-device physical output latency in milliseconds, parallel to
+		# self._ports by index.  Kept separate from the (name, port) tuple so
+		# replace() can swap the port object without disturbing latency.
+		self._latencies: typing.List[float] = []
+
+	def add (self, name: str, port: typing.Any, latency_ms: float = 0.0) -> int:
+
+		"""Register a port under *name*.  Returns the assigned integer index.
+
+		*latency_ms* is the device's physical output latency (non-negative);
+		see :meth:`set_latency`.
+		"""
+
+		idx = len(self._ports)
+		self._ports.append((name, port))
+		self._latencies.append(max(0.0, float(latency_ms)))
+		# First registration wins for name collisions.
+		if name not in self._name_to_index:
+			self._name_to_index[name] = idx
+		return idx
+
+	def get (self, device: DeviceId = None) -> typing.Optional[typing.Any]:
+
+		"""Return the port for *device*, or ``None`` if the registry is empty.
+
+		``None`` → index 0.  ``int`` → direct index.  ``str`` → name lookup.
+		Returns ``None`` if the device cannot be resolved (empty registry,
+		out-of-range index, unknown name).
+		"""
+
+		if not self._ports:
+			return None
+		idx = self.index_of(device)
+		if idx < 0 or idx >= len(self._ports):
+			return None
+		return self._ports[idx][1]
+
+	def index_of (self, device: DeviceId = None) -> int:
+
+		"""Resolve *device* to an integer index.  Returns 0 for ``None``.
+		Returns -1 if the name is unknown or the index is out of range."""
+
+		if device is None:
+			return 0
+		if isinstance(device, int):
+			if 0 <= device < len(self._ports):
+				return device
+			return -1
+		# str
+		return self._name_to_index.get(device, -1)
+
+	def replace (self, index: int, port: typing.Any) -> None:
+
+		"""Replace the port object at *index* without changing the name or index mapping.
+
+		Used by the backward-compat ``midi_out``/``midi_in`` setters to allow
+		test code to inject a fake port after the registry has been populated.
+		Raises ``IndexError`` if *index* is out of range.
+		"""
+
+		if index < 0 or index >= len(self._ports):
+			raise IndexError(f"MidiDeviceRegistry: index {index} out of range (size {len(self._ports)})")
+		name = self._ports[index][0]
+		self._ports[index] = (name, port)
+		# Latency is intentionally preserved — replace() is a pure port swap.
+
+	def set_latency (self, device: DeviceId, latency_ms: float) -> None:
+
+		"""Set the physical output latency (milliseconds) for *device*.
+
+		*latency_ms* must be non-negative — a device cannot sound before it is
+		triggered, so a negative output latency is meaningless.  Raises
+		``ValueError`` for a negative value or an unknown device.
+		"""
+
+		if latency_ms < 0:
+			raise ValueError(f"latency_ms must be non-negative — got {latency_ms}")
+		idx = self.index_of(device)
+		if idx < 0:
+			raise ValueError(f"Unknown output device: {device!r}")
+		self._latencies[idx] = float(latency_ms)
+
+	def latency_of (self, device: DeviceId = None) -> float:
+
+		"""Return the latency (ms) for *device*, or 0.0 if it cannot be resolved.
+
+		Defensive on the hot dispatch path: an unknown device yields 0.0 rather
+		than raising, so a stray event can never crash the send loop.
+		"""
+
+		idx = self.index_of(device)
+		if idx < 0 or idx >= len(self._latencies):
+			return 0.0
+		return self._latencies[idx]
+
+	def max_latency (self) -> float:
+
+		"""Return the largest latency across all registered devices (0.0 if empty)."""
+
+		return max(self._latencies, default=0.0)
+
+	def close_all (self) -> None:
+
+		"""Close every registered port and clear the registry."""
+
+		for name, port in self._ports:
+			try:
+				port.close()
+			except (OSError, RuntimeError, AttributeError):
+				# Shutdown path: a failure on one port must not prevent closing the rest.
+				logger.exception(f"Error closing MIDI port '{name}'")
+		self._ports.clear()
+		self._name_to_index.clear()
+		self._latencies.clear()
+
+	def __len__ (self) -> int:
+
+		"""
+		Number of registered devices.
+		"""
+
+		return len(self._ports)
+
+	def __iter__ (self) -> typing.Iterator[typing.Any]:
+		"""Iterate over port objects (not names)."""
+		return (port for _, port in self._ports)
+
+	def __bool__ (self) -> bool:
+
+		"""
+		True if at least one device is registered.
+		"""
+
+		return bool(self._ports)
+
+
+def bank_select (bank: int) -> typing.Tuple[int, int]:
+
+	"""
+	Convert a 14-bit MIDI bank number to (MSB, LSB) for use with
+	``p.program_change()``.
+
+	MIDI bank select uses two control-change messages: CC 0 (Bank MSB) and
+	CC 32 (Bank LSB).  Together they encode a 14-bit bank number in the
+	range 0–16,383:
+
+	    MSB = bank // 128   (upper 7 bits, sent on CC 0)
+	    LSB = bank % 128    (lower 7 bits, sent on CC 32)
+
+	Args:
+		bank: Integer bank number, 0–16,383.  Values outside this range are
+		      clamped.
+
+	Returns:
+		``(msb, lsb)`` tuple, each value in 0–127.
+
+	Example:
+		```python
+		msb, lsb = subsequence.bank_select(128)   # → (1, 0)
+		p.program_change(48, bank_msb=msb, bank_lsb=lsb)
+		```
+	"""
+
+	bank = max(0, min(16383, bank))
+	return bank >> 7, bank & 0x7F
+
+def select_output_device (device_name: typing.Optional[str] = None) -> typing.Tuple[typing.Optional[str], typing.Optional[typing.Any]]:
+
+	"""
+	Select and open a MIDI output device.
+
+	If ``device_name`` is provided, attempts to open that specific device.
+	If ``device_name`` is None, auto-discovers available devices:
+
+	- If exactly one device exists, it is selected automatically.
+	- If multiple devices exist, prompts the user to choose one from the console.
+	- If no devices exist, logs an error and returns None.
+
+	Returns:
+		A tuple of (device_name, midi_out_object) or (None, None) on failure.
+	"""
+
+	try:
+		outputs = mido.get_output_names()
+		logger.info(f"Available MIDI outputs: {outputs}")
+
+		if not outputs:
+			logger.error("No MIDI output devices found.")
+			return None, None
+
+		# Explicit device requested
+		if device_name is not None:
+			if device_name in outputs:
+				midi_out = mido.open_output(device_name)
+				logger.info(f"Opened MIDI output: {device_name}")
+				return device_name, midi_out
+			else:
+				logger.error(
+					f"MIDI output device '{device_name}' not found. "
+					f"Available devices: {outputs}"
+				)
+				return None, None
+
+		# Auto-discover: one device - use it
+		if len(outputs) == 1:
+			selected_name = outputs[0]
+			midi_out = mido.open_output(selected_name)
+			logger.info(f"One MIDI output found - using '{selected_name}'")
+			return selected_name, midi_out
+
+		# Auto-discover: multiple devices - prompt user
+		print("\nAvailable MIDI output devices:\n")
+		for i, name in enumerate(outputs, 1):
+			print(f"  {i}. {name}")
+		print()
+
+		while True:
+			try:
+				choice = int(input(f"Select a device (1-{len(outputs)}): "))
+				if 1 <= choice <= len(outputs):
+					break
+			except ValueError:
+				pass
+			except EOFError:
+				# stdin is closed (headless/redirected run) — the prompt can
+				# never be answered, so retrying would spin forever.
+				raise RuntimeError(
+					"No interactive terminal to choose between multiple MIDI outputs — "
+					f"pass output_device= with one of: {outputs}"
+				) from None
+			print(f"Enter a number between 1 and {len(outputs)}.")
+
+		selected_name = outputs[choice - 1]
+		midi_out = mido.open_output(selected_name)
+		logger.info(f"Opened MIDI output: {selected_name}")
+
+		print(f"\nTip: To skip this prompt, pass the device name directly:\n")
+		print(f"  Sequencer(output_device_name=\"{selected_name}\")")
+		print(f"  Composition(output_device=\"{selected_name}\")\n")
+
+		return selected_name, midi_out
+
+	except (OSError, RuntimeError) as e:
+		logger.error(f"Failed to open MIDI output: {e}")
+		return None, None
+
+
+def select_input_device (device_name: typing.Optional[str] = None, callback: typing.Optional[typing.Callable] = None) -> typing.Tuple[typing.Optional[str], typing.Optional[typing.Any]]:
+
+	"""
+	Select and open a MIDI input device.
+
+	If ``device_name`` is provided, attempts to open exactly that device.
+	If ``device_name`` is None, returns None without prompting (input is optional/advanced).
+	To enforce input, the caller should check the return value.
+
+	A named device that is not present raises ValueError rather than falling
+	back to another input: MIDI input drives clock-follow and live note
+	capture, so silently listening to the wrong device would desynchronise
+	or mis-record a performance.
+
+	Returns:
+		A tuple of (device_name, midi_in_object), or (None, None) when no
+		name was given or the device failed to open.
+
+	Raises:
+		ValueError: If *device_name* is not among the available inputs.
+	"""
+
+	if device_name is None:
+		return None, None
+
+	try:
+		inputs = mido.get_input_names()
+		logger.info(f"Available MIDI inputs: {inputs}")
+
+		if device_name not in inputs:
+			raise ValueError(
+				f"MIDI input device '{device_name}' not found. "
+				f"Available devices: {inputs}"
+			)
+
+		midi_in = mido.open_input(device_name, callback=callback)
+		logger.info(f"Opened MIDI input: {device_name}")
+		return device_name, midi_in
+
+	except (OSError, RuntimeError) as e:
+		logger.error(f"Failed to open MIDI input: {e}")
+		return None, None

subsequence/mini_notation.py

@@ -0,0 +1,164 @@
+import dataclasses
+import typing
+
+
+@dataclasses.dataclass
+class ParsedEvent:
+
+	"""
+	Represents a single event parsed from mini-notation.
+	"""
+
+	time: float
+	duration: float
+	symbol: str
+	probability: float = 1.0
+
+
+class MiniNotationError(Exception):
+	pass
+
+
+def parse (notation: str, total_duration: float = 4.0) -> typing.List[ParsedEvent]:
+
+	"""
+	Parse a mini-notation string into a list of timed events.
+
+	Mini-notation is a concise way to express rhythmic and melodic phrases. 
+	It distributes events evenly across the specified duration.
+
+	**Syntax:**
+
+	- ``x y z``: Items separated by spaces are distributed across the total duration.
+	- ``[a b]``: Groups items into a single subdivided step.
+	- ``~`` or ``.``: A rest.
+	- ``_``: Extends the previous note (sustain).
+	- ``x?0.6``: Probability suffix — fires with the given probability (0.0–1.0).
+
+	Parameters:
+		notation: The string to parse.
+		total_duration: The duration (in beats) to distribute the 
+			events over (default 4.0).
+
+	Returns:
+		A list of ``ParsedEvent`` objects with calculated times and durations.
+
+	Example:
+		```python
+		# Distributes kick on beats 1 and 3, snare on 2 and 4
+		parse("kick snare kick snare", 4.0)
+		
+		# Subdivisions: kick on 1, snare on 2.1 and 2.2
+		parse("kick [snare snare]", 2.0)
+		```
+	"""
+
+	if total_duration <= 0:
+		raise ValueError("total_duration must be positive")
+
+	tokens = _tokenize(notation)
+
+	events = _parse_recursive(tokens, 0.0, total_duration)
+	
+	return _post_process_sustains(events)
+
+
+def _tokenize (text: str) -> typing.List[typing.Union[str, list]]:
+	
+	"""
+	Convert string into nested lists of tokens.
+	"a [b c]" -> ["a", ["b", "c"]]
+	"""
+	
+	# Add spaces around brackets to make splitting easier
+	text = text.replace("[", " [ ").replace("]", " ] ")
+	raw_tokens = text.split()
+	
+	stack: typing.List[list] = [[]]
+	
+	for token in raw_tokens:
+	
+		if token == "[":
+			new_group: typing.List[typing.Any] = []
+			stack[-1].append(new_group)
+			stack.append(new_group)
+			
+		elif token == "]":
+			if len(stack) <= 1:
+				raise MiniNotationError("Unexpected closing bracket")
+			stack.pop()
+			
+		else:
+			stack[-1].append(token)
+			
+	if len(stack) > 1:
+		raise MiniNotationError("Missing closing bracket")
+		
+	return stack[0]
+
+
+def _parse_recursive (tokens: list, start_time: float, duration: float) -> typing.List[ParsedEvent]:
+
+	"""
+	Recursively distribute tokens over the given duration.
+	"""
+
+	events: typing.List[ParsedEvent] = []
+	step_duration = duration / len(tokens) if tokens else 0
+
+	for i, token in enumerate(tokens):
+	
+		current_time = start_time + (i * step_duration)
+		
+		if isinstance(token, list):
+			# Recursively parse sub-group
+			events.extend(_parse_recursive(token, current_time, step_duration))
+			
+		elif isinstance(token, str):
+			# Parse optional probability suffix: "kick?0.6" → symbol="kick", probability=0.6
+			if "?" in token and token[0] != "?":
+				symbol, prob_str = token.rsplit("?", 1)
+				try:
+					probability = float(prob_str)
+				except ValueError:
+					raise MiniNotationError(f"Invalid probability suffix in {token!r} - expected a number after '?'")
+
+				if not 0.0 <= probability <= 1.0:
+					raise MiniNotationError(f"Probability in {token!r} must be between 0.0 and 1.0")
+			else:
+				symbol = token
+				probability = 1.0
+
+			if symbol in ("~", "."):
+				continue
+			events.append(ParsedEvent(current_time, step_duration, symbol, probability))
+			
+	return events
+
+
+def _post_process_sustains (events: typing.List[ParsedEvent]) -> typing.List[ParsedEvent]:
+
+	"""
+	Merge ``_`` events into the previous event's duration.
+	"""
+
+	if not events:
+		return []
+
+	processed: typing.List[ParsedEvent] = []
+	last_event = None
+
+	for event in events:
+	
+		if event.symbol == "_":
+			# Extend only when this sustain slot is contiguous with the end
+			# of the previous note: after a rest, `_` keeps the silence
+			# instead of stretching the note through the gap.
+			if last_event and abs((last_event.time + last_event.duration) - event.time) < 1e-9:
+				last_event.duration += event.duration
+				
+		else:
+			processed.append(event)
+			last_event = event
+
+	return processed