subsequence 0.6.4__py3-none-any.whl

subsequence/conductor.py

@@ -0,0 +1,238 @@
+"""
+Global automation signals — LFOs and ramps that modulate a composition over time.
+
+The Conductor holds named, time-varying signals (swells, fades, filter sweeps)
+that any pattern can read via ``p.signal(name)`` to shape velocity, CCs, or
+note choices across long stretches of music.
+"""
+
+import math
+import typing
+import warnings
+
+import subsequence.easing
+
+
+_VALID_LFO_SHAPES = frozenset({"sine", "triangle", "saw", "square"})
+
+
+class Signal:
+	
+	"""
+	Abstract base class for a time-varying signal.
+	"""
+	
+	def value_at (self, beat: float) -> float:
+
+		"""
+		Return the signal value at the given beat time.  Subclasses must override.
+		"""
+
+		raise NotImplementedError
+
+
+class LFO(Signal):
+
+	"""
+	A Low-Frequency Oscillator for generating periodic modulation signals.
+	
+	LFOs are used to create cyclical changes (like a 'swell' or 'vibrato') 
+	over many bars.
+	"""
+
+	def __init__ (self, shape: str = "sine", cycle_beats: float = 16.0, min_val: float = 0.0, max_val: float = 1.0, phase: float = 0.0) -> None:
+		
+		"""
+		Initialize an LFO.
+		
+		Parameters:
+			shape: The waveform shape ("sine", "triangle", "saw", "square").
+			cycle_beats: How many beats for one full cycle (e.g., 16.0 = 4 bars).
+			min_val: The bottom of the LFO range (default 0.0).
+			max_val: The top of the LFO range (default 1.0).
+			phase: Phase offset (0.0 to 1.0).
+		"""
+		
+		if cycle_beats <= 0:
+			raise ValueError("cycle_beats must be positive")
+
+		if shape not in _VALID_LFO_SHAPES:
+			raise ValueError(
+				f"Unknown LFO shape {shape!r}. "
+				f"Valid shapes: {sorted(_VALID_LFO_SHAPES)}"
+			)
+
+		self.shape = shape
+		self.cycle_beats = cycle_beats
+		self.min_val = min_val
+		self.max_val = max_val
+		self.phase = phase
+
+	def value_at (self, beat: float) -> float:
+		
+		"""
+		Compute the signal value at a given beat time.
+		"""
+		
+		progress = (beat / self.cycle_beats + self.phase) % 1.0
+		val = 0.0
+		
+		if self.shape == "sine":
+			# Map -1..1 to 0..1
+			raw = math.sin(progress * 2 * math.pi)
+			val = (raw + 1) / 2
+			
+		elif self.shape == "triangle":
+			# 0 -> 0.5 -> 1 -> 0.5 -> 0
+			if progress < 0.5:
+				val = progress * 2
+			else:
+				val = 2 - (progress * 2)
+				
+		elif self.shape == "saw":
+			val = progress
+			
+		else:  # "square"
+			val = 1.0 if progress < 0.5 else 0.0
+
+		return self.min_val + (val * (self.max_val - self.min_val))
+
+
+class Line(Signal):
+
+	"""
+	A ramp signal that moves from one value to another over time.
+	"""
+
+	def __init__ (self, start_val: float, end_val: float, duration_beats: float, start_beat: float = 0.0, loop: bool = False, shape: typing.Union[str, subsequence.easing.EasingFn] = "linear") -> None:
+
+		"""
+		Initialize a ramp signal.
+
+		Parameters:
+			start_val: Initial value.
+			end_val: Target value.
+			duration_beats: How long it takes to reach the target (in beats).
+			start_beat: Global beat time when the ramp should start (default 0).
+			loop: Whether to jump back to start_val and repeat (default False).
+			shape: Easing curve — a name string (e.g. ``"ease_in_out"``) or any
+			       callable that maps [0, 1] → [0, 1].  Defaults to ``"linear"``.
+			       See :mod:`subsequence.easing` for available shapes.
+		"""
+
+		if duration_beats <= 0:
+			raise ValueError("duration_beats must be positive")
+
+		self.start_val = start_val
+		self.end_val = end_val
+		self.duration_beats = duration_beats
+		self.start_beat = start_beat
+		self.loop = loop
+		self._easing_fn = subsequence.easing.get_easing(shape)
+
+	def value_at (self, beat: float) -> float:
+
+		"""
+		Compute the ramp value at a given beat time.
+		"""
+
+		elapsed = beat - self.start_beat
+
+		if elapsed < 0:
+			return self.start_val
+
+		if self.loop:
+			elapsed %= self.duration_beats
+		elif elapsed >= self.duration_beats:
+			return self.end_val
+
+		progress = elapsed / self.duration_beats
+		eased = self._easing_fn(progress)
+		return self.start_val + (eased * (self.end_val - self.start_val))
+
+
+class Conductor:
+
+	"""
+	A registry for global automation signals.
+	
+	The ``Conductor`` allows you to define time-varying signals (like LFOs or 
+	ramps) that are available to all pattern builders. This is ideal for 
+	modulating parameters (like velocity or filter cutoff) over long 
+	compositional timeframes.
+	"""
+
+	def __init__ (self) -> None:
+
+		"""
+		Create an empty conductor; register signals with lfo() or line().
+		"""
+
+		self._signals: typing.Dict[str, Signal] = {}
+		self._warned_missing: typing.Set[str] = set()
+
+	@property
+	def signal_names (self) -> typing.Tuple[str, ...]:
+		"""Names of all registered signals, in sorted order."""
+		return tuple(sorted(self._signals))
+
+	def lfo (self, name: str, shape: str = "sine", cycle_beats: float = 16.0, min_val: float = 0.0, max_val: float = 1.0, phase: float = 0.0) -> None:
+		
+		"""
+		Register a named LFO signal.
+		
+		Example:
+			```python
+			comp.conductor.lfo("swell", shape="sine", cycle_beats=32)
+			```
+		"""
+		
+		self._signals[name] = LFO(shape, cycle_beats, min_val, max_val, phase)
+
+	def line (self, name: str, start_val: float, end_val: float, duration_beats: float, start_beat: float = 0.0, loop: bool = False, shape: typing.Union[str, subsequence.easing.EasingFn] = "linear") -> None:
+
+		"""
+		Register a named ramp signal.
+
+		Parameters:
+			name: Signal name, used to retrieve the value via ``p.signal(name)``.
+			start_val: Value at the start of the ramp.
+			end_val: Value at the end of the ramp.
+			duration_beats: Duration of the ramp in beats.
+			start_beat: Beat time at which the ramp begins (default 0).
+			loop: If True, the ramp restarts from start_val after each cycle.
+			shape: Easing curve name or callable.  Defaults to ``"linear"``.
+			       Use ``"ease_in_out"`` for smooth crossfades, ``"exponential"``
+			       for filter sweeps.  See :mod:`subsequence.easing`.
+
+		Example:
+			```python
+			comp.conductor.line("fadein", start_val=0, end_val=1, duration_beats=64)
+			comp.conductor.line("filter", start_val=0, end_val=1, duration_beats=32, shape="ease_in_out")
+			```
+		"""
+
+		self._signals[name] = Line(start_val, end_val, duration_beats, start_beat, loop, shape)
+
+	def get (self, name: str, beat: float) -> float:
+		
+		"""
+		Retrieve the value of a signal at a specific beat time.
+
+		Most patterns should use ``p.signal("name")`` instead, which
+		calls this method with the current bar time automatically.
+		Use ``get()`` directly when you need a beat time other than
+		the current bar.
+		"""
+		
+		if name not in self._signals:
+			if name not in self._warned_missing:
+				warnings.warn(
+					f"Conductor signal {name!r} not found; returning 0.0. "
+					"Register it with conductor.lfo() or conductor.line() first.",
+					stacklevel=2,
+				)
+				self._warned_missing.add(name)
+			return 0.0
+
+		return self._signals[name].value_at(beat)

