Harmonic context defines the Rules (R) that constrain the generative space.

These filters are applied BEFORE database evaluation (R in R→E→T pipeline), limiting which cadences can even be considered as candidates.

Three-part filtering system: * overtones: Pitch candidate set (e.g., "E A D G" for bass tuning overtones) * key: Key filter applied to candidates (e.g., C, "#", "bb" for key signature) * roots: Root/bass candidate set (e.g., "E F# G" for valid root notes)

Filters use "*" as wildcard (match all). Format matches legacy Overtone.hs notation.

Constructor for HarmonicContext.

Arguments: * overtones: Pitch set filter ("E A D G", C, "*") * key: Key signature filter (C, "#", "bb", Am, "*") * roots: Root notes filter ("E F# G", "1#", "*")

Example: harmonicContext "*" "*" "*" -- No filtering (all candidates) harmonicContext "E A D G" C "*" -- Bass tuning, C major key harmonicContext "*" "#" "E G" -- G major key, E/G roots only

Default harmonic context for Tidal live coding: all wildcards (chromatic). Named hContext to avoid collision with TidalCycles' EventF.context field.

Use modifier functions to constrain the context:

ctx = invSkip 2
    $ consonant
    $ hcRoots "C E G"
    $ hcKey "0#"
    $ hcOvertones "E A D G"
    $ hContext

Direction of dissonance drift across a generated progression.

When applied to a HarmonicContext, the generation engine filters the candidate pool at each step so that only chords with equal or greater (Dissonant) or equal or lesser (Consonant) dissonance than the current chord are preferred. Free imposes no constraint (default).

Advisory, not hard: if the drift predicate would empty the pool at a step, the filter relaxes and that step proceeds unconstrained rather than reaching an absorbing state (applyDriftFilter in Builder.Core). Note the predicate is dissonanceScore — an evaluation function acting as a filter, the documented E-inside-R leak (see ARCHITECTURE §2).

Set overtone filter. Default: "*" (all pitches).

hcOvertones "E A D G" $ hContext — bass tuning overtones

Set key filter. Default: "*" (chromatic).

hcKey "0#" $ hContext — C major

Set roots/bass filter. Default: "*" (all roots).

hcRoots "C E G" $ hContext — only C, E, G as bass notes

Modify context to trend toward increasing dissonance. Each subsequent chord should have dissonance >= the current chord; advisory — relaxes at any step where it would empty the pool.

Modify context to trend toward decreasing dissonance. Each subsequent chord should have dissonance <= the current chord; advisory — relaxes at any step where it would empty the pool.

Set minimum number of non-inversion states between inversions.

invSkip 0 allows inversions at any step (default, current behaviour). invSkip 1 requires at least 1 non-inversion between inversions. invSkip 2 requires at least 2 non-inversions between inversions. The starting state counts toward the counter (a non-inversion start means the first generated step may already be an inversion with invSkip 1).

Advisory, not hard: if excluding inversions would empty the pool at a step, the spacing constraint relaxes for that step rather than halting generation.

Require specific pitch classes to be present in every generated chord.

Tokens are note names (C, G, Bb). A trailing ? marks a tone as preferred rather than required — it is applied when it does not reduce the candidate pool below a minimum viable size, and relaxed otherwise.

Advisory at the limit: the relaxation chain is preferred → required → unfiltered (applyPedalFilter in Builder.Core), so even required tones are dropped as a last resort at a step where enforcing them would leave no candidates — generation never reaches an absorbing state through a pedal constraint.

hcPedal C $ hContext — C must appear in every chord hcPedal "C G" $ hContext — C and G must both appear hcPedal "C G?" $ hContext — C required, G preferred

Restrict the active tristrata pool for genP.

"" (default) — all 12 tristrata allowed. "5" — lock to a single tristrata (here #5, IV-VI-X). "1 2 5" — whitelist multiple tristrata. "[1,2,5]" — bracket form accepted.

Parsed via parseTristrataList; unknown tokens are silently discarded.

Configuration for the progression generator.

gcQuad switches on the gen4 family: after each triad selection, the step fuses one R-valid palette tone into the chord (4-note output) and the walk continues from the fused chord's most-consonant embedded triad (see fuseState).

Historical note: the former gcPoolSize field was removed (2026-08-19) because no generation path ever read it — the candidate pool is deliberately unlimited (full 660-candidate fallback; see Core).

Default configuration.

Pre-parsed HarmonicContext for O(1) membership tests. Computed once per generation run, avoiding repeated text parsing.

Parse a HarmonicContext once into efficient lookup structures.

Enharmonic side implied by a key-signature string. A key filter may carry several tokens (their pitch sets union into the candidate pool), so the side is a per-token vote: every token flat-side -> flat, every token sharp-side -> sharp, mixed or indeterminate -> neutral (spelling falls back to content inference and continuity). Count forms carry their side directly ("2b" flat, "3#" sharp; zero-accidental forms are neutral); note-name forms follow the circle of fifths (F and every flat name -> flat; G, D, A, E, B and every sharp name -> sharp; C is ambiguous -> neutral). Removal tokens ("-G") shape the pool, not the spelling, and do not vote. Wildcards are neutral.

Concrete direction action resolved for a single generation step. When active, the bass/root at the next step is forced to the Nth note above (Rise) or below (Fall) in the allowed set, with mod-12 wrapping. Step size 1 = closest note, 2 = skip one, etc.

Parsed specification for a rise/fall direction token. Resolved per step at generation time to a concrete BassDirection (or Nothing when the optional ? flag causes the direction to be skipped for that step).

Whether a parsed direction rises or falls.

How to pick a step size from bdsChoices at each generation step.

Verbosity level for generation output.

Configuration for the modifier-based generation API.

Built via modifier chains:

s <- seek "*" $ cue start $ tonal ctx $ len 4 $ entropy 0.3 $ gen

Generation mode.

Transform trace captures intermediate values in fromCadenceState → toTriad pipeline. Used for maximum verbosity debugging (gen''). Includes raw DB data plus all transformation stages.

Advance trace captures intermediate values in root advancement. Used for maximum verbosity debugging (gen'').

Diagnostic information for a single generation step

Diagnostic record for one gen4 fusion (the added-tone draw that turns the selected triad into a 4-note chord).

Complete diagnostics for a generation run

Per-attempt diagnostic record for the multi-attempt rank-and-select (generateBest) loop. Captured once per attempt and surfaced at Verbose via printAttemptScoreboard. At Silent / Standard the list is discarded after the winner is picked.