The Subsequence Cookbook

From first sound to generative composition.

This guide is for a musician or producer who knows their way around MIDI and is happy to learn a little Python — no prior coding experience assumed. It starts by getting Python and Subsequence installed and a first beat playing, then builds step by step toward complex generative composition. Every example is runnable, and you can read front-to-back or jump straight to any topic from the sidebar. For an exhaustive method-by-method listing, see the API Reference.

Part I · Getting Started

• Chapter 0 · Setup and Your First Sound
  • 0.1 What Subsequence is (and what it isn’t)
  • 0.2 Installing Python and git
  • 0.3 A clean workspace: the virtual environment
  • 0.4 Installing Subsequence
  • 0.5 Connecting your instrument
  • 0.6 Your first composition
  • 0.7 Rendering it to a file
  • 0.8 Going live with play()
  • 0.9 Troubleshooting your first run

Part II · Pattern Fundamentals

• Chapter 1 · The Step Grid: Writing a Beat by Hand
  • 1.1 The Composition object
  • 1.2 The @composition.pattern decorator
  • 1.3 Channels are 1-indexed, steps are 0-indexed (the gotcha)
  • 1.4 Placing hits with hit_steps
  • 1.5 Velocity and humanisation
  • 1.6 Note length: legato and detached
  • 1.7 Reading the terminal display
• Chapter 2 · The Rebuild Loop: Patterns That Remember
  • 2.1 Your function re-runs every cycle
  • 2.2 p is a fresh canvas (values vs canvas)
  • 2.3 Reacting to position (p.cycle, p.bar, p.bar_cycle)
  • 2.4 Module-level reusable values
  • 2.5 Sharing state with p.data
• Chapter 3 · Notes, Beats, and Durations
  • 3.1 p.note and the required beat
  • 3.2 Beats vs grid steps
  • 3.3 A hand-written bassline (p.sequence)
  • 3.4 Durations, repeats, detached and legato
  • 3.5 Note and duration constants
  • 3.6 Legacy aside: mini-notation

Part III · Generators and Pitch

• Chapter 4 · Your First Generators: Euclidean and Spread Rhythms
  • 4.1 Euclidean rhythms from one number
  • 4.2 Bresenham and weighted spread (bresenham_poly)
  • 4.3 Ratchets and rolls
  • 4.4 Swing and timing feel (not pitch)
  • 4.5 “Learn one verb, predict the rest”; builder chaining
  • 4.6 Repeatability (seed= / rng=)
• Chapter 5 · Relative Pitch and Scales
  • 5.1 Keys and scale degrees
  • 5.2 Snapping to a scale: snap_to_scale (pitch, not timing)
  • 5.3 Scale note lists: scale_notes
  • 5.4 Custom scales: register_scale
  • 5.5 A pitch is a specification resolved late

Part IV · Harmony

• Chapter 6 · Harmony as Context: Following the Current Chord
  • 6.1 Turning on the chord engine (harmony())
  • 6.2 Receiving the chord by parameter name (not a flag)
  • 6.3 Basslines from the chord
  • 6.4 Pads & arpeggios from chord tones
  • 6.5 “The same notes sound different under different chords”
  • 6.6 Steering the engine (gravity, cycle_beats)
• Chapter 7 · Progressions as Values: Building and Shaping Harmony
  • 7.1 Writing a progression as a value
  • 7.2 Inspecting it: .describe() and print
  • 7.3 Voicing and voice-leading
  • 7.4 Decoration and substitution
  • 7.5 Cadences: strong, soft, open, fakeout
  • 7.6 Placing harmony: p.progression, composition.chords, between()
  • 7.7 Strummed and broken chords

Part V · Material and Form

• Chapter 8 · Motifs: Naming and Reusing Material
  • 8.1 What a Motif is (an immutable value)
  • 8.2 Building one: motif(), degrees, notes, steps
  • 8.3 Transforms return NEW values
  • 8.4 Combining: then / stack / slice and the + / * operators
  • 8.5 Placing under harmony: p.motif, root, fit
  • 8.6 Capturing placed notes back: p.capture
  • 8.7 Presets & world rhythms
• Chapter 9 · Phrases and Motivic Development
  • 9.1 From motif to phrase
  • 9.2 Classical builders: sentence() and period()
  • 9.3 Development plans: Phrase.develop
  • 9.4 Placing a phrase: p.phrase, align
  • 9.5 Selective regeneration: reroll/replace while keeping the rest
• Chapter 10 · Form, Sections, and Energy: Arranging a Track
  • 10.1 Defining a form (list and weighted graph)
  • 10.2 Reading the section: p.section
  • 10.3 Energy as the arranging dial
  • 10.4 Boundaries: transitions, fills, and mutes
  • 10.5 Binding harmony, motifs, and phrases to sections
  • 10.6 Live navigation and generative forms

Part VI · Production Workflow

• Chapter 11 · Explore, Capture, Produce: Seeds, Locks, Freeze
  • 11.1 One seed → a reproducible piece
  • 11.2 Per-pattern and per-generator randomness (and precedence)
  • 11.3 Re-seeding live correctly
  • 11.4 Lock and reroll
  • 11.5 Freezing live harmony into data
  • 11.6 Recording and offline rendering

Part VII · Advanced

• Chapter 12 · Deep Generative Systems: Chaos, Automata, and Scored Melody
  • 12.1 Cellular automata (cellular_1d / cellular_2d)
  • 12.2 L-systems and Markov chains
  • 12.3 Strange attractors and noise
  • 12.4 Number-theoretic generators
  • 12.5 Evolve and branch
  • 12.6 Textural percussion
  • 12.7 The Conductor: LFOs, ramps, signals
  • 12.8 Scored melody with MelodicState
  • 12.9 The pattern-transforms toolkit
• Chapter 13 · Expression and Hardware Control
  • 13.1 Continuous controllers: cc and cc_ramp
  • 13.2 Pitch bend, portamento, and slide
  • 13.3 NRPN/RPN, program change, bank select, and SysEx
  • 13.4 Groove and .agr import
  • 13.5 Routing to several devices: mirrors and layer
  • 13.6 Microtonal tuning
• Chapter 14 · Live Performance, External Data, and Sync
  • 14.1 Hot-swapping patterns without stopping the clock
  • 14.2 Live control: hotkeys, tweaks, mutes, and form jumps
  • 14.3 Live MIDI input and arpeggiation
  • 14.4 OSC: control and broadcast over the network
  • 14.5 External-data sonification: schedule, ease, sound
  • 14.6 Ableton Link: locking to the room

Appendices

• Appendix A · The Direct Pattern API
• Appendix B · Analysis and Set-Theory Toolkit
• Appendix C · MIDI Routing and Troubleshooting Reference
• Appendix D · API Quick Reference
• Appendix E · Glossary
• Appendix F · A Field Guide to the Generators
• Appendix G · Learn One Verb, Predict the Rest