# 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.
```

(sec-appD-verbs)=
## 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.

```{seealso}
The conventions behind that regularity — the front the chord verbs share, what
`(low, high)`, `seed=`, and `probability` always mean, the velocity defaults, and
which methods chain — are written out in full in
[Appendix G: Learn One Verb, Predict the Rest](appendix-g-api-contract).
```

Three families do most of the work:

```{list-table}
:header-rows: 1
:widths: 26 30 44

* - 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.
```

The pattern-generator chapter sets this idea out in full — see
[§4.5](04-generators-euclidean) ("learn one verb, predict the rest") — and the
motif chapter ([Chapter 8](08-motifs)) shows the transform family returning new
values.

```{important}
**`seed=` / `rng=` are the determinism pair, and they sit on almost every
generator.** Pass `seed=` (an int) for a repeatable choice that survives a live
reload; pass `rng=` (a `random.Random`) to drive a generator from a shared stream.
Leave both off and the choice is fresh each run. The whole precedence story is
[Chapter 11](11-seeds-locks-freeze).
```

```{warning}
**Three idioms were retired before v0.5 — do not use them.** They appear in old
forum posts and pre-v0.5 drafts and will mislead you:

- **`chord=True` on the decorator** is gone. To receive the current chord, declare
  a parameter named `chord` on your pattern function — Subsequence injects it by
  name ([§6.2](06-harmony-context)).
- **`quantize` does not touch pitch.** `quantize` and `swing` are *timing* tools.
  To pull pitches into a scale use **`p.snap_to_scale(...)`** ([§5.2](05-pitch-and-scales)).
- **`p.note(pitch)` with no beat is invalid.** The beat is required:
  **`p.note(pitch, beat=...)`** ([§3.1](03-notes-beats-durations)).
```

(sec-appD-comp)=
## 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

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - 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](01-step-grid)
* - `pattern(channel, beats, …, min_energy)`
  - The decorator that registers a function as a repeating pattern.
  - [§1.2](01-step-grid)
* - `render(bars, filename, max_minutes)`
  - Render to a MIDI file headlessly — no real time, no instrument.
  - [§0.7](00-setup)
* - `play()`
  - Stream MIDI live off the wall clock (Ctrl-C to stop).
  - [§0.8](00-setup)
* - `set_bpm(bpm)` · `target_bpm(bpm, bars, shape)`
  - Change tempo instantly, or ramp smoothly over a number of bars.
  - [§12.7](12-deep-generative)
* - `display(enabled, grid, grid_scale)`
  - Turn on the live terminal dashboard (status line, optional ASCII grid).
  - [§1.7](01-step-grid)
* - `live_info()` · `running_patterns` *(property)*
  - Inspect the live state, or the active patterns keyed by name.
  - [§14.1](14-live-and-data)
```

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

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - Method
  - What it does
  - Taught in
* - `layer(*builder_fns, channel, beats, …)`
  - Combine several builder functions into one MIDI pattern (one channel).
  - [§13.5](13-expression-hardware)
* - `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](14-live-and-data)
```

### D.2.3 Harmony and chords

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - 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](06-harmony-context)
* - `chords(channel, progression, harmonic_rhythm, …)`
  - Declare a self-contained chord part at a chosen harmonic rhythm.
  - [§7.6](07-progressions)
* - `current_chord()` · `harmonic_state` *(property)*
  - The chord sounding at the playhead; the active `HarmonicState`.
  - [§6.6](06-harmony-context)
* - `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](11-seeds-locks-freeze)
```

### D.2.4 Form, sections, and energy

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - Method
  - What it does
  - Taught in
* - `form(sections, loop, start, at_end, …)`
  - Define the structure — a list form or a graph form.
  - [§10.1](10-form-sections)
* - `energy(energies)`
  - Set per-section energy — the arranging dial — as one dict.
  - [§10.3](10-form-sections)
* - `transition(before, fill, …, mute)`
  - Declare boundary material: an automatic fill or mute, in one line.
  - [§10.4](10-form-sections)
* - `section_chords(section_name, progression)`
  - Bind a `Progression` to a named section.
  - [§10.5](10-form-sections)
