subsequence 0.6.4__py3-none-any.whl

subsequence/__init__.py

@@ -0,0 +1,231 @@
+
+"""
+Subsequence - an algorithmic composition framework for Python.
+
+Subsequence gives you a palette of mathematical building blocks -
+Euclidean rhythms, cellular automata, L-systems, Markov chains,
+cognitive melody generation - and a stateful engine that lets them
+interact and evolve over time. Unlike tools that loop a fixed pattern
+forever, Subsequence rebuilds every pattern fresh before each cycle
+with full context, so algorithms feed into each other and compositions
+emerge that no single technique could produce alone. It generates pure
+MIDI (no audio engine) to control hardware synths, modular systems,
+drum machines, or software VSTs/DAWs.
+
+What makes it different:
+
+- **A rich algorithmic palette.** Euclidean and Bresenham rhythm
+  generators, cellular automata (1D and 2D), L-system string rewriting,
+  Markov chains, cognitive melody via the Narmour model, probability-
+  weighted ghost notes, position-aware thinning, drones and continuous
+  notes, Perlin and pink noise, logistic chaos maps - plus groove
+  templates, velocity shaping, and pitch-bend automation to shape
+  how they sound.
+- **Stateful patterns that evolve.** Each pattern is a Python function
+  rebuilt fresh every cycle with full context - current chord, section,
+  cycle count, shared data from other patterns. A Euclidean rhythm can
+  thin itself as tension builds, a cellular automaton can seed from the
+  harmony, and a Markov chain can shift behaviour between sections.
+- **Optional chord graph.** Define weighted chord and key transitions
+  via probability graphs, with gravity and automatic voice leading.
+  A dozen built-in palettes and frozen progressions to lock some sections
+  while others evolve freely. Layer on cognitive harmony for
+  Narmour-based melodic inertia.
+- **Sub-microsecond clock.** Hybrid sleep+spin timing achieves typical
+  pulse jitter of < 5 us on Linux, with zero long-term drift.
+- **Turn anything into music.** ``composition.schedule()`` runs any
+  Python function on a beat cycle - APIs, sensors, files. Anything
+  Python can reach becomes a musical parameter.
+- **Pure MIDI, zero sound engine.** No audio synthesis, no heavyweight
+  dependencies. Route to hardware synths, drum machines, Eurorack, or
+  software instruments.
+
+Composition tools:
+
+- **Rhythm and feel.** Euclidean and Bresenham generators, multi-voice
+  weighted Bresenham distribution (``bresenham_poly()``), ghost note
+  layers (``ghost_fill()``), position-aware note removal (``thin()`` -
+  the musical inverse of ``ghost_fill``), evolving cellular-automaton
+  rhythms (``cellular_1d()``, ``cellular_2d()``), smooth Perlin noise (``perlin_1d()``,
+  ``perlin_2d()``, ``perlin_1d_sequence()``, ``perlin_2d_grid()``),
+  deterministic chaos sequences (``logistic_map()``), pink 1/f noise
+  (``pink_noise()``), L-system string rewriting (``p.lsystem()``),
+  Markov-chain generation (``p.markov()``), aperiodic binary rhythms
+  (``p.thue_morse()``), golden-ratio beat placement (``p.fibonacci()``),
+  Gray-Scott reaction-diffusion patterns (``p.reaction_diffusion()``),
+  Lorenz strange-attractor generation (``p.lorenz()``), exhaustive
+  pitch-subsequence melodies (``p.de_bruijn()``), step-wise melodies
+  with guaranteed pitch diversity (``p.self_avoiding_walk()``), drones
+  and explicit note on/off events (``p.drone()``, ``p.drone_off()``,
+  ``p.silence()``),
+  groove templates (``Groove.swing()``, ``Groove.from_agr()``), swing via
+  ``p.swing()`` (a shortcut for ``Groove.swing()``), randomize,
+  velocity shaping and ramps (``p.build_velocity_ramp()``), dropout, per-step
+  probability, and polyrhythms via independent pattern lengths.
+- **Melody generation.** ``p.melody()`` with ``MelodicState`` applies
+  the Narmour Implication-Realization model to single-note lines:
+  continuation after small steps, reversal after large leaps, chord-tone
+  weighting, range gravity, and pitch-diversity penalty.  History persists
+  across bar rebuilds for natural phrase continuity.
+- **Chord parts.** ``comp.chords()`` and ``p.progression()`` play a chord
+  progression — generated from a chord-graph style or given explicitly — at a
+  declared *harmonic rhythm*: a fixed length, a shaped ``[WHOLE, HALF, HALF]``
+  sequence, or ``between(WHOLE, 3 * WHOLE, step=WHOLE)`` for chords of varying,
+  quantized length.  Voicing density, ``detached`` articulation, and a seed for
+  a fixed phrase are all declarative.
+- **Expression.** CC messages/ramps, pitch bend, note-correlated
+  bend/portamento/slide, program changes, SysEx, and OSC output - all
+  from within patterns.
+- **Form and structure.** Musical form as a weighted graph, ordered list,
+  or generator. Patterns read ``p.section`` to adapt. Conductor signals
+  (LFOs, ramps) shape intensity over time.
+- **Sequences as lists.** ``p.hit_steps("kick", [0, 4, 8, 12])`` and
+  ``p.sequence(steps=..., pitches=..., velocities=...)`` place rhythms
+  and lines from plain Python lists - the vocabulary the generator and
+  density helpers in ``sequence_utils`` all speak.
+- **Scales.** ``p.snap_to_scale()`` snaps notes to any
+  scale. ``scale_notes()`` generates a list of MIDI note numbers from
+  a key, mode, and range or note count - useful for arpeggios, Markov
+  chains, and melodic walks. Built-in western and non-western modes,
+  plus ``register_scale()`` for your own.
+- **Microtonal tuning.** ``composition.tuning()`` applies a tuning
+  system globally; ``p.apply_tuning()`` overrides per-pattern.
+  Supports Scala ``.scl`` files, explicit cent lists, frequency ratios,
+  and N-TET equal temperaments. Polyphonic parts use explicit channel
+  rotation so simultaneous notes can carry independent pitch bends
+  without MPE. Compatible with any standard MIDI synthesiser.
+- **Randomness tools.** Weighted choice, no-repeat shuffle, random
+  walk, probability gates. Deterministic seeding makes every decision
+  repeatable: set it composition-wide (``seed=42``) or per generator
+  (``seed=`` on any generator, with ``rng=`` for an explicit instance —
+  precedence ``rng`` > ``seed`` > the pattern's ``p.rng``). See the
+  README "Conventions" section for the API's shared vocabulary.
+- **Pattern transforms.** Legato, detached, fixed gate (``p.duration()``),
+  reverse, time-stretch, rotate, transpose, invert, randomize, and
+  conditional ``p.every()``.
+
+Integration:
+
+- **MIDI clock.** Master (``clock_output()``) or follower
+  (``clock_follow=True``). When multiple inputs are connected, only
+  one may be designated as the master clock source; messages from
+  other inputs are filtered to prevent sync interference. Sync to a
+  DAW or drive hardware.
+- **Latency compensation.** Declare each output device's physical
+  latency (``latency_ms=``); Subsequence delays the faster devices so
+  a mix of hardware and slower software instruments sound together.
+- **MIDI mirroring with per-device drum maps.** Fan a pattern out to
+  extra ``(device, channel)`` destinations; an entry can carry its own
+  ``drum_note_map`` so one named drum hit re-resolves to the right voice
+  on each device — a DRM1 and a General MIDI sampler alike.
+- **Shared project definitions.** ``load_definitions("project.yaml")``
+  reads a small per-project YAML file naming notes, CCs, channels,
+  programs, and NRPNs — the same file the Subsample sampler reads — so
+  both tools use identical names and a renumber is a single edit.
+- **Hardware control.** CC input mapping from knobs/faders to
+  ``composition.data``; patterns read and write the same dict via
+  ``p.data`` for both external data access and cross-pattern
+  communication. OSC for bidirectional communication with mixers,
+  lighting, visuals.
+- **Live held-note arpeggiator.** ``composition.note_input()`` tracks the
+  notes you hold on a keyboard; a pattern reads them with ``p.held_notes()``
+  and arpeggiates them (``p.arpeggio(p.held_notes())``), with ``release_ms``
+  debounce and ``latch``. A performance layer over the deterministic
+  composition - empty when rendering headlessly.
+- **Live coding.** Hot-swap patterns, change tempo, mute/unmute, and
+  tweak parameters during playback via a built-in TCP eval server.
+- **Hotkeys.** Single keystrokes to jump sections, toggle mutes, or
+  fire any action - with optional bar-boundary quantization.
+- **Real-time pattern triggering.** ``composition.trigger()`` generates
+  one-shot patterns in response to sensors, OSC, or any event.
+- **Terminal display.** Live status line (BPM, bar, section, chord).
+  Add ``grid=True`` for an ASCII pattern grid showing velocity and
+  sustain - makes legato, detached, and staccato articulations visually
+  distinct at a glance.
+  Add ``grid_scale=2`` to zoom in horizontally, revealing swing and
+  groove micro-timing.
+- **Web UI Dashboard (Beta).** Enable with ``composition.web_ui()`` to 
+  broadcast live composition metadata and visualize piano-roll pattern 
+  grids in a reactive HTTP/WebSocket browser dashboard.
+- **Ableton Link.** Industry-standard wireless tempo/phase sync
+  (``comp.link()``; requires ``pip install subsequence[link]``).
+  Any Link-enabled app on the same LAN — Ableton Live, iOS synths,
+  other Subsequence instances — stays in time automatically.
+- **Recording.** Record to standard MIDI file. Render to file without
+  waiting for real-time playback.
+
+Minimal example:
+
+    ```python
+    import subsequence
+    import subsequence.constants.instruments.gm_drums as gm_drums
+
+    comp = subsequence.Composition(bpm=120)
+
+    @comp.pattern(channel=10, beats=4, drum_note_map=gm_drums.GM_DRUM_MAP)
+    def drums (p):
+        (p.hit_steps("kick_1",        [0, 4, 8, 12], velocity=100)
+          .hit_steps("snare_1",       [4, 12],        velocity=90)
+          .hit_steps("hi_hat_closed", range(16),      velocity=70))
+
+    comp.play()
+    ```
+
+Community and Feedback:
+
+- **Discussions:** Chat and ask questions at https://github.com/simonholliday/subsequence/discussions
+- **Issues:** Report bugs and request features at https://github.com/simonholliday/subsequence/issues
+
+Package-level exports: ``Composition``, ``Chord``, ``Groove``, ``MelodicState``, ``Tuning``, ``Motif``, ``Phrase``, ``motif``, ``sentence``, ``period``, ``Degree``, ``ChordTone``, ``Approach``, ``MotifEvent``, ``ControlEvent``, ``Progression``, ``ChordSpan``, ``PitchSet``, ``progression``, ``Cadence``, ``Section``, ``Form``, ``roles``, ``sieve``, ``residual_class``, ``between``, ``parse_chord``, ``register_chord_quality``, ``register_scale``, ``scale_notes``, ``bank_select``, ``Definitions``, ``load_definitions``.
+"""
+
+import subsequence.cadences
+import subsequence.chords
+import subsequence.forms
+import subsequence.roles
+import subsequence.composition
+import subsequence.definitions
+import subsequence.groove
+import subsequence.harmonic_rhythm
+import subsequence.intervals
+import subsequence.melodic_state
+import subsequence.midi_utils
+import subsequence.motifs
+import subsequence.progressions
+import subsequence.sequence_utils
+import subsequence.tuning
+
+
+Composition = subsequence.composition.Composition
+Motif = subsequence.motifs.Motif
+Phrase = subsequence.motifs.Phrase
+motif = subsequence.motifs.motif
+sentence = subsequence.motifs.sentence
+period = subsequence.motifs.period
+Cadence = subsequence.cadences.Cadence
+Section = subsequence.forms.Section
+Form = subsequence.forms.Form
+Degree = subsequence.motifs.Degree
+ChordTone = subsequence.motifs.ChordTone
+Approach = subsequence.motifs.Approach
+MotifEvent = subsequence.motifs.MotifEvent
+ControlEvent = subsequence.motifs.ControlEvent
+Progression = subsequence.progressions.Progression
+ChordSpan = subsequence.progressions.ChordSpan
+PitchSet = subsequence.progressions.PitchSet
+progression = subsequence.progressions.progression
+Chord = subsequence.chords.Chord
+Groove = subsequence.groove.Groove
+MelodicState = subsequence.melodic_state.MelodicState
+Tuning = subsequence.tuning.Tuning
+between = subsequence.harmonic_rhythm.between
+parse_chord = subsequence.chords.parse_chord
+register_chord_quality = subsequence.chords.register_chord_quality
+register_scale = subsequence.intervals.register_scale
+scale_notes = subsequence.intervals.scale_notes
+bank_select = subsequence.midi_utils.bank_select
+Definitions = subsequence.definitions.Definitions
+load_definitions = subsequence.definitions.load_definitions
+roles = subsequence.roles
+sieve = subsequence.sequence_utils.sieve
+residual_class = subsequence.sequence_utils.residual_class

