Appendix D · API Quick Reference¶

A fast lookup of Subsequence’s public API, grouped by what you’re trying to do — every entry links to the chapter that teaches it and points you at the exhaustive cheatsheet for full signatures. This is the page a returning user reaches for: not to learn a method, but to remember its name.

Note

This appendix is organised by task, not exhaustive on signatures. It names the method and tells you which chapter teaches it; for every argument, default, and return type, go to the source of truth — the sequencer’s own api-cheatsheet.md (the v0.6.2 method catalog). Names here are cross-checked against that cheatsheet; where a method’s full arguments matter, the chapter link shows it in context.

D.1 The verb-family idea: learn one verb, predict the rest¶

Subsequence’s surface is large, but it is regular. The generators, the expression ramps, and the value transforms each form a family whose members share argument names and shapes. Learn one member properly and you can predict the rest — which is exactly what makes a quick-reference like this usable instead of overwhelming.

Family	Shared shape	Members (all on `p`)
Rhythm generators	`p.NAME(pitch, …, probability=, no_overlap=, seed=, rng=)`	`euclidean`, `bresenham`, `cellular_1d`, `thue_morse`, `reaction_diffusion`, `ghost_fill`, `ratchet` — place a drum/pitch on an algorithmically chosen rhythm. Pin `seed=` and you get the same rhythm every run.
Expression ramps	`p.X_ramp(target, start, end, beat_start, beat_end, resolution=, shape=)`	`cc_ramp`, `pitch_bend_ramp`, `nrpn_ramp`, `rpn_ramp`, `osc_ramp` — sweep a continuous value over a beat range. Each has a single-shot sibling (`cc`, `pitch_bend`, `nrpn`, `rpn`, `osc`).
Value transforms	`value.transform(...) -> new value`	`transpose`, `invert`, `reverse`, `rotate`, `stretch`, `quantize`, `with_velocity`, `pitched`, `rhythm` — every one returns a new `Motif`/`Phrase`, never mutates in place. The same names mean the same thing on both types.

D.2 `Composition` methods by topic¶

composition is the conductor — it owns tempo, output, the form, the harmony engine, and every live control. The methods below are grouped by the job you’d reach for them to do. For arguments and return types see api-cheatsheet.md.

D.2.1 Setup, transport, and rendering¶

Method	What it does	Taught in
`Composition(bpm, output_device, time_signature, key, scale, seed, …)`	Create the piece — tempo, MIDI port, key, and the master `seed`.	§1.1
`pattern(channel, beats, …, min_energy)`	The decorator that registers a function as a repeating pattern.	§1.2
`render(bars, filename, max_minutes)`	Render to a MIDI file headlessly — no real time, no instrument.	§0.7
`play()`	Stream MIDI live off the wall clock (Ctrl-C to stop).	§0.8
`set_bpm(bpm)` · `target_bpm(bpm, bars, shape)`	Change tempo instantly, or ramp smoothly over a number of bars.	§12.7
`display(enabled, grid, grid_scale)`	Turn on the live terminal dashboard (status line, optional ASCII grid).	§1.7
`live_info()` · `running_patterns` (property)	Inspect the live state, or the active patterns keyed by name.	§14.1

D.2.2 Rhythm, layering, and one-shots¶

Method	What it does	Taught in
`layer(*builder_fns, channel, beats, …)`	Combine several builder functions into one MIDI pattern (one channel).	§13.5
`trigger(fn, channel, beats, …, quantize)`	Fire a one-shot pattern now or on the next quantized boundary.	reference only — see `api-cheatsheet.md`
`schedule(fn, cycle_beats, …)`	Run a plain function on a repeating beat-based cycle (sonification, automation).	§14.5

D.2.3 Harmony and chords¶

