Subsequence

A Stateful Algorithmic MIDI Sequencer for Python. Subsequence is a generative MIDI sequencer and algorithmic composition engine for your studio. It gives you a palette of advanced algorithmic building blocks - Euclidean rhythm generators, cellular automata, L-systems, Markov chains - and a stateful engine that lets them interact and evolve over time, driving your hardware synths and VSTs with rock-solid timing.

It is designed for the professional musician who wants generative music with as much control or chaos as they choose - where patterns combine, react to context, and develop in ways that reward exploration.

Unlike tools that loop a fixed pattern forever, Subsequence rebuilds every pattern fresh before each cycle, granting macro-level structural control and narrative evolution. Each rebuild has full context - the current chord, the composition section, the cycle count, shared data from other patterns. A Euclidean rhythm can thin itself as tension builds; a cellular automaton can seed from the harmony.

An optional chord graph lets you define weighted chord and key transitions; layer on cognitive harmony for Narmour-based melodic inertia, gravity, and voice leading - progressions that model how listeners expect music to move.

Use your own gear. Subsequence provides the logic; your Eurorack, Elektron boxes, or DAW provide the sound. Serving as a boundless software alternative to hardware sequencers, there are no fixed limits on tracks, polyphony, complexity, or pattern length.

What you need: Basic Python knowledge and any MIDI-controllable instrument. Whether you are an experienced coder or a musician tempted to learn Python for the first time, the API is intuitive and accessible. Subsequence generates pure MIDI data; it does not produce sound itself.

Contents

• 1. Getting Started
  • Introduction
  • Why Subsequence?
  • What it does
  • Minimal Example
  • Quick start
• 2. Generating Music
  • Algorithmic generators
  • Melody generation
• 3. The Core APIs
  • Composition API
  • Direct Pattern API
  • Mini-notation
• 4. Harmony & Structure
  • Form and sections
  • The Conductor
  • Chord inversions and voice leading
  • Harmony and chord graphs
  • Frozen progressions
• 5. Live Performance & Tools
  • Seed and deterministic randomness
  • Terminal display
  • Web UI Dashboard (Beta)
  • MIDI recording and rendering
  • Live coding
  • Clock accuracy
  • MIDI input and external clock
  • Ableton Link
  • Pattern tools and hardware control
  • OSC integration
  • Hotkeys
  • Groove
• 6. Workflow & Utilities
  • Examples
  • Extra utilities
• 7. Project Info
  • Feature Roadmap
  • Tests
  • Community and Feedback
  • Dependencies and Credits
  • About the Author
  • License

1. Getting Started

Introduction

Subsequence is a generative MIDI sequencer and algorithmic composition engine for your studio. Engineered for rock-solid timing and efficiency, it gives you a palette of advanced algorithmic building blocks - Euclidean rhythm generators, cellular automata, L-systems, Markov chains - and a stateful engine that lets them interact and evolve over time.

It is designed for the professional musician who wants generative music with as much control or chaos as they choose - where patterns combine, react to context, and develop in ways that reward exploration. An optional chord graph lets you define weighted chord and key transitions; layer on cognitive harmony for Narmour-based melodic inertia, gravity, and voice leading - progressions that model how listeners expect music to move.

Why Subsequence?

• Precision and efficiency. Built for live performance and serious studio use. A highly-optimized hybrid timing strategy achieves typical pulse jitter of < 5 μs on Linux, while a comprehensively tested codebase provides rock-solid stability.
• Accessible Python, no CS degree required. If you can configure a synth, you can write generative music here. It is the perfect project to tempt a musician into learning basic Python. Simple algorithmic building blocks mean you can get started with tiny scripts and learn as you go.
• Not just for algorithms. You can program traditional basslines or fixed drum grooves without any generative variation. Use Subsequence as a highly precise, Python-driven standard MIDI sequencer alongside your evolving patterns.
• Implicit Compositional Structure. Subsequence understands predefined sections, bringing overarching musical form to a piece without getting stuck in infinite loops. Patterns rebuild each cycle with full context - chord, section, history - so music can grow and develop across defined movement.
• Built-in harmonic intelligence. An optional chord graph lets you define weighted chord and key transitions, with gravity and automatic voice leading. Layer on cognitive harmony for Narmour-based melodic inertia - big leaps tend to reverse, small steps tend to continue - for melodies that model deep listener expectations.
• Between traditional and generative. Most sequencers repeat a fixed loop. Most live-coding environments are stateless - the algorithm has no memory of what it just generated. Subsequence rebuilds every pattern fresh each cycle with full context: current chord, section, history, shared data. Patterns that evolve, remember, and react.
• Patterns that talk to each other. Shared state (composition.data) lets autonomous generators cooperate without coupling. A drum pattern can broadcast its density; a bass pattern reads it to place complementary gaps. No callbacks, no wiring - just a shared namespace rebuilt in sync.
• Explore, capture, produce. Seed a session for deterministic output: explore freely, and when something clicks, the same seed recreates it exactly. Record to a standard multi-channel .mid file and bring it straight into your DAW to arrange, edit, and polish.
• Turn anything into music. Patterns are plain Python functions, so any data source - live APIs, sensors, files, network streams - can drive musical decisions at rebuild time. Orbital telemetry, weather data, stock feeds, machine learning outputs: if Python can read it, Subsequence can play it.
• Microtonal-ready. Scala .scl file support and N-TET equal temperaments out of the box. Per-note pitch bend is injected automatically - no MPE, no special hardware. Works with any standard MIDI synth.

What it does

• Stateful patterns that evolve. Each pattern is a Python function rebuilt fresh every cycle with full context. Patterns can remember history and decide their next move.
• Cognitive harmony engine. Chord progressions evolve via weighted transition graphs with adjustable gravity and Narmour-based melodic inertia. Automatic voice leading.
• Single-digit-microsecond clock. A hybrid sleep+spin timing strategy achieves typical pulse jitter of < 5 μs on Linux (measured), with zero long-term drift.
• Pure MIDI, zero sound engine. Route to hardware synths, drum machines, Eurorack, or VSTs. You provide the sound; Subsequence provides the logic.

Minimal Example

This is all the code you need to build a simple drum pattern:

import subsequence
import subsequence.constants.instruments.gm_drums as gm_drums

composition = subsequence.Composition(bpm=120)

@composition.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) # beats 1, 2, 3, 4
    p.hit_steps("snare_1", [4, 12], velocity=90) # beats 2 and 4
    p.hit_steps("hi_hat_closed", range(16), velocity=70) # every sixteenth

composition.play()

Quick start

1. Install dependencies:

pip install -e .

2. Enable Ableton Link support (optional):

pip install -e ".[link]"

3. Run the demo:

python examples/demo.py

For the complete API reference, see the documentation.

2. Generating Music

Algorithmic generators

Before diving into the API, here's what powers it. Subsequence is built on algorithms borrowed from mathematics, physics, biology, and computer science - ideas originally developed to model weather, simulate chemical reactions, draw straight lines on plotters, and generate textures for films. Each one, when applied to rhythm and melody, produces results with a character you can't achieve by programming notes by hand.

These are some of the building blocks available for composition in Subsequence. You don't need to understand the maths to use them - most take two or three parameters and produce something musically interesting immediately.

They're designed to work together inside the stateful engine. A Euclidean rhythm can thin itself based on a conductor signal; a cellular automaton can seed from the current chord; a Perlin noise field can drift velocity across bars while a Markov chain steers the harmony. The algorithms are the vocabulary - the rebuild engine is the grammar.

The first three entries belo