subsequence/constants/__init__.py

@@ -0,0 +1,24 @@
+"""Constants for Subsequence.
+
+This package contains the following sets of constants:
+
+- ``subsequence.constants.pulses`` - Pulse-based MIDI timing (internal engine use)
+- ``subsequence.constants.durations`` - Beat-based durations for pattern lengths and steps
+- ``subsequence.constants.velocity`` - MIDI velocity constants
+- ``subsequence.constants.instruments`` - Instrument-specific note maps (GM, Vermona, etc.)
+- ``subsequence.constants.midi_notes`` - Named MIDI note constants C0–G9, C4 = 60 (Middle C)
+- ``subsequence.constants.instruments.gm_cc`` - Named MIDI Continuous Controller (CC) numbers
+
+Pulse constants are re-exported here for backwards compatibility, so
+``subsequence.constants.MIDI_QUARTER_NOTE`` continues to work.
+"""
+
+# Re-export pulse constants for backwards compatibility.
+# These match the values in subsequence.constants.pulses.
+
+MIDI_THIRTYSECOND_NOTE = 3
+MIDI_SIXTEENTH_NOTE = 6
+MIDI_EIGHTH_NOTE = 12
+MIDI_QUARTER_NOTE = 24
+MIDI_HALF_NOTE = 48
+MIDI_WHOLE_NOTE = 96