Method	What it does	Taught in
`harmony(style, cycle_beats, gravity, …, progression)`	Turn on the live chord engine — patterns can then receive `chord`.	§6.1
`chords(channel, progression, harmonic_rhythm, …)`	Declare a self-contained chord part at a chosen harmonic rhythm.	§7.6
`current_chord()` · `harmonic_state` (property)	The chord sounding at the playhead; the active `HarmonicState`.	§6.6
`pin_chord(bar, chord)`	Force the chord at a bar — fiat over the live generator.	reference only — see `api-cheatsheet.md`
`request_cadence(cadence, bar)`	Ask the live engine to approach a cadence arriving at a bar.	reference only — see `api-cheatsheet.md`
`freeze(bars, end, pins, avoid, cadence)`	Capture the live harmony into an editable `Progression` value.	§11.5

D.2.4 Form, sections, and energy¶

Method	What it does	Taught in
`form(sections, loop, start, at_end, …)`	Define the structure — a list form or a graph form.	§10.1
`energy(energies)`	Set per-section energy — the arranging dial — as one dict.	§10.3
`transition(before, fill, …, mute)`	Declare boundary material: an automatic fill or mute, in one line.	§10.4
`section_chords(section_name, progression)`	Bind a `Progression` to a named section.	§10.5
`section_motifs(section_name, value, part)`	Bind a `Motif`/`Phrase` to a named section (optionally per part).	§10.5
`section_cadence(section_name, cadence)`	Close every pass of a section with a cadence.	reference only — see `api-cheatsheet.md`
`phrase_part(channel, part, …)`	A part that plays whatever Motif/Phrase the current section binds.	§10.5
`form_jump(name)` · `form_next(name)` · `form_freeze(sections)`	Live navigation: jump now, queue the next section, or freeze a graph walk.	§10.6
`on_section(callback)`	Run a callback on every section change.	§10.6

D.2.5 Motifs and phrases (placement helpers)¶

Method	What it does	Taught in
`section_chords` / `section_motifs` / `section_cadence`	Bind values to sections (see §D.2.4 above).	§10.5
`phrase_part(channel, part, …)`	The composition-level part that renders each section’s bound material.	§10.5

Note

Most motif/phrase work happens on p (placing) and on the value itself (transforming), not on composition — see §D.3.5 and §D.4. The composition’s job is binding material to sections.

D.2.6 Live performance and control¶

Method	What it does	Taught in
`watch(path, poll_interval)` · `live(port)` · `load_patterns(source, …)`	Hot-swap code: reload on save, run an eval server, or apply a source string.	§14.1
`tweak(name, *kwargs)` · `get_tweaks(name)` · `clear_tweak(name, params)`	Override / read / clear a running pattern’s parameters live.	§14.2
`mute(name)` · `unmute(name)` · `unregister(name)`	Mute, unmute, or fully remove a running pattern.	§14.2
`hotkey(key, action, quantize, label)` · `hotkeys(enabled)`	Bind a single key to an action; enable the global key listener.	§14.2
`lock(name)` · `unlock(name)` · `reroll(name)`	Pin a stream’s realization; release it; deal it a fresh seed.	§11.4
`on_event(event_name, callback)`	Run a callback on a sequencer event (`"bar"`, `"start"`, `"stop"`, …).	reference only — see `api-cheatsheet.md`

D.2.7 External input, output, and sync (I/O)¶

Method	What it does	Taught in
`midi_input(device, clock_follow, name)` · `note_input(channel, …, latch)`	Configure a MIDI input for sync/messages; track held keys for arpeggiation.	§14.3
`midi_output(device, name, latency_ms)` · `clock_output(enabled)`	Register an extra output device; send MIDI clock to hardware.	§13.5, §14.6
`mirror(name, device, channel, …)` · `unmirror(…)` · `unmirror_all(name)`	Add or remove mirror destinations on a running pattern (one part, many devices).	§13.5
`cc_forward(cc, …)` · `cc_map(cc, data_key, …)`	Forward an incoming CC to output, or map it into `composition.data`.	§14.2
`osc(receive_port, send_port, …)` · `osc_map(address, handler)`	Enable bi-directional OSC; register a custom OSC handler.	§14.4
`web_ui(http_host, ws_host)`	Enable the realtime Web UI dashboard (beta).	§14.5
`link(quantum)`	Enable Ableton Link tempo/phase sync.	§14.6
`tuning(source, cents, ratios, equal, …)`	Set a global microtonal tuning for the whole composition.	§13.6