* - `section_motifs(section_name, value, part)`
  - Bind a `Motif`/`Phrase` to a named section (optionally per part).
  - [§10.5](10-form-sections)
* - `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](10-form-sections)
* - `form_jump(name)` · `form_next(name)` · `form_freeze(sections)`
  - Live navigation: jump now, queue the next section, or freeze a graph walk.
  - [§10.6](10-form-sections)
* - `on_section(callback)`
  - Run a callback on every section change.
  - [§10.6](10-form-sections)
```

### D.2.5 Motifs and phrases (placement helpers)

```{list-table}
:header-rows: 1
:widths: 40 38 22

* - Method
  - What it does
  - Taught in
* - `section_chords` / `section_motifs` / `section_cadence`
  - Bind values to sections (see [§D.2.4](#sec-appD-comp) above).
  - [§10.5](10-form-sections)
* - `phrase_part(channel, part, …)`
  - The composition-level part that renders each section's bound material.
  - [§10.5](10-form-sections)
```

```{note}
Most motif/phrase work happens on `p` (placing) and on the value itself
(transforming), not on `composition` — see [§D.3.5](#sec-appD-motif-place) and
[§D.4](#sec-appD-values). The composition's job is *binding* material to sections.
```

### D.2.6 Live performance and control

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - 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](14-live-and-data)
* - `tweak(name, **kwargs)` · `get_tweaks(name)` · `clear_tweak(name, *params)`
  - Override / read / clear a running pattern's parameters live.
  - [§14.2](14-live-and-data)
* - `mute(name)` · `unmute(name)` · `unregister(name)`
  - Mute, unmute, or fully remove a running pattern.
  - [§14.2](14-live-and-data)
* - `hotkey(key, action, quantize, label)` · `hotkeys(enabled)`
  - Bind a single key to an action; enable the global key listener.
  - [§14.2](14-live-and-data)
* - `lock(name)` · `unlock(name)` · `reroll(name)`
  - Pin a stream's realization; release it; deal it a fresh seed.
  - [§11.4](11-seeds-locks-freeze)
* - `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)

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - 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](14-live-and-data)
* - `midi_output(device, name, latency_ms)` · `clock_output(enabled)`
  - Register an extra output device; send MIDI clock to hardware.
  - [§13.5](13-expression-hardware), [§14.6](14-live-and-data)
* - `mirror(name, device, channel, …)` · `unmirror(…)` · `unmirror_all(name)`
  - Add or remove mirror destinations on a running pattern (one part, many devices).
  - [§13.5](13-expression-hardware)
* - `cc_forward(cc, …)` · `cc_map(cc, data_key, …)`
  - Forward an incoming CC to output, or map it into `composition.data`.
  - [§14.2](14-live-and-data)
* - `osc(receive_port, send_port, …)` · `osc_map(address, handler)`
  - Enable bi-directional OSC; register a custom OSC handler.
  - [§14.4](14-live-and-data)
* - `web_ui(http_host, ws_host)`
  - Enable the realtime Web UI dashboard (beta).
  - [§14.5](14-live-and-data)
* - `link(quantum)`
  - Enable Ableton Link tempo/phase sync.
  - [§14.6](14-live-and-data)
* - `tuning(source, cents, ratios, equal, …)`
  - Set a global microtonal tuning for the whole composition.
  - [§13.6](13-expression-hardware)
```

### D.2.8 Determinism and inspection

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - 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-seeds-locks-freeze), [§11.2](11-seeds-locks-freeze)
* - `lock(name)` · `unlock(name)` · `reroll(name)`
  - Pin / release / re-deal a stream's randomness (also under live control).
  - [§11.4](11-seeds-locks-freeze)
* - `sequencer` *(property)* · `builder_bar` *(property)*
  - The underlying `Sequencer`; the bar index pattern builders see.
  - [§14.2](14-live-and-data)
```

(sec-appD-p)=
## 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

```{list-table}
:header-rows: 1
:widths: 32 46 22

* - 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](03-notes-beats-durations)
* - `p.hit(pitch, beats, velocity, duration)`
  - Place short hits at a *list of beat* positions.
  - [§3.4](03-notes-beats-durations)