subsequence/constants/durations.py

@@ -0,0 +1,37 @@
+"""Beat-based duration constants for pattern lengths and note timing.
+
+All values are in **beats**, where 1.0 = one quarter note. Use these to express
+pattern lengths and step sizes in musical terms instead of raw floats.
+
+Multiply by a count for multi-note durations::
+
+    import subsequence.constants.durations as dur
+
+    # "9 sixteenth notes"
+    length = 9 * dur.SIXTEENTH     # 2.25 beats
+
+    # "21 eighth notes"
+    length = 21 * dur.EIGHTH       # 10.5 beats
+
+    # "4 bars of quarter notes"
+    length = 4 * dur.QUARTER       # 4.0 beats
+
+Use directly for step sizes and note durations::
+
+    p.arpeggio(tones, spacing=dur.SIXTEENTH, velocity=90)
+    p.arpeggio(tones, spacing=dur.DOTTED_SIXTEENTH, velocity=80)
+    p.repeat(60, spacing=dur.EIGHTH)
+"""
+
+THIRTYSECOND = 0.125
+SIXTEENTH = 0.25
+DOTTED_SIXTEENTH = 0.375
+TRIPLET_EIGHTH = 1 / 3
+EIGHTH = 0.5
+DOTTED_EIGHTH = 0.75
+TRIPLET_QUARTER = 2 / 3
+QUARTER = 1.0
+DOTTED_QUARTER = 1.5
+HALF = 2.0
+DOTTED_HALF = 3.0
+WHOLE = 4.0

subsequence/constants/instruments/__init__.py

@@ -0,0 +1,13 @@
+"""Instrument definitions — note maps, CC maps, and constants.
+
+Each instrument module exports constants and lookup dictionaries that can be
+passed to ``@composition.pattern()`` via ``drum_note_map`` and ``cc_name_map``.
+
+Available instruments:
+
+- ``subsequence.constants.instruments.gm_cc`` - General MIDI CC assignments
+- ``subsequence.constants.instruments.gm_drums`` - General MIDI Level 1 drums
+- ``subsequence.constants.instruments.gm_instruments`` - General MIDI Level 1 program numbers
+- ``subsequence.constants.instruments.roland_tr8s`` - Roland TR-8S (drums + CCs)
+- ``subsequence.constants.instruments.vermona_drm1_drums`` - Vermona DRM1 MKIV drums
+"""

subsequence/constants/instruments/gm_cc.py

@@ -0,0 +1,46 @@
+"""General MIDI Continuous Controller (CC) constants.
+
+Standard MIDI CC assignments (0-127). These are supported by virtually all GM-compatible
+instruments, synthesizers, and DAWs.
+
+Two ways to use this module:
+
+1. **As constants** - reference CC numbers directly when sending MIDI CC messages::
+
+	import subsequence.constants.instruments.gm_cc as gm_cc
+
+	@composition.pattern(...)
+	def sweep (p):
+		p.cc(gm_cc.FILTER_CUTOFF, 127)
+
+2. **As a cc_name_map** - pass ``GM_CC_MAP`` to the ``cc_name_map`` parameter
+   of ``@composition.pattern()`` and use human-readable names like ``"filter_cutoff"``
+   or ``"sustain_pedal"`` in your CC calls::
+
+	import subsequence.constants.instruments.gm_cc as gm_cc
+
+	@composition.pattern(channel=1, beats=4, cc_name_map=gm_cc.GM_CC_MAP)
+	def synth (p):
+		p.cc("filter_cutoff", 100)
+		p.cc_ramp("expression", 0, 127, shape="ease_in")
+
+Canonical source: `pymididefs <https://github.com/simonholliday/PyMidiDefs>`_.
+"""
+
+import typing
+
+# Re-export everything from pymididefs.cc — all CC constants and the lookup dict.
+# These constants modules are deliberate re-export shims, exempt from the
+# project's import-x-only rule (which the rest of the codebase satisfies).
+from pymididefs.cc import *  # noqa: F401,F403
+from pymididefs.cc import CC_MAP  # noqa: F401 — explicit re-export for type checkers
+
+# ─── Backward-compatibility aliases ─────────────────────────────────────────
+# Subsequence used FOOT_PEDAL_LSB; pymididefs uses FOOT_CONTROLLER_LSB.
+FOOT_PEDAL_LSB = FOOT_CONTROLLER_LSB  # noqa: F405
+
+# GM_CC_MAP extends the canonical CC_MAP with the backward-compat alias.
+GM_CC_MAP: typing.Dict[str, int] = {
+	**CC_MAP,
+	"foot_pedal_lsb": FOOT_PEDAL_LSB,
+}