D.2.8 Determinism and inspection¶

Method	What it does	Taught in
`seed` (property) · `seed_for(name)`	The master seed; the effective derived seed for a named stream.	§11.1, §11.2
`lock(name)` · `unlock(name)` · `reroll(name)`	Pin / release / re-deal a stream’s randomness (also under live control).	§11.4
`sequencer` (property) · `builder_bar` (property)	The underlying `Sequencer`; the bar index pattern builders see.	§14.2

D.3 Pattern-builder (`p.*`) methods by topic¶

Inside a pattern function the one argument p is the builder — the palette you paint onto. Almost every method returns p, so calls chain. Grouped by task:

D.3.1 Notes, beats, and durations¶

Method	What it does	Taught in
`p.note(pitch, beat, velocity, duration)`	Place one note at a beat. `beat` is required (no bare `p.note(pitch)`).	§3.1
`p.hit(pitch, beats, velocity, duration)`	Place short hits at a list of beat positions.	§3.4
`p.hit_steps(pitch, steps, velocity, …, probability, seed, rng)`	Place short hits at grid step positions (0-indexed).	§1.4
`p.sequence(steps, pitches, velocities, durations, …)`	Multi-parameter step sequencer — parallel lists for pitch/vel/dur.	§3.3
`p.repeat(pitch, spacing, velocity, duration)`	Repeat one note at a fixed beat interval across the pattern.	§3.4
`p.duration(beats)` · `p.legato(ratio)` · `p.detached(beats)`	Set a fixed length; fill to the next onset; guarantee a gap before it.	§3.4, §1.6
`p.drone(pitch, …)` · `p.drone_off(pitch)` · `p.note_on/off` · `p.silence(beat)`	Sustained notes that span cycles, and the All-Notes-Off panic.	§3.4
`p.seq(notation, …)`	The legacy mini-notation string parser (a single aside, not an entry point).	§3.6

D.3.2 Rhythm generators and timing feel¶

Method	What it does	Taught in
`p.euclidean(pitch, pulses, …, seed, rng)`	Spread `pulses` evenly across the bar (Bjorklund) — one number, a groove.	§4.1
`p.bresenham(pitch, pulses, …)` · `p.bresenham_poly(parts, …)`	Line-algorithm spread; weighted polyphonic spread across drum voices.	§4.2
`p.ratchet(subdivisions, …)`	Subdivide existing notes into rapid rolls / ratchets.	§4.3
`p.ghost_fill(pitch, density, bias, …)` · `p.build_ghost_bias(grid, bias)`	Probability-biased ghost notes; the bias weights behind them.	§12.6
`p.swing(percent, grid, strength)`	Apply swing feel — a timing tool (not pitch).	§4.4
`p.groove(template, strength)`	Apply a `Groove` template (timing + velocity) to every note.	§13.4
`p.randomize(timing, velocity, …)`	Add small random timing/velocity variation — humanise.	§13.4
`p.rotate(steps, grid)` · `p.reverse()` · `p.stretch(factor)` · `p.set_length(length)`	Shift / flip / scale the bar in time; change the pattern’s length.	§12.9
`p.thin(pitch, strategy, amount, …)` · `p.dropout(probability, …)`	Remove notes by rhythmic position, or at random.	§12.9

D.3.3 Melody, pitch, and scales¶