* - `p.hit_steps(pitch, steps, velocity, …, probability, seed, rng)`
  - Place short hits at *grid step* positions (0-indexed).
  - [§1.4](01-step-grid)
* - `p.sequence(steps, pitches, velocities, durations, …)`
  - Multi-parameter step sequencer — parallel lists for pitch/vel/dur.
  - [§3.3](03-notes-beats-durations)
* - `p.repeat(pitch, spacing, velocity, duration)`
  - Repeat one note at a fixed beat interval across the pattern.
  - [§3.4](03-notes-beats-durations)
* - `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](03-notes-beats-durations), [§1.6](01-step-grid)
* - `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](03-notes-beats-durations)
* - `p.seq(notation, …)`
  - The legacy mini-notation string parser (a single aside, not an entry point).
  - [§3.6](03-notes-beats-durations)
```

### D.3.2 Rhythm generators and timing feel

```{list-table}
:header-rows: 1
:widths: 36 42 22

* - 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](04-generators-euclidean)
* - `p.bresenham(pitch, pulses, …)` · `p.bresenham_poly(parts, …)`
  - Line-algorithm spread; weighted polyphonic spread across drum voices.
  - [§4.2](04-generators-euclidean)
* - `p.ratchet(subdivisions, …)`
  - Subdivide existing notes into rapid rolls / ratchets.
  - [§4.3](04-generators-euclidean)
* - `p.ghost_fill(pitch, density, bias, …)` · `p.build_ghost_bias(grid, bias)`
  - Probability-biased ghost notes; the bias weights behind them.
  - [§12.6](12-deep-generative)
* - `p.swing(percent, grid, strength)`
  - Apply swing feel — a **timing** tool (not pitch).
  - [§4.4](04-generators-euclidean)
* - `p.groove(template, strength)`
  - Apply a `Groove` template (timing + velocity) to every note.
  - [§13.4](13-expression-hardware)
* - `p.randomize(timing, velocity, …)`
  - Add small random timing/velocity variation — humanise.
  - [§13.4](13-expression-hardware)
* - `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](12-deep-generative)
* - `p.thin(pitch, strategy, amount, …)` · `p.dropout(probability, …)`
  - Remove notes by rhythmic position, or at random.
  - [§12.9](12-deep-generative)
```

### D.3.3 Melody, pitch, and scales

```{list-table}
:header-rows: 1
:widths: 36 42 22

* - 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](05-pitch-and-scales)
* - `p.transpose(semitones)` · `p.invert(pivot)`
  - Shift all pitches; mirror them around a pivot.
  - [§5.2](05-pitch-and-scales)
* - `p.melody(state, spacing, …)`
  - Generate a single line by querying a persistent `MelodicState`.
  - [§12.8](12-deep-generative)
* - `p.markov(transitions, pitch_map, …)` · `p.lsystem(…)` · `p.evolve(…)` · `p.branch(…)`
  - Walked / rewritten / mutating / fractal-tree melodies.
  - [§12.2](12-deep-generative), [§12.5](12-deep-generative)
* - `p.lorenz(…)` · `p.cellular_1d/2d(…)` · `p.reaction_diffusion(…)`
  - Chaos, automata, and reaction-diffusion as note sources.
  - [§12.1](12-deep-generative), [§12.3](12-deep-generative)
* - `p.fibonacci(…)` · `p.de_bruijn(…)` · `p.thue_morse(…)` · `p.self_avoiding_walk(…)`
  - Number-theoretic and combinatorial pitch/rhythm generators.
  - [§12.4](12-deep-generative)
```

### D.3.4 Harmony, chords, and arpeggios

```{list-table}
:header-rows: 1
:widths: 36 42 22

* - 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](06-harmony-context)
* - `p.arpeggio(notes, root, count, span, spacing, direction, …)`
  - Cycle a chord's notes one at a time at regular beat intervals.
  - [§6.4](06-harmony-context)
* - `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](07-progressions)
* - `p.progression(source, harmonic_rhythm, key, seed, rng)`
  - Lay a `Progression` across the pattern, returning it so you can place to it.
  - [§7.6](07-progressions)