subsequence/constants/instruments/gm_drums.py

@@ -0,0 +1,53 @@
+"""General MIDI Level 1 drum note map.
+
+Standard MIDI percussion assignments for channel 10 (0-indexed channel 9).
+These note numbers are supported by virtually all GM-compatible instruments,
+drum machines, and DAWs.
+
+Two ways to use this module:
+
+1. **As a drum_note_map** - pass ``GM_DRUM_MAP`` to the ``drum_note_map`` parameter
+   of ``@composition.pattern()`` and use human-readable names like ``"kick"``,
+   ``"snare"``, or the numbered ``"kick_1"`` in your pattern builder calls::
+
+       import subsequence.constants.instruments.gm_drums
+
+       @composition.pattern(channel=10, beats=4, drum_note_map=subsequence.constants.instruments.gm_drums.GM_DRUM_MAP)
+       def drums (p):
+           p.hit_steps("kick", [0, 4, 8, 12], velocity=127)
+
+2. **As constants** - reference note numbers directly::
+
+       import subsequence.constants.instruments.gm_drums
+
+       @composition.pattern(channel=10, beats=4)
+       def drums (p):
+           p.hit_steps(subsequence.constants.instruments.gm_drums.KICK, [0, 4, 8, 12], velocity=127)
+
+This map is the canonical GM percussion key map **plus** the unnumbered
+"primary" aliases (``"kick"`` / ``"snare"`` / ``"crash"`` / ``"ride"`` → the
+``_1`` variant), so a pattern can use either ``"kick"`` or ``"kick_1"``.  The
+pure, one-name-per-note spec map is always available upstream as
+``pymididefs.drums.GM_DRUM_MAP``.
+
+Canonical source: `pymididefs <https://github.com/simonholliday/PyMidiDefs>`_.
+"""
+
+import typing
+
+import pymididefs.drums
+
+# Re-export every GM drum constant and the primary-alias names (KICK, SNARE,
+# CRASH, RIDE, GM_DRUM_PRIMARY_ALIASES) so callers can write e.g.
+# ``gm_drums.KICK`` or ``gm_drums.KICK_1``.
+from pymididefs.drums import *  # noqa: F401,F403
+
+# The composition-facing map: the canonical GM Level 1 percussion key map plus
+# the unnumbered primary aliases.  Merged here (not upstream) so the spec map at
+# ``pymididefs.drums.GM_DRUM_MAP`` stays one name per note.  The annotated
+# assignment deliberately specialises the spec map re-exported by ``import *``
+# above (hence the no-redef suppression).
+GM_DRUM_MAP: typing.Dict[str, int] = {  # type: ignore[no-redef]
+	**pymididefs.drums.GM_DRUM_MAP,
+	**pymididefs.drums.GM_DRUM_PRIMARY_ALIASES,
+}

subsequence/constants/instruments/gm_instruments.py

@@ -0,0 +1,32 @@
+"""General MIDI Level 1 instrument program numbers.
+
+All 128 GM Level 1 instrument assignments, organised into 16 families of 8.
+Use these constants with ``p.program_change()`` to select instruments on
+GM-compatible synthesizers and sound modules.
+
+Usage::
+
+    import subsequence.constants.instruments.gm_instruments as gm
+
+    @composition.pattern(channel=1, length=4)
+    def strings (p):
+        p.program_change(gm.VIOLIN)
+        p.note(60, beat=0)
+
+    # Lookup by name
+    gm.GM_INSTRUMENT_MAP["flute"]        # 73
+    gm.GM_INSTRUMENT_NAMES[73]           # "Flute"
+
+    # Family ranges
+    gm.GM_FAMILIES["piano"]              # (0, 7)
+
+Canonical source: `pymididefs <https://github.com/simonholliday/PyMidiDefs>`_.
+"""
+
+# Re-export everything from pymididefs.gm - all instrument constants and lookup tables.
+from pymididefs.gm import *  # noqa: F401,F403
+from pymididefs.gm import (  # noqa: F401 - explicit re-exports for type checkers
+	GM_FAMILIES,
+	GM_INSTRUMENT_MAP,
+	GM_INSTRUMENT_NAMES,
+)