Method	What it does	Taught in
`p.snap_to_scale(key, mode, strength, …)`	Pull every note to the nearest scale pitch — the pitch-correction tool.	§5.2
`p.transpose(semitones)` · `p.invert(pivot)`	Shift all pitches; mirror them around a pivot.	§5.2
`p.melody(state, spacing, …)`	Generate a single line by querying a persistent `MelodicState`.	§12.8
`p.markov(transitions, pitch_map, …)` · `p.lsystem(…)` · `p.evolve(…)` · `p.branch(…)`	Walked / rewritten / mutating / fractal-tree melodies.	§12.2, §12.5
`p.lorenz(…)` · `p.cellular_1d/2d(…)` · `p.reaction_diffusion(…)`	Chaos, automata, and reaction-diffusion as note sources.	§12.1, §12.3
`p.fibonacci(…)` · `p.de_bruijn(…)` · `p.thue_morse(…)` · `p.self_avoiding_walk(…)`	Number-theoretic and combinatorial pitch/rhythm generators.	§12.4

D.3.4 Harmony, chords, and arpeggios¶

Method	What it does	Taught in
`p.chord(chord_obj, root, velocity, inversion, …, beat)`	Place a chord at `beat` (the bar start by default).	§6.4
`p.arpeggio(notes, root, count, span, spacing, direction, …)`	Cycle a chord’s notes one at a time at regular beat intervals.	§6.4
`p.broken_chord(chord_obj, order, spacing, …)` · `p.strum(chord_obj, spacing, direction, …)`	Arpeggiate in a chosen/random order; strum with a small per-note offset.	§7.7
`p.progression(source, harmonic_rhythm, key, seed, rng)`	Lay a `Progression` across the pattern, returning it so you can place to it.	§7.6

Tip

To receive the current chord, don’t call a method — declare a parameter named chord (and optionally key, scale) on the pattern function, and Subsequence injects it each cycle (§6.2). The p.chord* methods are for placing a chord you already hold.

D.3.5 Placing motifs and phrases¶

Method	What it does	Taught in
`p.motif(m, beat, span, root, velocity, fit, …)`	Place an immutable `Motif`; `fit` snaps it to the current harmony.	§8.5
`p.phrase(value, root, velocity, fit, align, offset, …)`	Place this cycle’s window of a `Phrase` — position computed, never stored.	§9.4
`p.capture(beat, span)`	Read the notes placed so far back out as a new `Motif`.	§8.6
`p.section_motif(part)`	The Motif/Phrase bound to the current section (and part), or `None`.	§10.5

D.3.6 Velocity and expression¶

Method	What it does	Taught in
`p.velocity_shape(low, high)`	Spread the velocity of everything placed evenly across a range.	§1.5
`p.scale_velocities(factors, grid)` · `p.build_velocity_ramp(low, high, …)`	Multiply velocities per step; build a ramp list to hand to it.	§12.9
`p.duck_map(steps, floor, grid)`	Build a per-step velocity-multiplier list for sidechain-style ducking.	reference only — see `api-cheatsheet.md`
`p.cc(control, value, beat)` · `p.cc_ramp(control, start, end, …, shape)`	One CC write at a beat; a CC swept over a beat range.	§13.1
`p.pitch_bend(…)` · `p.pitch_bend_ramp(…)` · `p.bend(note, amount, …)`	Single bend, a swept bend, or bend one note by index.	§13.2
`p.portamento(time, …)` · `p.slide(notes, steps, time, …)`	Glide between consecutive notes; TB-303-style selective slide.	§13.2
`p.nrpn / nrpn_ramp` · `p.rpn / rpn_ramp` · `p.program_change(…)` · `p.sysex(data, beat)`	NRPN/RPN writes and sweeps; program/bank change; raw SysEx.	§13.3
`p.osc(address, *args, beat)` · `p.osc_ramp(address, start, end, …)`	Emit an OSC message, or sweep an OSC float over a beat range.	§14.4
`p.apply_tuning(tuning, bend_range, …)`	Apply a microtonal tuning to this one pattern via pitch-bend injection.	§13.6

D.3.7 Position, conductor, and shared state¶