subsequence/__main__.py

@@ -0,0 +1,24 @@
+"""
+Entry point for ``python -m subsequence`` — confirms the install and points to the docs.
+"""
+
+import logging
+
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def main () -> None:
+
+	"""
+	Main entry point for the subsequence module.
+	"""
+
+	logger.info("Subsequence module loaded.")
+	logger.info("To make your first sound, follow the Cookbook: https://subsequence.live/cookbook/00-setup.html")
+
+
+if __name__ == "__main__":
+	main()

subsequence/assets/web/index.html

@@ -0,0 +1,345 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Subsequence Dashboard</title>
+    <style>
+        :root {
+            --bg-color: #0d1117;
+            --text-color: #c9d1d9;
+            --accent-color: #58a6ff;
+            --panel-bg: #161b22;
+            --border-color: #30363d;
+        }
+
+        body {
+            background-color: var(--bg-color);
+            color: var(--text-color);
+            font-family: 'Inter', -apple-system, sans-serif;
+            margin: 0;
+            padding: 20px;
+        }
+
+        .dashboard {
+            max-width: 1200px;
+            margin: 0 auto;
+            display: grid;
+            gap: 20px;
+        }
+
+        .header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            border-bottom: 1px solid var(--border-color);
+            padding-bottom: 20px;
+        }
+
+        .header h1 {
+            margin: 0;
+            font-size: 1.5rem;
+        }
+
+        .status {
+            display: flex;
+            gap: 20px;
+            font-size: 1.2rem;
+            font-weight: 600;
+        }
+
+        .status span {
+            color: var(--accent-color);
+        }
+
+        .grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
+            gap: 20px;
+        }
+
+        .panel {
+            background: var(--panel-bg);
+            border: 1px solid var(--border-color);
+            border-radius: 8px;
+            padding: 20px;
+        }
+
+        .panel h2 {
+            margin-top: 0;
+            font-size: 1.2rem;
+            border-bottom: 1px solid var(--border-color);
+            padding-bottom: 15px;
+            margin-bottom: 20px;
+        }
+
+        .gauge-container {
+            margin-bottom: 20px;
+        }
+
+        .gauge-label {
+            display: flex;
+            justify-content: space-between;
+            margin-bottom: 8px;
+            font-size: 0.95rem;
+        }
+
+        .gauge-bar {
+            width: 100%;
+            height: 12px;
+            background: var(--border-color);
+            border-radius: 6px;
+            overflow: hidden;
+            position: relative;
+        }
+
+        .gauge-fill {
+            height: 100%;
+            background: var(--accent-color);
+            transition: width 0.1s linear;
+        }
+
+        .pattern-grid-container {
+            margin-bottom: 15px;
+            background: rgba(0, 0, 0, 0.2);
+            border: 1px solid var(--border-color);
+            border-radius: 6px;
+            padding: 12px;
+        }
+
+        .pattern-grid-container:last-child {
+            margin-bottom: 0;
+        }
+
+        .pattern-grid-header {
+            display: flex;
+            justify-content: space-between;
+            margin-bottom: 10px;
+            font-family: monospace;
+            font-size: 1.1rem;
+        }
+
+        .pattern-grid {
+            position: relative;
+            width: 100%;
+            background: rgba(255, 255, 255, 0.03);
+            border-radius: 2px;
+            overflow: hidden;
+        }
+
+        .note-rect {
+            position: absolute;
+            border-radius: 2px;
+        }
+
+        .piano-roll-label {
+            position: absolute;
+            left: 4px;
+            font-size: 0.70rem;
+            color: rgba(255, 255, 255, 0.6);
+            font-family: monospace;
+            text-shadow: 1px 1px 1px rgba(0, 0, 0, 0.7);
+            pointer-events: none;
+            z-index: 5;
+            white-space: nowrap;
+        }
+
+        .playhead {
+            position: absolute;
+            top: 0;
+            bottom: 0;
+            width: 1px;
+            background-color: rgba(255, 255, 255, 0.8);
+            box-shadow: 0 0 4px rgba(255, 255, 255, 0.5);
+            z-index: 10;
+        }
+    </style>
+</head>
+
+<body>
+    <div id="app"></div>
+
+    <script type="module">
+        import { h, Component, render } from 'https://esm.sh/preact@10.19.6';
+        import { useState, useEffect } from 'https://esm.sh/preact@10.19.6/hooks';
+        import htm from 'https://esm.sh/htm@3.1.1';
+
+        const html = htm.bind(h);
+
+        function Transport({ state }) {
+            let sectionStr = state.section || '---';
+            if (state.section && state.section_bars) {
+                sectionStr = `[${state.section} ${state.section_bar}/${state.section_bars}`;
+                if (state.next_section) {
+                    sectionStr += ` \u2192 ${state.next_section}`;
+                }
+                sectionStr += ']';
+            }
+
+            return html`
+                <div class="header">
+                    <h1>Subsequence <span>Dashboard</span></h1>
+                    <div class="status">
+                        <div>BPM: <span>${state.bpm ? state.bpm.toFixed(1) : '---'}</span></div>
+                        ${state.key ? html`<div>Key: <span>${state.key}</span></div>` : ''}
+                        <div>Bar: <span>${state.global_bar || 0}.${state.global_beat || 0}</span></div>
+                        <div>Section: <span>${sectionStr}</span></div>
+                        <div>Chord: <span>${state.chord || '---'}</span></div>
+                    </div>
+                </div>
+            `;
+        }
+
+        function SignalGauge({ name, value }) {
+            // value is expected to be roughly 0.0 - 1.0. Clamp it to 0-100% just in case
+            const pct = Math.max(0, Math.min(100, value * 100));
+            return html`
+                <div class="gauge-container">
+                    <div class="gauge-label">
+                        <span>${name}</span>
+                        <span>${value.toFixed(2)}</span>
+                    </div>
+                    <div class="gauge-bar">
+                        <div class="gauge-fill" style="width: ${pct}%"></div>
+                    </div>
+                </div>
+            `;
+        }
+
+        function PatternGrid({ pattern, state }) {
+            const color = pattern.muted ? '#ff7b72' : '#3fb950';
+            const notes = pattern.notes || [];
+            const length_pulses = pattern.length_pulses || 1;
+            const drum_map = pattern.drum_map || {};
+
+            // Reverse the drum map: { midi_note: "kick" }
+            const reverseDrumMap = {};
+            for (const [name, noteNum] of Object.entries(drum_map)) {
+                if (!reverseDrumMap[noteNum]) reverseDrumMap[noteNum] = name;
+            }
+
+            // Find unique pitches and sort descending (higher pitches at top)
+            const pitches = [...new Set(notes.map(n => n.p))].sort((a, b) => b - a);
+            const rowHeight = 16;
+            const gridHeight = Math.max(48, pitches.length * rowHeight);
+
+            const pitchToY = (p) => {
+                const idx = pitches.indexOf(p);
+                if (idx === -1) return 0;
+                // Center the note vertically in its "row"
+                return idx * rowHeight + 1;
+            };
+
+            const getPitchName = (p) => {
+                if (reverseDrumMap[p]) return reverseDrumMap[p];
+                const noteNames = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+                const octave = Math.floor(p / 12) - 1;
+                const note = noteNames[p % 12];
+                return `${note}${octave}`;
+            };
+
+            const localPlayhead = (state.playhead_pulse || 0) % length_pulses;
+            const playheadLeft = (localPlayhead / length_pulses) * 100;
+
+            const renderLabel = (p) => {
+                const top = pitchToY(p);
+                return html`<div class="piano-roll-label" style="top: ${top}px; line-height: ${rowHeight - 2}px;">${getPitchName(p)}</div>`;
+            };
+
+            const renderNote = (n, i) => {
+                const left = (n.s / length_pulses) * 100;
+                // Clamp width to remainder of bar so it doesn't spill over
+                const width = Math.min((n.d / length_pulses) * 100, 100 - left);
+                const top = pitchToY(n.p);
+                const opacity = Math.max(0.3, n.v / 127);
+                return html`<div key=${i} class="note-rect" style="left: ${left}%; width: ${Math.max(0.5, width)}%; top: ${top}px; height: ${rowHeight - 2}px; opacity: ${opacity}; background-color: ${color};"></div>`;
+            };
+
+            return html`
+                <div class="pattern-grid-container">
+                    <div class="pattern-grid-header">
+                        <span>${pattern.name}</span>
+                        <span style="color: ${color}; font-weight: bold; font-size: 0.85rem;">${pattern.muted ? 'MUTED' : 'PLAYING'}</span>
+                    </div>
+                    <div class="pattern-grid" style="height: ${gridHeight}px;">
+                        ${pitches.map(renderLabel)}
+                        ${notes.map(renderNote)}
+                        <div class="playhead" style="left: ${playheadLeft}%;"></div>
+                    </div>
+                </div>
+            `;
+        }
+
+        function App() {
+            const [state, setState] = useState({
+                bpm: null,
+                chord: null,
+                section: null,
+                patterns: [],
+                signals: {}
+            });
+            const [connected, setConnected] = useState(false);
+
+            useEffect(() => {
+                let ws;
+
+                function connect() {
+                    // __WS_PORT__ is substituted by web_ui.py at serve time so
+                    // WebUI(ws_port=...) actually reaches the dashboard; the
+                    // regex guard keeps the raw file working (default 8765)
+                    // when opened without the server.
+                    const wsPortToken = '__WS_PORT__';
+                    const wsPort = /^\d+$/.test(wsPortToken) ? wsPortToken : '8765';
+                    ws = new WebSocket('ws://' + window.location.hostname + ':' + wsPort);
+
+                    ws.onopen = () => setConnected(true);
+
+                    ws.onmessage = (event) => {
+                        const data = JSON.parse(event.data);
+                        setState(data);
+                    };
+
+                    ws.onclose = () => {
+                        setConnected(false);
+                        // Try to reconnect in 2s
+                        setTimeout(connect, 2000);
+                    };
+                }
+
+                connect();
+
+                return () => {
+                    if (ws) ws.close();
+                };
+            }, []);
+
+            return html`
+                <div class="dashboard">
+                    <${Transport} state=${state} />
+                    
+                    ${!connected ? html`<div style="color: #ff7b72; padding: 20px; text-align: center; border: 1px solid #ff7b72; border-radius: 8px;">Not connected to Subsequence websocket...</div>` : null}
+
+            <div class="grid">
+                <div class="panel">
+                    <h2>Signals & Conductor</h2>
+                    ${Object.keys(state.signals).length === 0 ? html`<p style="color: grey; font-style: italic;">No active signals</p>` : null}
+                    ${Object.entries(state.signals).map(([name, value]) =>
+                html`<${SignalGauge} key=${name} name=${name} value=${value} />`
+            )}
+                </div>
+                <div class="panel">
+                    <h2>Active Patterns</h2>
+                    ${state.patterns.length === 0 ? html`<p style="color: grey; font-style: italic;">No active patterns</p>` : null}
+                    ${state.patterns.map(p => html`<${PatternGrid} key=${p.name} pattern=${p} state=${state} />`)}
+                </div>
+            </div>
+                </div>
+                `;
+        }
+
+        render(html`<${App} />`, document.getElementById('app'));
+    </script>
+</body>
+
+</html>