```

```{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](06-harmony-context)). The `p.chord*` methods are for
*placing* a chord you already hold.
```

(sec-appD-motif-place)=
### D.3.5 Placing motifs and phrases

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - 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](08-motifs)
* - `p.phrase(value, root, velocity, fit, align, offset, …)`
  - Place *this cycle's window* of a `Phrase` — position computed, never stored.
  - [§9.4](09-phrases)
* - `p.capture(beat, span)`
  - Read the notes placed so far back out as a new `Motif`.
  - [§8.6](08-motifs)
* - `p.section_motif(part)`
  - The Motif/Phrase bound to the current section (and part), or `None`.
  - [§10.5](10-form-sections)
```

### D.3.6 Velocity and expression

```{list-table}
:header-rows: 1
:widths: 36 42 22

* - Method
  - What it does
  - Taught in
* - `p.velocity_shape(low, high)`
  - Spread the velocity of *everything placed* evenly across a range.
  - [§1.5](01-step-grid)
* - `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](12-deep-generative)
* - `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](13-expression-hardware)
* - `p.pitch_bend(…)` · `p.pitch_bend_ramp(…)` · `p.bend(note, amount, …)`
  - Single bend, a swept bend, or bend one note by index.
  - [§13.2](13-expression-hardware)
* - `p.portamento(time, …)` · `p.slide(notes, steps, time, …)`
  - Glide between consecutive notes; TB-303-style selective slide.
  - [§13.2](13-expression-hardware)
* - `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](13-expression-hardware)
* - `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](14-live-and-data)
* - `p.apply_tuning(tuning, bend_range, …)`
  - Apply a microtonal tuning to this one pattern via pitch-bend injection.
  - [§13.6](13-expression-hardware)
```

### D.3.7 Position, conductor, and shared state

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - 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](02-rebuild-loop)
* - `p.data`
  - The shared dict for passing state between patterns and cycles.
  - [§2.5](02-rebuild-loop)
* - `p.section`
  - The current `Section` (name, energy, key/scale) — read it to react.
  - [§10.2](10-form-sections)
* - `p.signal(name)` · `p.c` / `p.conductor`
  - Read a conductor signal (LFO/ramp) at the current bar.
  - [§12.7](12-deep-generative)
* - `p.every(n, fn)`
  - Apply a transformation every Nth cycle.
  - [§12.9](12-deep-generative)
* - `p.param(name, default)`
  - Read a tweakable parameter (the value behind `composition.tweak`).
  - [§14.2](14-live-and-data)
* - `p.held_notes()`
  - The MIDI notes currently held on the `note_input` keyboard.
  - [§14.3](14-live-and-data)
* - `p.grid` *(property)*
  - The number of grid slots in this pattern (16 for a 4-beat sixteenth grid).
  - [§1.4](01-step-grid)
```

(sec-appD-values)=
## 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:

```{doctest} appD
>>> 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)

```{list-table}
:header-rows: 1
:widths: 40 38 22

* - 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](08-motifs)
* - `Motif.hits(…)` · `Motif.euclidean(…)` · `Motif.preset(name, …)` · `Motif.generate(…)`
  - Drum-hit, euclidean, named world-rhythm, and generated motifs.
  - [§8.7](08-motifs), [§12.8](12-deep-generative)
* - `sentence(motif, bars, cadence, seed, …)` · `period(antecedent, cadence, …)`
  - The classical sentence and period, as thin phrase combinators.
  - [§9.2](09-phrases)
* - `Phrase.develop(motif, bars, plan, seed, …)`
  - Grow a motif into a phrase by a development plan.
  - [§9.3](09-phrases)
* - `progression(source, beats, style, bars, key, scale, seed, …)`
  - Build a `Progression` from degrees, romans, names, or a preset.
  - [§7.1](07-progressions)
* - `Progression.generate(style, bars, …)`
  - Generate a progression from a chord-graph walk.
  - [§7.1](07-progressions)
* - `Form([(name, bars), …])` · `Section(name, bars, energy, key, scale)`
  - The form value and its sections.
  - [§10.1](10-form-sections)
* - `parse_chord(name)`
  - Parse `"Cm7"` / `"Dbmaj7"` into a `Chord`.
  - [§7.1](07-progressions)
```

