# Appendix E · Glossary

Concise definitions of every musical and Subsequence-specific term the guide
uses, each cross-linked to the chapter where it is introduced — so you can jump
here from any page, get the one-line meaning, and follow the link to the full
treatment.

```{note}
Terms in **bold** are defined here; a *bare-stem* link such as
[Chapter 4](04-generators-euclidean) points to where the term is taught in full.
Where a name is a real API verb, it is spelled exactly as it appears in
[Appendix D](appendix-d-api-reference) and the sequencer's own `api-cheatsheet.md`.
```

(sec-appE-glossary)=
## E.1 Alphabetical glossary

```{list-table}
:header-rows: 1
:widths: 24 60 16

* - Term
  - Definition
  - See

* - **Bar / cycle**
  - One full turn of a pattern's loop. `beats=4` makes a one-bar loop; the
    pattern function re-runs once per turn. `p.cycle` counts cycles from `0`,
    `p.bar` counts absolute bars — equal for a one-bar pattern.
  - [Chapter 1](01-step-grid), [Chapter 2](02-rebuild-loop)

* - **bank select**
  - The pair of CC messages (MSB + LSB) that selects a patch *bank* before a
    program change. `bank_select(n)` converts a 14-bit bank number into the
    `(MSB, LSB)` a `p.program_change(...)` call needs.
  - [Chapter 13](13-expression-hardware)

* - **Bresenham rhythm**
  - An even rhythm spread by the Bresenham line-drawing algorithm. Like a
    Euclidean rhythm but it tends to land on the *trailing* edge of each group
    rather than the downbeat — a subtly different feel. The verb is
    `p.bresenham`.
  - [Chapter 4](04-generators-euclidean)

* - **Cadence**
  - The harmonic punctuation that ends a phrase. Subsequence names four:
    **strong** (V→I, the full stop / *authentic*), **soft** (IV→I, the gentle
    "amen" / *plagal*), **open** (IV→V, hangs unresolved / *half*), and
    **fakeout** (V→vi, sets up home then swerves / *deceptive*). Applied with
    `.cadence(name)` on a progression, or requested live with `cadence=`.
  - [Chapter 7](07-progressions), [Chapter 9](09-phrases)

* - **CC (continuous controller)**
  - A numbered MIDI control message carrying a value 0–127 — filter cutoff, mod
    wheel, volume, and so on. Sent with `p.cc(...)`, swept over time with
    `p.cc_ramp(...)`.
  - [Chapter 13](13-expression-hardware)

* - **Channel vs step**
  - The guide's one indexing gotcha. **MIDI channels are 1-indexed** (channel 10
    = drums, matching your gear); **grid steps are 0-indexed** (the first step is
    step `0`). They come from different worlds and never line up.
  - [Chapter 0](00-setup), [Chapter 1](01-step-grid)

* - **Chord injection**
  - How a pattern follows the live harmony: you *declare a parameter named*
    `chord` on the pattern function, and Subsequence passes the sounding chord in
    on every cycle. It is **not** a decorator flag — `chord=True` is a retired
    idiom.
  - [Chapter 6](06-harmony-context)

* - **Composition**
  - The top-level object — the conductor — that holds the tempo, owns the
    connection to your instrument, runs the clock, and to which every pattern is
    attached. You make exactly one per script.
  - [Chapter 1](01-step-grid)

* - **Conductor**
  - The composition's slow, piece-wide modulation source. You register
    time-varying **signals** on `composition.conductor` (an **LFO** that cycles
    forever, or a **line** that ramps once), and any pattern reads one with
    `p.signal(name)`.
  - [Chapter 12](12-deep-generative)

* - **Decorator**
  - The `@composition.pattern(...)` line directly above a function — a label that
    hands your function to the composition to run for you each cycle. You don't
    call the function yourself; the engine does. The same mechanism registers
    every **pattern**.
  - [Chapter 1](01-step-grid)

* - **Energy**
  - The single arranging dial, a number from `0.0` to `1.0` per section. A part
    reads it to scale its density or dynamics, and `min_energy=` on a pattern
    gates it off below a threshold. Set with `composition.energy({...})`.
  - [Chapter 10](10-form-sections)

* - **EasedValue / sonification**
  - The recipe for steering music from outside data: `composition.schedule(fn,
    cycle_beats=...)` fetches a value into `composition.data`, an
    `easing.EasedValue` smooths each reading toward the last (`.update`/`.get`),
    and a pattern reads the eased value and maps it (often via `scale_clamp`).
  - [Chapter 14](14-live-and-data)

* - **Euclidean rhythm**
  - The workhorse generator: spread N pulses as evenly as possible across the
    bar (via Bjorklund's algorithm). `p.euclidean("kick", pulses=4)` is four on
    the floor; `pulses=5` is a syncopated, rolling line.
  - [Chapter 4](04-generators-euclidean)

* - **Fakeout cadence**
  - See **Cadence** — the V→vi swerve that promises home and dodges to the
    submediant.
  - [Chapter 7](07-progressions)

* - **fit**
  - The melody-to-chord dial, `0.0`–`1.0`, on `p.motif`/`p.phrase`: the
    probability that a resolved scale degree landing on a strong beat snaps to
    the nearest tone of the sounding chord. Hand-written degrees default to
    `0.0` (played as written); generated material to a gentle `0.7`.
  - [Chapter 8](08-motifs)

* - **Form**
  - The track's structure: a sequence of named **sections** (intro, verse,
    chorus…). Declared with `composition.form([...])` as a fixed list or a
    weighted graph that decides its route as it goes; an editable `Form` value
    can be built and bound directly.
  - [Chapter 10](10-form-sections)

* - **Freeze**
  - Capturing the *live* harmony engine's improvised chords into a fixed,
    editable `Progression` value you can keep, print, and replay.
    `composition.freeze(bars=...)`.
  - [Chapter 11](11-seeds-locks-freeze)

* - **Ghost note**
  - A very soft hit that sits *under* the main pattern, felt more than heard —
    the micro-detail of a real groove. Scattered with `p.ghost_fill(...)`,
    weighted toward chosen grid positions by a bias.
  - [Chapter 12](12-deep-generative)

* - **Groove**
  - A timing-and-velocity template applied to quantized notes to humanise the
    feel — swing, push/pull, accent shape. A `Groove` value, often imported from
    an Ableton `.agr` file, applied with `p.groove(template)`.
  - [Chapter 13](13-expression-hardware)

* - **Hotkey**
  - A single-key live shortcut bound with `composition.hotkey(key, action)` (the
    action a zero-argument callable) after enabling the listener with
    `composition.hotkeys()`. The standard way to mute, tweak, and steer the form
    (`form_jump`/`form_next`) by hand during `play()`.
  - [Chapter 14](14-live-and-data)

* - **Harmonic rhythm**
  - How fast the chords change, measured in beats per chord. Set per progression
    span, reshaped with `.with_rhythm(...)`, or made to breathe with `between(low,
    high)` so each change waits a different number of beats.
  - [Chapter 7](07-progressions)

* - **Key / scale (mode)**
  - A **key** is the home note of the piece (a pitch class — `"C"`, `"F#"`,
    `"Bb"`); a **scale** (or **mode**) is the set of steps allowed away from it.
    Set on the `Composition(key=, scale=)`; the harmony engine requires a key.
  - [Chapter 5](05-pitch-and-scales)

* - **Layer**
  - Folding several small builder functions into one scheduled pattern on a
    single channel, with `composition.layer(fn1, fn2, ..., channel=, beats=)` —
    the inverse of a **mirror**. If any builder declares a `chord` parameter the
    merged pattern follows the harmony.
  - [Chapter 13](13-expression-hardware)

* - **Link (Ableton Link)**
  - Wireless tempo, beat-phase, and transport sync to other instruments on the
    LAN, joined with `composition.link(quantum)` (e.g. `quantum=4.0` = one 4/4
    bar). The network tempo is authoritative — `set_bpm()` proposes, `target_bpm()`
    is ignored — and `play()` enters on the next bar boundary. Needs the `link` extra.
  - [Chapter 14](14-live-and-data)

* - **Live coding / hot-swap**
  - Editing a piece while it plays. `composition.watch(path)` re-runs a watched
    file on every save and swaps the patterns in place on the next rebuild — the
    clock, cycle count, and seeded RNG keep running. `composition.live(port)` (a
    REPL) and `load_patterns(source)` (a string) are the lighter siblings.
  - [Chapter 14](14-live-and-data)

* - **Lock**
  - Pinning a named stream to its current seed and realization so it survives a
    `reroll` of everything around it. `composition.lock(name)`; released with
    `composition.unlock(name)`.
  - [Chapter 11](11-seeds-locks-freeze)

* - **Mirror**
  - A second `(device, channel)` destination a pattern's MIDI is *copied* to —
    notes, CCs, bends, all of it — for unison-stacking two synths or feeding a
    recorder. Declared with `mirrors=[(device, channel), ...]` on the decorator;
    toggled live with `composition.mirror(...)` / `unmirror(...)`.
  - [Chapter 13](13-expression-hardware)

* - **MelodicState**
  - A persistent, scored single-line melody generator. It holds key, register,
    and recent history, and on each query scores every candidate pitch (using the
    **Narmour** model) to choose a musical next note. Driven by `p.melody(state)`.
  - [Chapter 12](12-deep-generative)

* - **Mini-notation**
  - A compact string shorthand for rhythm (`"kick . snare ."`), kept for
    familiarity as `p.seq`. A single legacy aside — not the path this guide
    teaches; the Python-list standard form is the instrument.
  - [Chapter 3](03-notes-beats-durations)

* - **Motif**
  - The smallest unit of musical *material* — a four-note hook, a clave. An
    **immutable value** you build once and reuse; every transform returns a *new*
    motif rather than changing it. Placed with `p.motif(m)`.
  - [Chapter 8](08-motifs)

* - **Narmour (NIR)**
  - The Narmour Implication-Realization model — the cognitive theory of melodic
    expectation that Subsequence uses to *score* candidate pitches (in
    `MelodicState` and the chord engine), favouring lines that move the way a
    listener expects. Strength is tuned with `nir_strength`.
  - [Chapter 12](12-deep-generative)

* - **NRPN / RPN**
  - Multi-message MIDI parameter writes that reach beyond the 128 CC numbers.
    **NRPN** (Non-Registered) is vendor-specific (filter, envelope amounts);
    **RPN** (Registered) is the small standardised set (e.g. pitch-bend range).
    Sent with `p.nrpn(...)` / `p.rpn(...)`, swept with the `_ramp` forms.
  - [Chapter 13](13-expression-hardware)

* - **OSC (Open Sound Control)**
  - A networked, named-message protocol over UDP for control surfaces and
    Max/Pd patches. Enable a bidirectional server with
    `composition.osc(receive_port, send_port)` (custom handlers via `osc_map`);
    emit messages in time with `p.osc(...)` / `p.osc_ramp(...)`.
  - [Chapter 14](14-live-and-data)

* - **Open cadence**
  - See **Cadence** — the IV→V close that hangs on the dominant, a question
    rather than a full stop.
  - [Chapter 7](07-progressions)

* - **Pattern**
  - One repeating part — a drum loop, a bassline, a pad. Written as an ordinary
    Python function and registered with the `@composition.pattern(...)`
    decorator; the composition re-runs it once per cycle.
  - [Chapter 1](01-step-grid)

* - **Pattern builder (`p`)**
  - The single argument every pattern function receives — the musician's palette
    you paint notes, hits, and control gestures onto. Every `p.something(...)`
    method (and `p.cycle`, `p.bar`, `p.data`) lives here. A *fresh* canvas each
    cycle.
  - [Chapter 1](01-step-grid), [Chapter 2](02-rebuild-loop)

* - **Period**
  - A classical two-part phrase: the *antecedent* asks (open close) and the
    *consequent* answers (home close) using the same material. Built with
    `period(antecedent, ...)`.
  - [Chapter 9](09-phrases)

* - **Phrase**
  - A multi-bar musical sentence made of motifs, with its segmentation preserved
    — a value like a `Motif`. Grown from a motif by a development plan, or by the
    `sentence()` / `period()` builders; placed with `p.phrase(value)`.
  - [Chapter 9](09-phrases)

* - **Progression**
  - A frozen sequence of chords with durations — the governing harmony value.
    Built with `progression([...])`, inspected with `.describe()`, and shaped by
    voicing, cadence, harmonic-rhythm, and substitution transforms that each
    return a new value.
  - [Chapter 7](07-progressions)

* - **Rebuild loop**
  - The heart of Subsequence: your pattern function is **re-run from scratch
    before every cycle**, so each bar is freshly described and small algorithmic
    ideas can evolve over time rather than looping identically.
  - [Chapter 2](02-rebuild-loop)

* - **Render vs play**
  - The two ways to hear a piece. `composition.render(...)` runs the sequencer
    as fast as possible and writes a MIDI file — headless, instant, no hardware
    needed. `composition.play()` streams MIDI live off the wall clock to your
    instrument.
  - [Chapter 0](00-setup)

* - **Reroll**
  - Dealing a named stream a fresh deterministic seed to try a new variation,
    while everything you have **locked** stays put. `composition.reroll(name)`.
  - [Chapter 11](11-seeds-locks-freeze)

* - **Scale degree**
  - A note named by its *position in the key* (degree 1 = tonic, degree 5 =
    dominant) rather than by absolute pitch, so the same melody transposes to any
    key for free. Degrees feed `motif()`, `scale_notes(...)`, and the harmony
    layer.
  - [Chapter 5](05-pitch-and-scales)

* - **Section**
  - One named stretch of a **form** — a verse, a chorus — with a length in bars
    and its own energy (and optionally key/scale). Patterns read `p.section` to
    react to where they are. Harmony, motifs, and phrases can be *bound* to
    sections.
  - [Chapter 10](10-form-sections)

* - **Seed**
  - One number that makes every random choice in a piece repeatable: the same
    seed always gives the same piece. Set with `Composition(seed=...)`; internally
    it derives an independent named stream per consumer.
  - [Chapter 11](11-seeds-locks-freeze)

* - **Sentence**
  - A classical four-unit phrase: the basic idea stated twice (the
    *presentation*), then a continuation that drives to a closing **cadence**.
    Built with `sentence(idea, bars=..., cadence=...)`.
  - [Chapter 9](09-phrases)

* - **Signal**
  - A named time-varying value on the **Conductor** — an `lfo` or a `line` —
    read inside a pattern with `p.signal(name)` to scale a velocity, a CC, or a
    pitch. Sampled once per bar, for slow macro modulation.
  - [Chapter 12](12-deep-generative)

* - **Snap-to-scale**
  - Pulling already-placed notes onto the nearest pitch of a scale, so any pitch
    material lands in key. `p.snap_to_scale(key, mode)` — the pitch verb. It
    changes *which note*, never *when*; "quantize" is timing-only and is never
    used for pitch.
  - [Chapter 5](05-pitch-and-scales)

* - **Soft cadence**
  - See **Cadence** — the IV→I plagal "amen" close, gentler than V→I.
  - [Chapter 7](07-progressions)

* - **Strong cadence**
  - See **Cadence** — the V→I authentic full stop that lands home conclusively.
  - [Chapter 7](07-progressions)

* - **Substitution / decoration**
  - Progression transforms that reshape the harmony without rewriting it by hand:
    `.extend(...)` adds 7ths/9ths, `.borrow(...)` pulls a chord from the parallel
    scale, `.over(bass)` puts it over a pedal, `.elaborate(...)` approaches each
    chord by fifths. Each returns a new `Progression`.
  - [Chapter 7](07-progressions)

* - **SysEx**
  - A System Exclusive message — a raw vendor-specific byte string for things no
    standard MIDI message covers (patch dumps, deep config). Sent with
    `p.sysex(data)`.
  - [Chapter 13](13-expression-hardware)

* - **Tuning (microtonal)**
  - A non-12-TET temperament expressed as cent offsets from the unison — a
    `Tuning` value built with `Tuning.equal(n)`, `.from_ratios(...)`,
    `.from_cents(...)`, or `.from_scl(path)`. Applied piece-wide with
    `composition.tuning(...)` or per-part with `p.apply_tuning(...)`, realised by
    injecting a corrective pitch bend before each note.
  - [Chapter 13](13-expression-hardware)

* - **Tweak / `p.param`**
  - Live parameter override. Read a value in the pattern body with
    `p.param(name, default)` instead of hard-coding it, then change it while the
    music plays with `composition.tweak(name, value=...)`; cleared with
    `clear_tweak(...)`. The override persists across rebuilds until cleared.
  - [Chapter 14](14-live-and-data)

* - **Velocity**
  - How hard a note is struck, `1` (barely there) to `127` (full force) — a
    note's dynamic. Set as a single number, a `(low, high)` tuple for a per-note
    random draw, or reshaped across a pattern with `p.velocity_shape(...)`.
  - [Chapter 1](01-step-grid)

* - **Voice leading**
  - Letting Subsequence pick each chord's inversion so it moves the fewest notes
    from the last one — smooth connection without hand-choosing inversions.
    Turned on with `voice_leading=True` where the chords are *placed*.
  - [Chapter 7](07-progressions)

* - **Voicing**
  - *How* a chord is stacked: which tone is in the bass (`.inversions(...)`) and
    how widely it spreads (`.spread("close" / "open" / "wide")`). It changes the
    notes that sound without changing the chord's name.
  - [Chapter 7](07-progressions)
```

(sec-appE-touchstone)=
## E.2 One worked touchstone

Several entries above describe the same object from different angles — a
**Progression** carries chords, a **harmonic rhythm**, and (when you ask) a
**cadence**. Seen together on a four-chord loop, with a *strong* cadence rewriting
the tail to V→I (here `E Am` in A minor):

```{doctest} appE
>>> from subsequence import progression
>>> loop = progression(["Am", "F", "C", "G"])
>>> print(loop.cadence("strong").describe("A", "minor"))
Progression — 4 chords over 16 beats
    0.00 …   4.00   Am       (4 beats)
    4.00 …   8.00   F        (4 beats)
    8.00 …  12.00   E        (4 beats)
   12.00 …  16.00   Am       (4 beats)
```

```{tip}
If a term names a method or argument and you want the exact signature, jump to
[Appendix D](appendix-d-api-reference); if you want the verb's analytical cousins
(syncopation, contour, sieves), see [Appendix B](appendix-b-analysis-toolkit).
For the live-versus-file mechanics behind **render vs play**, see
[Appendix C](appendix-c-midi-routing).
```