Method / property	What it does	Taught in
`p.cycle` · `p.bar` · `p.bar_cycle(length)`	Where you are: the cycle count, the bar, the bar’s slot in a cycle of bars.	§2.3
`p.data`	The shared dict for passing state between patterns and cycles.	§2.5
`p.section`	The current `Section` (name, energy, key/scale) — read it to react.	§10.2
`p.signal(name)` · `p.c` / `p.conductor`	Read a conductor signal (LFO/ramp) at the current bar.	§12.7
`p.every(n, fn)`	Apply a transformation every Nth cycle.	§12.9
`p.param(name, default)`	Read a tweakable parameter (the value behind `composition.tweak`).	§14.2
`p.held_notes()`	The MIDI notes currently held on the `note_input` keyboard.	§14.3
`p.grid` (property)	The number of grid slots in this pattern (16 for a 4-beat sixteenth grid).	§1.4

D.4 Values and factories (Motif / Phrase / Progression / Section / Form)¶

These are immutable values: every transform returns a new value, so you can build a library by hand and reshape it without surprises. The factories below are pure — they need no Composition, which makes them easy to try in isolation:

>>> from subsequence import Motif, Form, progression, motif, sentence
>>> m = motif([1, 3, 5, 1], beats=[0, 1, 2, 3])   # a 4-beat idea, key-relative degrees
>>> ph = sentence(m, bars=4, seed=1)               # grow it into a 4-bar phrase
>>> pr = progression([1, 6, 4, 5], key="C")        # I vi IV V as scale degrees
>>> fm = Form([("intro", 4), ("verse", 8)]).with_energy({"verse": 0.7})
>>> m.length, ph.length, pr.length, fm.bars
(4.0, 16.0, 16.0, 12)

D.4.1 Building values (factories)¶

Factory	What it builds	Taught in
`motif(degrees, beats, …)` · `Motif.degrees(…)` · `Motif.notes(…)` · `Motif.steps(…)`	A `Motif` from scale degrees, absolute MIDI, or grid steps.	§8.2
`Motif.hits(…)` · `Motif.euclidean(…)` · `Motif.preset(name, …)` · `Motif.generate(…)`	Drum-hit, euclidean, named world-rhythm, and generated motifs.	§8.7, §12.8
`sentence(motif, bars, cadence, seed, …)` · `period(antecedent, cadence, …)`	The classical sentence and period, as thin phrase combinators.	§9.2
`Phrase.develop(motif, bars, plan, seed, …)`	Grow a motif into a phrase by a development plan.	§9.3
`progression(source, beats, style, bars, key, scale, seed, …)`	Build a `Progression` from degrees, romans, names, or a preset.	§7.1
`Progression.generate(style, bars, …)`	Generate a progression from a chord-graph walk.	§7.1
`Form([(name, bars), …])` · `Section(name, bars, energy, key, scale)`	The form value and its sections.	§10.1
`parse_chord(name)`	Parse `"Cm7"` / `"Dbmaj7"` into a `Chord`.	§7.1

D.4.2 Transforming `Motif` / `Phrase` (return a new value)¶

The same verb means the same thing on both types — this is the value-transform family from §D.1.

Method (on a `Motif` or `Phrase`)	What it does	Taught in
`.transpose(steps / semitones)` · `.invert(pivot)` · `.reverse()`	Shift pitch (degrees or semitones), mirror around a pivot, flip in time.	§8.3
`.rotate(beats)` · `.stretch(factor)` · `.quantize(grid)`	Rotate onsets, scale time, snap onsets to a grid. (`quantize` = timing.)	§8.3
`.with_velocity(velocity)` · `.pitched(spec)` · `.rhythm()`	Reset velocities, repitch every note, or strip to a rhythmic skeleton.	§8.3
`.then(other)` · `.stack(other)` · `m1 * n` · `m1 & m2`	Sequential concat; parallel merge; repeat; the `&` merge operator.	§8.4
`Motif.vary(notes, …)` · `Motif.answer(to)` · `Motif.accent(beat, amount)`	Smallest variation; call→response tail; add accent velocity.	§8.3
`Motif.slice(start, end)` · `Phrase.slice(start, end)` · `Phrase.flatten()`	A window onto the value; collapse a phrase to one long motif.	§8.4, §9.5
`Phrase.replace(position, motif)` · `Phrase.reroll(bar, bars, seed)`	Swap one segment; regenerate only named bars, keeping the rest.	§9.5
`Motif.cc / cc_ramp / pitch_bend / nrpn / …`	Attach control gestures as data — mirrors the `p.*` expression family.	§13.1