### 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](#sec-appD-verbs).

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - 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](08-motifs)
* - `.rotate(beats)` · `.stretch(factor)` · `.quantize(grid)`
  - Rotate onsets, scale time, snap onsets to a grid. *(`quantize` = timing.)*
  - [§8.3](08-motifs)
* - `.with_velocity(velocity)` · `.pitched(spec)` · `.rhythm()`
  - Reset velocities, repitch every note, or strip to a rhythmic skeleton.
  - [§8.3](08-motifs)
* - `.then(other)` · `.stack(other)` · `m1 * n` · `m1 & m2`
  - Sequential concat; parallel merge; repeat; the `&` merge operator.
  - [§8.4](08-motifs)
* - `Motif.vary(notes, …)` · `Motif.answer(to)` · `Motif.accent(beat, amount)`
  - Smallest variation; call→response tail; add accent velocity.
  - [§8.3](08-motifs)
* - `Motif.slice(start, end)` · `Phrase.slice(start, end)` · `Phrase.flatten()`
  - A window onto the value; collapse a phrase to one long motif.
  - [§8.4](08-motifs), [§9.5](09-phrases)
* - `Phrase.replace(position, motif)` · `Phrase.reroll(bar, bars, seed)`
  - Swap one segment; regenerate only named bars, keeping the rest.
  - [§9.5](09-phrases)
* - `Motif.cc / cc_ramp / pitch_bend / nrpn / …`
  - Attach control gestures as data — mirrors the `p.*` expression family.
  - [§13.1](13-expression-hardware)
```

### D.4.3 Shaping a `Progression`

```{list-table}
:header-rows: 1
:widths: 34 44 22

* - 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](07-progressions)
* - `.spread(style)` · `.inversions(spec)` · `.over(bass)`
  - Voicing spread (close/open/wide); inversions; slash/pedal bass.
  - [§7.3](07-progressions)
* - `.extend(*extensions)` · `.borrow(slot)` · `.elaborate(depth, seed)`
  - Add 7/9/11/13/sus; borrow from the parallel scale; approach-by-fifths.
  - [§7.4](07-progressions)
* - `.replace(slot, chord)` · `.with_rhythm(beats)` · `.cadence(name)`
  - Swap a chord; reshape harmonic rhythm; substitute a named cadence.
  - [§7.4](07-progressions), [§7.5](07-progressions)
```

### D.4.4 Shaping a `Form`

```{list-table}
:header-rows: 1
:widths: 34 44 22

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

### D.4.5 Supporting values

```{list-table}
:header-rows: 1
:widths: 30 48 22

* - 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](13-expression-hardware)
* - `Tuning.equal(…)` · `Tuning.from_cents(…)` · `Tuning.from_ratios(…)` · `Tuning.from_scl(…)`
  - Microtonal tunings, including Scala `.scl` import.
  - [§13.6](13-expression-hardware)
* - `MelodicState(key, mode, low, high, …)`
  - Persistent melodic context that scores a single line (for `p.melody`).
  - [§12.8](12-deep-generative)
* - `Chord` · `ChordSpan` · `PitchSet`
  - The harmony atoms: a named chord, one span of harmonic time, a nameless sonority.
  - [§7.2](07-progressions)
* - `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](05-pitch-and-scales), [§5.4](05-pitch-and-scales)
* - `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](13-expression-hardware), [§7.6](07-progressions), [§B.4.2](appendix-b-analysis-toolkit)
```

(sec-appD-deeper)=
## D.5 Where to go deeper

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

```{list-table}
:header-rows: 1
:widths: 32 68

* - 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](appendix-a-direct-pattern-api) — the power-user path below the
    `@composition.pattern` decorator.
* - **The analysis & set-theory toolkit** — Toussaint metrics, Xenakis sieves,
    contour (`cseg`/`csim`), `register_*`
  - [Appendix B](appendix-b-analysis-toolkit). 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](appendix-c-midi-routing).
* - **A term you don't recognise** — musical or Subsequence-specific
  - [Appendix E](appendix-e-glossary).
```

```{tip}
Two reading habits make the rest of the library predictable. First, **the verb
families** ([§D.1](#sec-appD-verbs)): 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.
```