D.4.3 Shaping a `Progression`¶

Method (on a `Progression`)	What it does	Taught in
`.resolve(key, scale)` · `.describe(…)` · `.chords` / `.events()` (props)	Resolve relative spans to a key; print it; inspect the realised timeline.	§7.2
`.spread(style)` · `.inversions(spec)` · `.over(bass)`	Voicing spread (close/open/wide); inversions; slash/pedal bass.	§7.3
`.extend(*extensions)` · `.borrow(slot)` · `.elaborate(depth, seed)`	Add 7/9/11/13/sus; borrow from the parallel scale; approach-by-fifths.	§7.4
`.replace(slot, chord)` · `.with_rhythm(beats)` · `.cadence(name)`	Swap a chord; reshape harmonic rhythm; substitute a named cadence.	§7.4, §7.5

D.4.4 Shaping a `Form`¶

Method (on a `Form`)	What it does	Taught in
`.with_energy(energies)`	Set the energy payload on named sections.	§10.3
`.insert(slot, section)` · `.replace(slot, section, **changes)`	Insert a section; replace one whole or by field.	§10.1
`.describe()` · `.bars` (property)	One-section-per-line summary; total length in bars.	§10.1

D.4.5 Supporting values¶

Type / factory	What it is	Taught in
`Groove(offsets, grid, velocities)` · `Groove.swing(…)` · `Groove.from_agr(path)`	A timing/velocity template; from swing %, or an Ableton `.agr` file.	§13.4
`Tuning.equal(…)` · `Tuning.from_cents(…)` · `Tuning.from_ratios(…)` · `Tuning.from_scl(…)`	Microtonal tunings, including Scala `.scl` import.	§13.6
`MelodicState(key, mode, low, high, …)`	Persistent melodic context that scores a single line (for `p.melody`).	§12.8
`Chord` · `ChordSpan` · `PitchSet`	The harmony atoms: a named chord, one span of harmonic time, a nameless sonority.	§7.2
`scale_notes(key, mode, low, high, count)` · `register_scale(name, intervals, …)`	MIDI notes of a scale in a range; register a custom scale.	§5.3, §5.4
`bank_select(bank)` · `register_chord_quality(name, intervals, suffix)` · `between(low, high, step)`	14-bit bank → (MSB, LSB); a custom chord quality; a varying harmonic rhythm.	§13.3, §7.6, §B.4.2

D.5 Where to go deeper¶

This page is the map; the places below hold the territory.

For…	Go to
Exhaustive signatures — every argument, default, and return type	The sequencer’s `api-cheatsheet.md` (the v0.6.2 method catalog this appendix is built from). Names here are cross-checked against it.
The Direct Pattern API — `Pattern` subclassing and the async sequencer	Appendix A — the power-user path below the `@composition.pattern` decorator.
The analysis & set-theory toolkit — Toussaint metrics, Xenakis sieves, contour (`cseg`/`csim`), `register_*`	Appendix B. The Toussaint metrics and contour helpers live in `subsequence.sequence_utils`; `sieve`, `residual_class` and the `register_*` calls are top-level exports.
MIDI routing and troubleshooting — port names per OS, virtual ports, `latency_ms`	Appendix C.
A term you don’t recognise — musical or Subsequence-specific	Appendix E.

Tip

Two reading habits make the rest of the library predictable. First, the verb families (§D.1): when you meet a new generator, expect seed=/rng=; when you meet a new ramp, expect start/end/beat_start/ beat_end. Second, values are immutable: a Motif/Phrase/Progression transform always returns a new value, so you can chain freely and never lose the original.