@libraz/libcantus 0.9.4 → 1.0.0

package/dist/index-D57QRbVn.d.ts

@@ -0,0 +1,1804 @@
+import { d as KeyScale, g as NoteEvent, S as SpelledInterval } from './index-B9MNZboQ.js';
+import { d as ChordQuality, b as Chord, N as NoteSafety, S as SafetyProfile } from './index-szBv3496.js';
+import { r as ScaleName } from './masks-DYbE485J.js';
+import { i as KeyProfileName, j as KeyProfilePair, R as RejectedCandidate, k as KeyRegion, e as ChordTimeline, C as CadenceHit, a as AnalyzedNote, T as TheoryLabel, K as KeyContext, b as CadenceResult } from './index-Chbst3Jx.js';
+import { T as TimeSignature, c as MeterMap, b as MeterLike } from './index-Cj49F892.js';
+
+/**
+ * Church-mode candidates for {@link detectKey}.
+ *
+ * A mode is not a key with a different scale bolted on: it is the same tonal
+ * hierarchy — tonic strongest, dominant next, the remaining diatonic degrees
+ * behind them — heard over a scale in which one degree has been replaced. Its
+ * profile is therefore derived from the profile of the major or minor key it
+ * sits closest to, rather than being a table of its own.
+ */
+
+/**
+ * A church mode {@link detectKey} can rank alongside the major and minor keys.
+ *
+ * Ionian and Aeolian are absent because they are the major and the natural minor
+ * scale: a piece in either is already reported by the plain major or minor
+ * candidate, and adding a second candidate over the same pitch classes and the
+ * same profile would only produce a tie with itself.
+ *
+ * @category Recognition
+ */
+type ModalScaleName = 'dorian' | 'phrygian' | 'lydian' | 'mixolydian' | 'locrian';
+/**
+ * How a modal candidate is built out of its parallel major or minor key.
+ *
+ * @category Recognition
+ */
+type ModalCandidate = {
+    /** The name reported as {@link KeyMatch.scaleName} when this candidate wins. */
+    scaleName: ModalScaleName;
+    /** The major or minor key this mode is closest to, reported as `mode`. */
+    mode: 'major' | 'minor';
+    /** The 12-bit scale mask of the mode. */
+    mask: number;
+    /**
+     * Degree pairs the mode substitutes, as `[replaced, replacing]` semitone
+     * offsets above the tonic. Applying them to the parallel scale yields `mask`,
+     * and applying them to the parallel profile yields this candidate's profile.
+     */
+    substitutions: readonly (readonly [number, number])[];
+};
+/**
+ * Every mode {@link DetectKeyOptions.modes} accepts, in candidate order.
+ *
+ * @category Recognition
+ */
+declare const MODAL_SCALE_NAMES: readonly ModalScaleName[];
+
+/**
+ * Recognition: infer a chord name from a set of pitches, or a key from a set of
+ * pitch classes. This is the inverse direction of the chord/scale builders,
+ * which only go name -> notes.
+ */
+
+/**
+ * A candidate chord interpretation of a pitch set.
+ *
+ * @category Recognition
+ */
+type ChordMatch = {
+    rootPc: number;
+    quality: ChordQuality;
+    /** Chord tones absent from the input (an incomplete voicing). */
+    missingPcs: number[];
+    /** Input pitch classes not belonging to the chord. */
+    extraPcs: number[];
+    /** True when the input pitch-class set equals the chord exactly. */
+    exact: boolean;
+    /**
+     * Inversion implied by a known bass: 0 for root position, 1..n for an
+     * inversion. Null when no inversion can be named — either the input is an
+     * unordered pitch-class set with no bass, or the bass is not a chord tone (a
+     * pedal or passing bass), in which case `bassPc` still reports it.
+     */
+    inversion: number | null;
+    /** Bass pitch class when the lowest note is not the root. */
+    bassPc?: number;
+};
+/**
+ * Input interpretation for {@link detectChord} and {@link detectChordBest}.
+ *
+ * @category Recognition
+ */
+type DetectChordOptions = {
+    /**
+     * `midi` uses the numerically lowest pitch as bass; `pitchClass` treats the
+     * input as unordered. `auto` (default) selects pitch-class mode only when all
+     * values lie in 0..11.
+     */
+    input?: 'auto' | 'midi' | 'pitchClass';
+    /** Explicit bass pitch class, including for an unordered pitch-class set. */
+    bassPc?: number;
+};
+/**
+ * A candidate key interpretation of a pitch-class set.
+ *
+ * @category Recognition
+ */
+type KeyMatch = {
+    /** The scale that scored best for this tonic and mode, `variant` included. */
+    key: KeyScale;
+    /**
+     * The major or minor key this match is closest to. A modal match reports the
+     * mode it leans on — dorian, phrygian and locrian are minor, lydian and
+     * mixolydian major — so a caller that reads nothing but `mode` still gets a
+     * musically sane answer; `scaleName` is where the mode itself is named.
+     */
+    mode: 'major' | 'minor';
+    /**
+     * Which scale form `key` uses. Minor keys report whichever of the natural,
+     * harmonic and melodic masks covers the most input weight; the variant does
+     * not take part in ranking. A church mode reports `'modal'`, since its scale
+     * is neither of the major nor one of the three minor forms.
+     */
+    variant: KeyVariant;
+    /**
+     * The entry of `NAMED_SCALES` whose mask is `key.modeMask12`, naming the scale
+     * exactly where `mode` and `variant` only place it: `'major'`,
+     * `'naturalMinor'`, `'harmonicMinor'`, `'melodicMinor'`, or one of the church
+     * modes when {@link DetectKeyOptions.modes} put them in the running. Ionian
+     * and Aeolian are reported as `'major'` and `'naturalMinor'`, the names of the
+     * candidates they are the same scale as.
+     */
+    scaleName: ScaleName;
+    /**
+     * Fraction of the distinct input pitch classes that belong to `key`, in
+     * [0, 1]. Measured against the returned scale, so it always agrees with
+     * `isScaleTone(pc, match.key)`. This is a coverage figure, not the ranking:
+     * see `score`.
+     */
+    fit: number;
+    /**
+     * The value the results are ranked by, in [-1, 1]: the Pearson correlation
+     * between the weighted pitch-class distribution of the input and this
+     * candidate's key profile rotated onto its tonic. 1 is a distribution shaped
+     * exactly like the profile, 0 no relationship, negative an anti-correlation.
+     * Unlike `fit` it is a distribution measure, not a membership count, so where
+     * the weight falls among the scale degrees is what separates a key from its
+     * relative. Always a finite number; see {@link DetectKeyOptions.profile} for
+     * the degenerate case.
+     */
+    score: number;
+    /**
+     * Why this candidate scored what it did, in the phrasing
+     * {@link analyzeVoice} uses for a note.
+     *
+     * Present only when {@link DetectKeyOptions.explain} asked for it: a ranking
+     * is 24 candidates before the modes are counted, and most callers read the
+     * first one or two.
+     */
+    rationale?: string;
+    /**
+     * The candidates that were considered and rejected, and why each ranked
+     * below this one.
+     *
+     * Carried by the top-ranked match alone — the rivals of a runner-up are the
+     * rest of the list, which the caller already holds — and only when
+     * {@link DetectKeyOptions.explain} asked for it.
+     */
+    alternatives?: RejectedCandidate[];
+};
+/**
+ * Which form of a scale a {@link KeyMatch} settled on.
+ *
+ * @category Recognition
+ */
+type KeyVariant = 'major' | 'natural' | 'harmonic' | 'melodic' | 'modal';
+/**
+ * Input weighting for {@link detectKey}.
+ *
+ * @category Recognition
+ */
+type DetectKeyOptions = {
+    /**
+     * How much each pitch counts toward the histogram, one entry per pitch.
+     * Defaults to one per pitch, which weighs a thirty-second-note ornament as
+     * heavily as the whole note under it. {@link detectKeyFromNotes} supplies
+     * duration times velocity, matching how chord inference weighs its own
+     * histogram.
+     */
+    weights?: readonly number[];
+    /**
+     * Which key profile ranks the candidates: the 12 degree weights a key is
+     * expected to distribute its music over, correlated against the distribution
+     * actually observed.
+     *
+     * `'krumhansl'` (the default) uses the Krumhansl–Kessler probe-tone ratings,
+     * `'temperley'` the Kostka–Payne corpus proportions, and `'flat'` a flat
+     * profile over the scale, which reduces the ranking to plain scale membership
+     * — the behaviour this detector had before profile correlation, kept as a way
+     * back for a caller that depends on it. A custom pair supplies two 12-entry
+     * vectors indexed from the tonic (index 0 = tonic, 1 = flat second, and so on
+     * to 11 = major seventh).
+     *
+     * When either the distribution or the rotated profile has zero variance the
+     * correlation is undefined; such a candidate is scored by the normalized dot
+     * product (cosine similarity) of the same two vectors instead, so a result
+     * never carries NaN.
+     *
+     * @defaultValue `'krumhansl'`
+     */
+    profile?: KeyProfileName | KeyProfilePair;
+    /**
+     * Whether the church modes join the 24 major and minor keys as candidates.
+     *
+     * Off by default, because a modal candidate can only change a ranking by
+     * outranking something: a caller working in common-practice repertoire, where
+     * a raised sixth over a minor tonic is a melodic-minor inflection rather than
+     * a dorian tonality, should keep reading the answer it reads today. Turn it on
+     * (`true` for all five, or a list to name the modes a repertoire actually
+     * uses) and each enabled mode adds one candidate per tonic, ranked on a
+     * profile derived from its parallel major or minor key.
+     *
+     * Ionian and Aeolian are not on the list: they are the major and natural minor
+     * candidates, which already carry `scaleName` `'major'` and `'naturalMinor'`.
+     *
+     * @defaultValue `false`
+     */
+    modes?: boolean | readonly ModalScaleName[];
+    /**
+     * Attach a {@link KeyMatch.rationale} to every candidate, and
+     * {@link KeyMatch.alternatives} to the top-ranked one.
+     *
+     * Off by default, and the one explanation in the library that is: the other
+     * entry points explain a single reading, while a ranking explains 24 of them
+     * (36 or more with the modes on), each needing a phrase built for a candidate
+     * nobody asked about. That cost outweighs the detection itself, so it is paid
+     * only on request.
+     *
+     * @defaultValue false
+     */
+    explain?: boolean;
+    /**
+     * Upper bound on the input pitches processed by this detection call.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * Identify chords matching a set of pitches.
+ *
+ * Every input pitch class is tried as a root against every known chord quality.
+ * A match is reported when all of the chord's tones are present in the input, or
+ * when the only absent tone is the perfect fifth (a common omission in shell
+ * voicings); matches are ranked best-first by fewest extra notes, then fewest
+ * missing notes, then most specific (largest) chord. An exact match (no extras,
+ * no missing) is flagged and ranked first.
+ *
+ * @param pitches MIDI pitches or bare pitch classes (octave-agnostic).
+ * @returns Ranked chord interpretations (may be empty).
+ * @example
+ * ```ts
+ * import { detectChord } from '@libraz/libcantus';
+ * const matches = detectChord([60, 64, 67]); // C E G
+ * matches[0]; // { rootPc: 0, quality: 'maj', exact: true, ... }
+ * ```
+ * @category Recognition
+ */
+declare function detectChord(pitches: readonly number[], opts?: DetectChordOptions): ChordMatch[];
+/**
+ * The single best chord interpretation of a pitch set, or null if none.
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @returns The top-ranked chord, or null when nothing matches.
+ * @example
+ * ```ts
+ * import { detectChordBest } from '@libraz/libcantus';
+ * detectChordBest([60, 64, 67]); // C major triad: { rootPc: 0, quality: 'maj', ... }
+ * ```
+ * @category Recognition
+ */
+declare function detectChordBest(pitches: readonly number[], opts?: DetectChordOptions): Chord | null;
+/**
+ * Rank major and minor keys by how well a set of pitch classes is distributed
+ * like each key.
+ *
+ * The input becomes a weighted pitch-class distribution, and every one of the
+ * 24 candidates is scored by the Pearson correlation between that distribution
+ * and its key profile rotated onto the candidate tonic (see
+ * {@link DetectKeyOptions.profile}). Correlating against a profile rather than
+ * counting scale members is what tells a key apart from its relative: C major
+ * and A minor contain the same seven pitch classes, so a membership count can
+ * only separate them by a tie-break, while their profiles expect the weight on
+ * different degrees.
+ *
+ * Choosing the minor variant is deliberately not part of the ranking. A minor
+ * candidate is ranked once, on the minor profile, which already expects some
+ * weight on the raised sixth and seventh; only then does it report whichever of
+ * the natural, harmonic and melodic masks covers the most input weight, and
+ * `fit` is measured against that mask. That split is why a harmonic-minor
+ * cadence ranks its own tonic first without the harmonic variant having to win
+ * a scoring contest against the natural one.
+ *
+ * {@link DetectKeyOptions.modes} adds the church modes to the same contest, one
+ * candidate per mode per tonic, each ranked on a profile derived from its
+ * parallel major or minor key. A modal winner reports the mode in `scaleName`
+ * and still reports the key it leans on in `mode`. The option is off by default,
+ * so a caller that does not ask for modes gets the ranking of the 24 keys it has
+ * always got.
+ *
+ * Ties are broken by `fit` descending, then tonic pitch class ascending, then by
+ * scale — major, the minor forms, then the modes — so the order is fully
+ * determined by the input rather than by the order candidates happen to be built
+ * in. Returns all 24 keys ranked best-first, plus 12 more per enabled mode, or
+ * an empty array for an empty input (mirroring {@link detectChord}).
+ *
+ * {@link DetectKeyOptions.explain} adds a `rationale` to every candidate and,
+ * to the winner, the runners-up it beat with the link of that tie-break chain
+ * that separated each. It is off by default; see the option for why.
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @param opts How to weigh the input, which profile to rank with, and whether
+ *   the modes take part; see {@link DetectKeyOptions}.
+ * @returns Ranked key interpretations (empty for an empty input), each carrying
+ *   a finite `score` in [-1, 1].
+ * @throws {InvalidInputError} When `weights` does not have one entry per pitch,
+ *   `profile` is not a known name or a valid pair of 12-entry vectors, or
+ *   `modes` names something that is not a church mode.
+ * @throws {RangeError} When a pitch is outside the MIDI domain or the input
+ *   exceeds the budget.
+ * @example
+ * ```ts
+ * import { detectKey } from '@libraz/libcantus';
+ * const keys = detectKey([60, 62, 64, 65, 67, 69, 71]); // C major scale
+ * keys[0].mode; // 'major', with keys[0].key.rootPc === 0
+ * keys[1].mode; // 'minor' on 9: A minor, the relative, ranked just below
+ * const riff = detectKey([62, 62, 65, 69, 71, 69, 65, 62], { modes: true });
+ * riff[0].scaleName; // 'dorian', on rootPc 2, still reported as mode 'minor'
+ * ```
+ * @category Recognition
+ */
+declare function detectKey(pitches: readonly number[], opts?: DetectKeyOptions): KeyMatch[];
+/**
+ * Rank keys by how well they contain a set of note events, weighting each note
+ * by how much of the music it actually occupies.
+ *
+ * {@link detectKey} counts every pitch once, which lets a run of fast ornamental
+ * notes outvote the sustained harmony that establishes the key. This weighs
+ * each note by duration times velocity, the same measure chord inference uses,
+ * so the two agree on what the music emphasises. Notes that never sound (zero
+ * or negative duration) are ignored. The weighted distribution is then ranked
+ * exactly as {@link detectKey} ranks it, by correlation against a key profile,
+ * so `score` is a finite correlation in [-1, 1].
+ *
+ * @param notes The note events to weigh.
+ * @param opts Which profile to rank with, whether the modes take part, and the
+ *   budget for processing imported note events; the weights are derived from the
+ *   notes themselves.
+ * @returns Ranked key interpretations (empty when nothing sounds).
+ * @throws {InvalidInputError} When `profile` is not a known name or a valid
+ *   pair of 12-entry vectors, or `modes` names something that is not a church
+ *   mode.
+ * @throws {RangeError} When a note event is malformed or the input exceeds the
+ *   budget.
+ * @example
+ * ```ts
+ * import { detectKeyFromNotes } from '@libraz/libcantus';
+ * detectKeyFromNotes([{ pitch: 60, startBeat: 0, durationBeat: 4 }])[0]?.key.rootPc; // 0
+ * ```
+ * @category Recognition
+ */
+declare function detectKeyFromNotes(notes: readonly NoteEvent[], opts?: Omit<DetectKeyOptions, 'weights'>): KeyMatch[];
+/**
+ * The single best key interpretation of a pitch set.
+ *
+ * The counterpart of {@link detectChordBest}: the ranked list is the general
+ * answer, but a caller that just wants "what key is this" should not have to
+ * index into it and assert the result is there. The winner is the candidate
+ * whose key profile correlates best with the input distribution, with the same
+ * deterministic tie-break {@link detectKey} applies, so its `score` is a finite
+ * correlation in [-1, 1] rather than a membership share.
+ *
+ * This is where {@link DetectKeyOptions.explain} earns its keep: the winner is
+ * the only match a caller of this function sees, and with `explain` it carries
+ * both its own rationale and the candidates it beat.
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @param opts How to weigh the input, which profile to rank with, and whether
+ *   the modes take part; see {@link DetectKeyOptions}.
+ * @returns The top-ranked key, or null when nothing sounds.
+ * @throws {InvalidInputError} When `weights` does not have one entry per pitch,
+ *   `profile` is not a known name or a valid pair of 12-entry vectors, or
+ *   `modes` names something that is not a church mode.
+ * @throws {RangeError} When a pitch is outside the MIDI domain or the input
+ *   exceeds the budget.
+ * @example
+ * ```ts
+ * import { detectKeyBest } from '@libraz/libcantus';
+ * detectKeyBest([0, 2, 4, 5, 7, 9, 11])?.mode; // 'major'
+ * ```
+ * @category Recognition
+ */
+declare function detectKeyBest(pitches: readonly number[], opts?: DetectKeyOptions): KeyMatch | null;
+
+/**
+ * Arrangement track-role analysis: a single harmony is inferred from every
+ * track's notes pooled together, each track is then analysed against that shared
+ * harmony, and notes that clash with the sounding chord are collected as
+ * conflicts.
+ */
+
+/**
+ * The musical role a track plays in the arrangement.
+ *
+ * Only `drums` changes the analysis: its pitches select instruments rather than
+ * naming harmony, so such a track is excluded from chord and key inference and
+ * from every voice-leading comparison, and is reported back with no
+ * annotations. `harmony` is meaningful through
+ * {@link ArrangementOptions.harmonyTracks}, which names the tracks the chords
+ * are inferred from. The rest are labels carried through to
+ * {@link TrackAnalysis.role} for the caller's own use; nothing is inferred, so
+ * a track left unlabelled reports `'other'` rather than a guess.
+ *
+ * @category Arrangement & Analysis
+ */
+type TrackRole = 'melody' | 'harmony' | 'bass' | 'drums' | 'other';
+/**
+ * One input track: its notes plus optional name and role.
+ *
+ * @category Arrangement & Analysis
+ */
+type ArrangementTrack = {
+    name?: string;
+    role?: TrackRole;
+    notes: readonly NoteEvent[];
+};
+/**
+ * A track after analysis: its resolved name, role, and per-note annotations.
+ *
+ * @category Arrangement & Analysis
+ */
+type TrackAnalysis = {
+    name: string;
+    role: TrackRole;
+    /** One {@link AnalyzedNote} per note, labelled against the inferred chords. */
+    notes: AnalyzedNote[];
+};
+/**
+ * A note that clashes with the harmony sounding beneath it.
+ *
+ * @category Arrangement & Analysis
+ */
+type Conflict = {
+    beat: number;
+    trackName: string;
+    /** The clashing track's index in the caller's input array. */
+    trackIndex: number;
+    /** The note's index in that track's own note array. */
+    originalIndex?: number;
+    /** The id the note carries in {@link TrackAnalysis.notes}. */
+    noteId: number;
+    pitch: number;
+    /**
+     * The note's theory labels at its onset, so a caller can tell a genuine clash
+     * from a passing tone, a neighbour, or a prepared suspension — all of which
+     * are ordinary non-chord tones that still evaluate as unsafe.
+     */
+    labels: TheoryLabel[];
+    /** The clash severity: {@link NoteSafety.Warning} or {@link NoteSafety.Dissonant}. */
+    safety: NoteSafety;
+    /** {@link SafetyResult.reasons} bitmask. */
+    reasons: number;
+    /** Preferred stepwise resolution, when the safety evaluator provides one. */
+    resolveTo?: number;
+    /** Nearby fully safe replacement pitches, nearest first. */
+    suggestions?: number[];
+    rationale?: string;
+};
+/**
+ * The full result of {@link analyzeArrangement}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ArrangementAnalysis = {
+    /**
+     * The key regions the analysis ran against, in time order. Roman numerals,
+     * harmonic function and note safety are all judged against the region
+     * covering the beat, so a piece that modulates is not read against the key it
+     * started in for every bar after it leaves.
+     */
+    keys: KeyRegion[];
+    /** The key held longest across {@link ArrangementAnalysis.keys}. */
+    prevailingKey: KeyScale;
+    timeline: ChordTimeline;
+    segmentConfidence: number[];
+    cadences: CadenceHit[];
+    tracks: TrackAnalysis[];
+    /** Notes clashing with the sounding harmony, worst severity first. */
+    conflicts: Conflict[];
+};
+/**
+ * Options controlling {@link analyzeArrangement} and {@link tensionCurve}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ArrangementOptions = {
+    /**
+     * A single key held across the whole arrangement. Omit it, and `keys` with
+     * it, to have the key searched for over time so a modulating piece is read
+     * against the key actually in force.
+     */
+    key?: KeyScale;
+    /**
+     * Key regions to judge against, when a previous pass already worked them out.
+     * Takes precedence over `key`; supplying both is answering the same question
+     * twice, and the more specific answer wins.
+     */
+    keys?: KeyRegion[];
+    /**
+     * A chord timeline to analyse against, instead of inferring one from the
+     * notes. Supply it to analyse a hand-written progression, or to reuse the
+     * timeline of an earlier call rather than re-running chord inference.
+     */
+    timeline?: ChordTimeline;
+    /**
+     * Indices of the tracks the harmony is inferred from. Defaults to every
+     * pitched track. Percussion tracks are excluded either way. An index naming
+     * no track is an input error rather than one that matches nothing.
+     */
+    harmonyTracks?: number[];
+    /**
+     * Lowest severity reported in `conflicts`.
+     *
+     * @defaultValue {@link NoteSafety.Warning}
+     */
+    minSeverity?: NoteSafety;
+    /**
+     * A single time signature held across the whole arrangement, as sugar for a
+     * one-element `meters`; defaults to 4/4. Giving both is an input error.
+     *
+     * @defaultValue `4/4`
+     */
+    ts?: TimeSignature;
+    /**
+     * The meter as it changes over the arrangement. Bar lines, downbeats and
+     * metric weight all follow the signature in force at the beat in question.
+     *
+     * @defaultValue 4/4 throughout
+     */
+    meters?: MeterMap;
+    /**
+     * Length of the pickup in beats, when the piece starts with one.
+     *
+     * The first downbeat is beat 0, so an upbeat is written at negative beats.
+     * Declaring its length rejects a note that starts before the pickup does;
+     * leave it unset to accept any finite onset.
+     *
+     * @defaultValue no declared pickup
+     */
+    pickupBeats?: number;
+    /**
+     * Chord-slot length in beats; defaults to the length of the opening bar.
+     *
+     * @defaultValue the length of the opening bar
+     */
+    harmonicRhythm?: number;
+    /**
+     * Safety profile used for conflict detection; defaults to `pop`.
+     *
+     * @defaultValue `'pop'`
+     */
+    profile?: SafetyProfile;
+    /**
+     * Upper bound on the work this call may do — note counts, windows, and
+     * candidate counts are each checked against it before anything is allocated.
+     *
+     * Raise it to analyse a piece larger than the default allows; the default is
+     * {@link DEFAULT_GENERATION_BUDGET}, chosen so a runaway input fails fast
+     * rather than blocking the thread.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * Analyse a whole arrangement against the harmony inferred from it.
+ *
+ * The chord timeline and the key regions it is read against are inferred from
+ * the pooled notes of every pitched track (see
+ * {@link chordTimelineFromNotes}); pooling all voices is
+ * robust even when roles are absent or a track doubles the harmony, so it is
+ * preferred over deriving the harmony from a subset. A track marked
+ * `role: 'drums'` is excluded — its pitches name instruments, not harmony, and
+ * pooling them would corrupt the key, the timeline and every reading built on
+ * them. Pass `harmonyTracks` to restrict inference further, or `timeline` to
+ * analyse against a progression you already have. Zero- and negative-length
+ * notes never sound, so they are dropped at ingest and appear in neither the
+ * annotations nor the conflicts.
+ *
+ * Voice analysis assumes one monophonic voice at a time, so each track is
+ * first partitioned into monophonic sub-voices (a polyphonic block-chord track
+ * fans out into one sub-voice per simultaneous note; a monophonic track is
+ * unaffected). Each sub-voice is labelled note-by-note against the harmony
+ * with {@link analyzeVoice}, seeing every other sub-voice — including siblings
+ * within the same track — as its accompaniment. Every note is then re-checked
+ * with {@link evaluateSafety} at its onset and again at each chord change it
+ * sustains across, so a held note that clashes with a later chord is caught:
+ * evaluations that are not {@link NoteSafety.Safe} become conflicts, one per
+ * clashing beat, sorted worst severity first and then by beat.
+ *
+ * Every ordinary non-chord tone — a passing note, a neighbour, a prepared
+ * suspension — is by definition unsafe against the chord under it, so the
+ * conflict list is a report, not a fault list. Each conflict carries the note's
+ * `labels` and its `trackIndex`/`originalIndex`, so a caller can tell those
+ * apart and map a conflict back to the note it passed in; `minSeverity` narrows
+ * the list to outright dissonance.
+ *
+ * @param tracks The tracks to analyse.
+ * @param opts Analysis options; see {@link ArrangementOptions}.
+ * @returns The inferred harmony, per-track annotations, cadences, and conflicts.
+ * @example
+ * ```ts
+ * import { analyzeArrangement } from '@libraz/libcantus';
+ * const melody = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 2 },
+ *   { pitch: 67, startBeat: 2, durationBeat: 2 },
+ * ];
+ * const { prevailingKey, conflicts } = analyzeArrangement([{ role: 'melody', notes: melody }]);
+ * prevailingKey.rootPc; // the key held longest across the analysis
+ * conflicts; // notes clashing with the inferred harmony, worst severity first
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function analyzeArrangement(tracks: ArrangementTrack[], opts?: ArrangementOptions): ArrangementAnalysis;
+
+/**
+ * Incremental arrangement analysis: an analysis held open across edits, so a
+ * host that re-analyses on every keystroke pays for the beats that changed
+ * rather than for the whole piece.
+ */
+
+/**
+ * One track's notes as they stand after an edit.
+ *
+ * The whole note array is given rather than a description of what moved: a host
+ * always has the track's current contents, and working out what actually
+ * changed is this module's job, not the caller's.
+ *
+ * @category Arrangement & Analysis
+ */
+type TrackEdit = {
+    /** Index of the track in the session's track array. */
+    trackIndex: number;
+    /** The track's notes after the edit. */
+    notes: readonly NoteEvent[];
+};
+/**
+ * An arrangement analysis held open for editing.
+ *
+ * @category Arrangement & Analysis
+ */
+type ArrangementSession = {
+    /** The tracks the current analysis was made from. */
+    readonly tracks: readonly ArrangementTrack[];
+    /** The analysis of those tracks. */
+    readonly analysis: ArrangementAnalysis;
+    /**
+     * Re-analyse after replacing the notes of one or more tracks, reusing
+     * everything the edit provably cannot reach.
+     *
+     * The result equals {@link analyzeArrangement} over the edited tracks — the
+     * same segments, confidences, key regions, cadences, annotations and
+     * conflicts — so a host may hold a session for as long as it likes without
+     * the analysis drifting from what a fresh pass would say.
+     */
+    update: (edits: readonly TrackEdit[]) => ArrangementSession;
+};
+/**
+ * Open an arrangement analysis that can be updated a few beats at a time.
+ *
+ * The first pass is an ordinary {@link analyzeArrangement}; what the session
+ * adds is the slot-level evidence behind it, so a later {@link
+ * ArrangementSession.update} can work out which beats an edit could possibly
+ * have changed and leave the rest of the harmony alone. An update returns a new
+ * session, so the analysis before an edit stays valid and a host can keep it
+ * for undo.
+ *
+ * What an update recomputes is derived rather than guessed at:
+ *
+ * - The edited beats are the beats covered by the notes the old and new track
+ *   arrays disagree on, which is narrower than the track and usually far
+ *   narrower than the piece.
+ * - A slot's evidence sees exactly the notes overlapping it, so the slots to
+ *   re-derive are the slots overlapping those beats — plus one either side, so
+ *   that an onset sitting a floating-point hair off a slot boundary cannot
+ *   leave a stale slot behind.
+ * - The boundary search itself has no such margin. It is a shortest-path search
+ *   over a whole run of slots, so a changed slot can move a boundary anywhere in
+ *   the run, and its change cost is calibrated on the mean weight of every
+ *   sounding slot in the piece, which couples the runs to one another. The
+ *   search is therefore re-run over the whole piece — arithmetic over the
+ *   carried-over evidence, with nothing allocated per slot — rather than being
+ *   spliced at a margin that does not exist.
+ * - Each settled segment's chord is carried over when its bounds, its key and
+ *   its slots are all unchanged, since those are the only things chord
+ *   inference reads.
+ *
+ * Key regions and the per-note annotations are recomputed in full. Both are
+ * whole-piece passes — the key search is a shortest-path search with no reset
+ * points, sub-voice lane assignment is greedy from the first note, and every
+ * note is judged against the other voices sounding beneath it — so neither has
+ * a sound local answer, and reporting one would mean an update that quietly
+ * disagreed with a fresh analysis.
+ *
+ * An update falls back to a full analysis whenever the edit moves the ground the
+ * evidence stands on: a changed piece length, a changed first onset (both of
+ * which move the slot grid), or an edit to a session whose harmony was supplied
+ * through {@link ArrangementOptions.timeline}. The answer is the same either
+ * way; only the work differs.
+ *
+ * @param tracks The tracks to analyse.
+ * @param opts Analysis options; see {@link ArrangementOptions}.
+ * @returns A session holding the analysis and the evidence behind it.
+ * @example
+ * ```ts
+ * import { createArrangementSession } from '@libraz/libcantus';
+ * const melody = [{ pitch: 60, startBeat: 0, durationBeat: 4 }];
+ * const session = createArrangementSession([{ role: 'melody', notes: melody }]);
+ * const moved = [{ pitch: 62, startBeat: 0, durationBeat: 4 }];
+ * const next = session.update([{ trackIndex: 0, notes: moved }]);
+ * next.analysis.timeline.segments; // as if analyzed from scratch
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function createArrangementSession(tracks: ArrangementTrack[], opts?: ArrangementOptions): ArrangementSession;
+
+/**
+ * Arrangement tension analysis: a coarse harmonic-tension curve sampled at
+ * regular beats across a whole multi-track piece, combining the sounding
+ * chord's harmonic function, the dissonance of the sounding notes, and their
+ * registral span into a single normalized reading.
+ */
+
+/**
+ * A tension reading sampled at a beat.
+ *
+ * @category Arrangement & Analysis
+ */
+type TensionPoint = {
+    beat: number;
+    /** Combined tension in [0, 1]. */
+    tension: number;
+};
+/**
+ * Sample the harmonic tension of an arrangement at regular beats.
+ *
+ * At each sample beat the tension combines three normalized terms:
+ *  - the sounding chord's harmonic function (dominant `1`, subdominant `0.5`,
+ *    tonic or no chord `0`), weighted `FUNCTION_WEIGHT`;
+ *  - the dissonance of the sounding notes — the larger of the share of sounding
+ *    pitches that are not chord tones and the share that {@link evaluateSafety}
+ *    rates {@link NoteSafety.Dissonant} — weighted `DISSONANCE_WEIGHT`;
+ *  - the registral span of the sounding notes, saturating at
+ *    `SPAN_SATURATION` semitones, weighted `SPAN_WEIGHT`.
+ *
+ * The weighted sum is clamped to [0, 1]. The harmony is inferred from all tracks
+ * pooled together, so the result is deterministic and self-contained.
+ *
+ * @param tracks The tracks to sample.
+ * @param opts Analysis options plus an optional `step` (default one beat).
+ * @returns One {@link TensionPoint} per sampled beat, in beat order.
+ * @throws If `step` is not positive.
+ * @example
+ * ```ts
+ * import { tensionCurve } from '@libraz/libcantus';
+ * const notes = [{ pitch: 60, startBeat: 0, durationBeat: 4 }];
+ * const curve = tensionCurve([{ notes }], { step: 1 });
+ * curve; // one { beat, tension } sample per beat, in beat order
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function tensionCurve(tracks: ArrangementTrack[], opts?: ArrangementOptions & {
+    step?: number;
+}): TensionPoint[];
+/**
+ * Sample the tension of an arrangement already analysed by
+ * {@link analyzeArrangement}, reusing its harmony instead of inferring it again.
+ *
+ * `analyzeArrangement` followed by `tensionCurve` runs chord and key inference
+ * twice over the same notes. This takes the analysis it already produced, so
+ * the curve and the annotations describe the same harmony by construction.
+ *
+ * @param tracks The same tracks that were analysed.
+ * @param analysis The result of {@link analyzeArrangement} for those tracks.
+ * @param opts Analysis options plus an optional `step` (default one beat).
+ * @returns One {@link TensionPoint} per sampled beat, in beat order.
+ * @example
+ * ```ts
+ * import { analyzeArrangement, tensionCurveFrom } from '@libraz/libcantus';
+ * const tracks = [{ notes: [{ pitch: 60, startBeat: 0, durationBeat: 4 }] }];
+ * const analysis = analyzeArrangement(tracks);
+ * tensionCurveFrom(tracks, analysis, { step: 1 });
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function tensionCurveFrom(tracks: ArrangementTrack[], analysis: ArrangementAnalysis, opts?: ArrangementOptions & {
+    step?: number;
+}): TensionPoint[];
+
+/**
+ * Hypermeter: the grouping of bars into hyperbars.
+ *
+ * Bars are felt in groups the way beats are felt in bars — four bars at a time
+ * in most tonal and popular music, but two, three, six or eight elsewhere. The
+ * grouping is not written in the score, so it has to be inferred from where the
+ * music actually restarts: harmony changes on a hypermetric downbeat, and
+ * cadences arrive at the end of a hyperbar.
+ */
+
+/**
+ * A bar grouping inferred from the music.
+ *
+ * @category Arrangement & Analysis
+ */
+type Hypermeter = {
+    /**
+     * Bars per hyperbar. Falls back to the span's own bar count when the span is
+     * too short to hold two of any candidate grouping.
+     */
+    groupBars: number;
+    /**
+     * Absolute beat of each hypermetric downbeat inside the analysed span, in
+     * time order. A pickup bar is not a group head, so the first entry is the
+     * first full bar that starts a group.
+     */
+    downbeats: number[];
+    /**
+     * How much the music supports the grouping, in [0, 1]: how strongly harmonic
+     * change and cadences prefer these bars over the others, discounted when the
+     * runner-up grouping explains the music nearly as well.
+     */
+    confidence: number;
+    /** Why this grouping was chosen. */
+    rationale: string;
+};
+/**
+ * Options for {@link hypermeter}.
+ *
+ * @category Arrangement & Analysis
+ */
+type HypermeterOptions = {
+    /**
+     * End of the analysed span in beats; defaults to the end of the last note.
+     *
+     * @defaultValue the end of the last note
+     */
+    totalBeats?: number;
+    /**
+     * Beats at which cadences arrive, as {@link CadenceHit.atBeat} reports them.
+     *
+     * A cadence is the clearest hypermetric evidence there is — it arrives at the
+     * end of a hyperbar — but finding one needs a chord timeline and a key, which
+     * this function is not given. Callers that already hold cadences should pass
+     * them; {@link phrasesFromTimeline} does.
+     *
+     * @defaultValue none
+     */
+    cadenceBeats?: readonly number[];
+    /**
+     * Upper bound on the work this call may do.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * Infer how a piece's bars group into hyperbars.
+ *
+ * Groupings of 2, 3, 4, 6, and 8 bars are tried at every phase, and each
+ * reading is scored on two counts: how much more harmonic change lands on the
+ * bars it calls group heads than on the bars between them, and how many of the
+ * cadences it is given arrive where it says a hyperbar ends. The commonest
+ * groupings are believed a little more readily than the rare ones, which
+ * settles ties without letting a prior overrule the music.
+ *
+ * The meter is read at the beat in question rather than at the start, so a
+ * piece that changes metre keeps being cut at its own bar lines. Bar 0 is the
+ * first full bar however much pickup precedes it, so an upbeat is bar -1 and is
+ * never taken for a hypermetric downbeat. Whether there is an upbeat at all is
+ * decided the way the rest of the analysis decides it: a note a millibeat early
+ * is playing the downbeat, not anticipating it.
+ *
+ * @param notes The notes to read, in any order. Notes that never sound are
+ *   dropped.
+ * @param meter A single time signature, or the piece's meter map; defaults to
+ *   4/4 throughout.
+ * @param opts Analysis options; see {@link HypermeterOptions}.
+ * @returns The grouping, its downbeats, a confidence, and a rationale.
+ * @example
+ * ```ts
+ * import { hypermeter } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 16 },
+ *   { pitch: 65, startBeat: 16, durationBeat: 16 },
+ * ];
+ * hypermeter(notes).groupBars; // 4
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function hypermeter(notes: readonly NoteEvent[], meter?: MeterLike, opts?: HypermeterOptions): Hypermeter;
+
+/**
+ * Phrases: the unit of music one bar larger than the chord.
+ *
+ * Every other analysis in this library is local — a chord against the next
+ * chord, a note against the chord under it — and that is the ceiling on what it
+ * can say. A cadence is a cadence because it falls at the end of a phrase, so
+ * two chords read in isolation cannot settle how much weight one carries. This
+ * module draws the boundaries, then ranks the cadences that sit on them.
+ *
+ * No single signal draws a phrase boundary reliably, so three are combined: the
+ * cadences the harmony forms, the rests and long notes the melody breathes at,
+ * and the points where the music starts saying something it has said before. A
+ * boundary is reported with the evidence behind it and a confidence, because a
+ * phrase reading is an interpretation and pretending otherwise would be worse
+ * than useless to a caller deciding whether to trust it.
+ */
+
+/**
+ * A reason a phrase boundary was placed where it was.
+ *
+ * @category Arrangement & Analysis
+ */
+type PhraseSignal = 
+/** A cadence closed on the beat the boundary falls at. */
+'cadence'
+/** The melody stopped sounding long enough to have taken a breath. */
+ | 'rest'
+/** A note was held long enough to read as an arrival. */
+ | 'longNote'
+/** The music began repeating material heard immediately before. */
+ | 'repetition'
+/** The boundary falls on a hypermetric downbeat. */
+ | 'hypermeter'
+/** The music ends here, which closes whatever phrase was open. */
+ | 'pieceEnd';
+/**
+ * One phrase: a span of music closed by a boundary, and the evidence for it.
+ *
+ * @category Arrangement & Analysis
+ */
+type Phrase = {
+    /** First beat of the phrase; negative when the phrase begins in a pickup. */
+    startBeat: number;
+    /** End of the phrase, exclusive. */
+    endBeat: number;
+    /**
+     * The cadence closing the phrase, or null when the boundary rests on the
+     * melody and the metre alone.
+     */
+    cadence: CadenceHit | null;
+    /** Why the closing boundary was placed here, strongest evidence first. */
+    signals: PhraseSignal[];
+    /**
+     * How well evidenced the phrase is, in [0, 1]: how strong its closing
+     * boundary is, and how close its length is to the length expected of a
+     * phrase in this piece.
+     */
+    confidence: number;
+    /**
+     * How much structural weight the closing cadence carries, in [0, 1]; 0 for a
+     * phrase that no cadence closes.
+     *
+     * This is the number that answers "which cadence matters most": it grades the
+     * cadence by how conclusive its type is, then by where the phrase it closes
+     * sits — a cadence ending the piece or landing on a hypermetric boundary
+     * closes more than one in the middle of a hyperbar.
+     * {@link structuralCadences} ranks by it.
+     */
+    structuralWeight: number;
+    /** A short reading of the phrase in words. */
+    rationale: string;
+};
+/**
+ * Options for {@link phrasesFromTimeline}.
+ *
+ * @category Arrangement & Analysis
+ */
+type PhraseOptions = {
+    /**
+     * A single time signature held across the whole span, as sugar for a
+     * one-element `meters`; defaults to 4/4. Giving both is an input error.
+     *
+     * @defaultValue `4/4`
+     */
+    ts?: TimeSignature;
+    /**
+     * The meter as it changes over the span. Bar lines, hypermetric downbeats and
+     * the default phrase length all follow the signature in force at the beat in
+     * question, so a piece that changes metre is not read in the one it opened in.
+     *
+     * @defaultValue 4/4 throughout
+     */
+    meters?: MeterMap;
+    /**
+     * Key context for cadence detection: one key for the whole span, or the key
+     * in force at a given beat. Omit it to have the key searched for over time,
+     * so a piece that modulates has each cadence read in the key it arrives in.
+     *
+     * @defaultValue the key inferred from the notes over time
+     */
+    key?: KeyContext;
+    /**
+     * End of the analysed span in beats; defaults to the end of the last note or
+     * timeline segment.
+     *
+     * @defaultValue the end of the input
+     */
+    totalBeats?: number;
+    /**
+     * Length a phrase is expected to run, in beats; defaults to one hyperbar.
+     *
+     * This is a prior, not a rule: a boundary is placed where the evidence puts
+     * it, and this decides how much evidence an irregular length has to carry
+     * before it is preferred to a regular one. Set it to two hyperbars for music
+     * whose phrases are periods.
+     *
+     * @defaultValue one hyperbar of the opening meter
+     */
+    expectedPhraseBeats?: number;
+    /**
+     * Shortest phrase that may be reported, in beats; defaults to one bar of the
+     * opening meter.
+     *
+     * @defaultValue one bar of the opening meter
+     */
+    minPhraseBeats?: number;
+    /**
+     * Silence at least this long divides phrases; defaults to half a bar of the
+     * opening meter.
+     *
+     * @defaultValue half a bar of the opening meter
+     */
+    restBeats?: number;
+    /**
+     * A note held at least this long reads as an arrival and closes a phrase;
+     * defaults to one bar of the opening meter.
+     *
+     * @defaultValue one bar of the opening meter
+     */
+    longNoteBeats?: number;
+    /**
+     * A hypermeter already computed for this piece, to be used instead of
+     * inferring one. Pass it when the caller has already asked for the grouping,
+     * or to impose a grouping the search would not have chosen.
+     *
+     * @defaultValue inferred from the notes and the cadences found
+     */
+    hypermeter?: Hypermeter;
+    /**
+     * Upper bound on the work this call may do.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * A cadence ranked by how much of the structure it closes.
+ *
+ * @category Arrangement & Analysis
+ */
+type StructuralCadence = {
+    /** Index of the phrase this cadence closes, in the array it came from. */
+    phraseIndex: number;
+    /** The beat the cadence arrives on. */
+    atBeat: number;
+    /** The beat the phrase it closes ends at. */
+    endBeat: number;
+    /** The cadence itself. */
+    cadence: CadenceResult;
+    /** Structural weight in [0, 1]; {@link Phrase.structuralWeight}. */
+    weight: number;
+    /** Why it weighs what it does. */
+    rationale: string;
+};
+/**
+ * Split a piece into phrases.
+ *
+ * Three kinds of evidence are gathered independently and then reconciled. The
+ * harmony contributes its cadences, each closing at the end of the chord it
+ * arrives on. The melody contributes the rests it breathes at and the notes it
+ * holds long enough to read as arrivals. Repetition contributes the beats where
+ * the music restarts material it has just played. The metre contributes its
+ * hypermetric downbeats, which confirm a boundary but never declare one on
+ * their own.
+ *
+ * The boundaries are then chosen together rather than one at a time: the
+ * reading that best trades each boundary's evidence against how regular the
+ * phrase lengths come out is selected by dynamic programming, at a fixed cost
+ * per cut. That is what stops a phrase being declared at every plausible beat,
+ * and what lets a well-evidenced irregular phrase survive next to regular ones.
+ *
+ * The result is contiguous: phrases abut, and together they cover the span from
+ * the first note to the end of the music. A cadence found in the middle of a
+ * phrase is not lost — it is still reachable through {@link detectCadences} —
+ * but only the cadences the reading puts at phrase ends are ranked by
+ * {@link structuralCadences}.
+ *
+ * @param timeline The chord timeline the cadences are read from.
+ * @param notes The melody, for its rests, held notes and repetitions. Notes
+ *   that never sound are dropped.
+ * @param opts Analysis options; see {@link PhraseOptions}.
+ * @returns The phrases, in time order; one phrase covering the whole span when
+ *   the span is too short to divide.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes, phrasesFromTimeline } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 4 },
+ *   { pitch: 67, startBeat: 4, durationBeat: 4 },
+ *   { pitch: 60, startBeat: 8, durationBeat: 8 },
+ * ];
+ * const { timeline } = chordTimelineFromNotes(notes);
+ * const phrases = phrasesFromTimeline(timeline, notes);
+ * phrases[phrases.length - 1]?.cadence?.cadence.type; // 'authentic', when one closes it
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function phrasesFromTimeline(timeline: ChordTimeline, notes: readonly NoteEvent[], opts?: PhraseOptions): Phrase[];
+/**
+ * Rank the cadences that close phrases by how much structure they close.
+ *
+ * This is the question the phrase layer exists to answer. Two chords alone
+ * cannot say whether a V-to-I is the end of the piece or a passing confirmation
+ * halfway through a hyperbar; a phrase reading can, because it knows what the
+ * cadence closes and where that sits. Phrases no cadence closes are left out.
+ *
+ * @param phrases The phrases, as {@link phrasesFromTimeline} returns them.
+ * @returns The cadences, heaviest first; ties keep the earlier one.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes, phrasesFromTimeline, structuralCadences } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 4 },
+ *   { pitch: 67, startBeat: 4, durationBeat: 4 },
+ *   { pitch: 60, startBeat: 8, durationBeat: 8 },
+ * ];
+ * const { timeline } = chordTimelineFromNotes(notes);
+ * const ranked = structuralCadences(phrasesFromTimeline(timeline, notes));
+ * ranked[0]; // the cadence carrying the most structural weight, if any
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function structuralCadences(phrases: readonly Phrase[]): StructuralCadence[];
+
+/**
+ * Sections: the largest unit this library reads, recovered from repetition.
+ *
+ * A section is found, not named. What the analysis can see is that a span of
+ * music is a restatement of an earlier one, so the spans are labelled by order
+ * of first appearance — A, B, C — and nothing more is claimed. Calling a
+ * repeated span a chorus would be a guess dressed as a finding: repetition
+ * alone cannot tell a chorus from a second verse, and the label a listener
+ * would give depends on lyrics, arrangement and loudness that the notes do not
+ * carry.
+ */
+
+/**
+ * A span of music labelled by which earlier span it restates.
+ *
+ * @category Arrangement & Analysis
+ */
+type FormSection = {
+    /**
+     * The section's letter, assigned in order of first appearance: the opening
+     * material is A, the first material unlike it is B, and a later restatement
+     * of A is A again. Past Z the letters double (AA, AB), the way spreadsheet
+     * columns do. No functional name — verse, chorus, bridge — is ever inferred.
+     */
+    label: string;
+    /** First beat of the section; negative when it opens with a pickup. */
+    startBeat: number;
+    /** End of the section, exclusive. */
+    endBeat: number;
+    /** The section's length in bars. */
+    bars: number;
+    /**
+     * Index, in the returned array, of the first section carrying this label; the
+     * section's own index when it is that first appearance.
+     */
+    firstOccurrence: number;
+    /**
+     * How alike this section and its first occurrence are, in [0, 1]; 1 on the
+     * first occurrence itself. The mean over the units the section was merged
+     * from, each scored against the unit it matched.
+     */
+    similarity: number;
+    /** How the section came to carry its label. */
+    rationale: string;
+};
+/**
+ * Options for {@link sectionsFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
+type FormSectionOptions = {
+    /**
+     * A single time signature held across the whole span, as sugar for a
+     * one-element `meters`; defaults to 4/4. Giving both is an input error.
+     *
+     * @defaultValue `4/4`
+     */
+    ts?: TimeSignature;
+    /**
+     * The meter as it changes over the span, so a piece that changes metre is cut
+     * at its own bar lines.
+     *
+     * @defaultValue 4/4 throughout
+     */
+    meters?: MeterMap;
+    /**
+     * Length of the unit spans are compared in, in bars; defaults to one hyperbar.
+     *
+     * Sections are found by comparing equal units and merging the neighbours that
+     * match, so this is the resolution of the answer rather than the length of a
+     * section: a section is any whole number of units long.
+     *
+     * @defaultValue the inferred hyperbar, in bars
+     */
+    unitBars?: number;
+    /**
+     * How alike two units must be before the later one is called a restatement of
+     * the earlier, in [0, 1].
+     *
+     * @defaultValue `0.8`
+     */
+    threshold?: number;
+    /**
+     * End of the analysed span in beats; defaults to the end of the last note.
+     *
+     * @defaultValue the end of the last note
+     */
+    totalBeats?: number;
+    /**
+     * Upper bound on the work this call may do.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * Recover a piece's sections from what it repeats.
+ *
+ * The span is cut into equal units of `unitBars` bars, each unit is compared
+ * with every unit before it, and a unit alike enough to an earlier one takes
+ * that unit's label. Neighbouring units carrying the same label are then merged,
+ * so an eight-bar section built of two like four-bar units is reported as one
+ * section rather than two.
+ *
+ * Likeness is measured on the melodic line and on the harmonic content
+ * together — the same tune under different harmony is a variation, not a
+ * restatement — and the labels are letters in order of first appearance.
+ * Nothing beyond "this is a restatement of that" is asserted: see
+ * {@link FormSection.label}.
+ *
+ * A pickup belongs to the section it leads into, so material before the first
+ * bar is folded into the opening unit rather than made a section of its own.
+ *
+ * @param notes The piece's notes, in any order. Notes that never sound are
+ *   dropped.
+ * @param opts Analysis options; see {@link FormSectionOptions}.
+ * @returns The sections, in time order.
+ * @example
+ * ```ts
+ * import { sectionsFromNotes } from '@libraz/libcantus';
+ * const bar = (pitch: number, at: number) => ({ pitch, startBeat: at, durationBeat: 4 });
+ * const notes = [bar(60, 0), bar(64, 4), bar(67, 8), bar(60, 12)];
+ * sectionsFromNotes(notes, { unitBars: 2 }).map((section) => section.label);
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function sectionsFromNotes(notes: readonly NoteEvent[], opts?: FormSectionOptions): FormSection[];
+
+/**
+ * Melody as a shape, rather than as a run of notes.
+ *
+ * A motif is held here as an interval contour plus a rhythmic profile, which is
+ * what makes a restatement at another pitch level the same motif; the absolute
+ * pitches only ever describe one statement of it. On that footing two statements
+ * can be compared and the transformation between them named — repetition,
+ * transposition, inversion, retrograde, augmentation — and phrases that stand in
+ * no such relation can still be scored for similarity.
+ */
+
+/**
+ * Step direction between two consecutive notes.
+ *
+ * @category Arrangement & Analysis
+ */
+type ContourDirection = 'up' | 'down' | 'same';
+/**
+ * The overall shape of a line.
+ *
+ * The first four names are the vocabulary the motif generator's contours are
+ * written in, and mean the same here. `'static'` is the shape a generator never
+ * asks for and an analysis regularly meets: a line that does not move. A line
+ * that dips and comes back — an arch upside down — reads as `'wave'`, since the
+ * shared vocabulary has no name of its own for it.
+ *
+ * A wave has to turn more than once to be heard as one, so a cell the generator
+ * writes for `'wave'` reads back as `'wave'` only from three bars up; the one-
+ * and two-bar cells turn once and read as `'arch'`. The other three shapes come
+ * back under their own name at every length.
+ *
+ * @category Arrangement & Analysis
+ */
+type MelodicContourShape = 'arch' | 'ascending' | 'descending' | 'wave' | 'static';
+/**
+ * The abstract shape of a line: its step directions and what they add up to.
+ *
+ * @category Arrangement & Analysis
+ */
+type MelodicContour = {
+    /** One direction per adjacent pair of notes, in time order. */
+    directions: ContourDirection[];
+    /** What the directions add up to. */
+    shape: MelodicContourShape;
+    /** Index of the highest note; ties keep the earliest. */
+    peakIndex: number;
+    /** Index of the lowest note; ties keep the earliest. */
+    troughIndex: number;
+    /** Semitone distance from the lowest note to the highest. */
+    range: number;
+    /** Why the line was given that shape. */
+    rationale: string;
+};
+/**
+ * One statement of a motif, addressed in the melody it was found in.
+ *
+ * The notes themselves are not repeated here: a statement is the motif's notes
+ * moved by `transpose` and stretched by `timeRatio`, and `noteIndex` addresses
+ * the original array for a caller that wants them exactly.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifOccurrence = {
+    /**
+     * Index of the statement's first note among the sounding notes of the melody,
+     * in time order. Notes that never sound are dropped before the search, so this
+     * is not an index into the caller's array unless the caller's array has none.
+     */
+    noteIndex: number;
+    /** Onset of the statement's first note. */
+    startBeat: number;
+    /** End of the statement's last note, exclusive. */
+    endBeat: number;
+    /** Semitones this statement stands above the motif's first statement. */
+    transpose: number;
+    /**
+     * How much this statement is stretched against the motif's first: 2 for a
+     * statement in doubled note values, 0.5 for one in halved values, 1 for one in
+     * the same values.
+     */
+    timeRatio: number;
+};
+/**
+ * A recurring melodic cell.
+ *
+ * Identity is the interval sequence plus the rhythmic profile, so every
+ * statement of the motif carries the same `intervals` and `rhythm` however far
+ * it has been transposed or however wide its note values are written. `notes`
+ * holds one statement — the first — exactly as it sounds.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifData = {
+    /** The first statement, exactly as it sounds in the melody. */
+    notes: NoteEvent[];
+    /**
+     * Semitones between consecutive notes. This is the transposition-invariant
+     * identity of the cell: two statements a fifth apart share it.
+     */
+    intervals: number[];
+    /**
+     * Onset-to-onset gaps as multiples of the first gap, so an even cell reads
+     * `[1, 1, 1]` whatever the tempo or note values it is written in.
+     */
+    rhythm: number[];
+    /** Every statement found, in time order; the first is `notes`. */
+    occurrences: MotifOccurrence[];
+    /** Why this counts as a motif. */
+    rationale: string;
+};
+/**
+ * Options controlling {@link extractMotifs}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ExtractMotifsOptions = {
+    /**
+     * Shortest cell to report, in notes.
+     *
+     * @defaultValue 3
+     */
+    minNotes?: number;
+    /**
+     * Longest cell to report, in notes.
+     *
+     * @defaultValue 8
+     */
+    maxNotes?: number;
+    /**
+     * How many statements a cell needs before it is reported.
+     *
+     * @defaultValue 2
+     */
+    minOccurrences?: number;
+    /**
+     * Upper bound on the work this call may do.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * How one statement of a motif stands to another.
+ *
+ * `'transposition'` is the literal one — every interval preserved, which is what
+ * makes a sequence built on it a *real* sequence. `'tonalTransposition'` shifts
+ * by scale degrees instead and lets the key resize the intervals, which is what
+ * makes a sequence built on it a *tonal* sequence; the two are different devices
+ * and are never reported as one. `'augmentation'` and `'diminution'` name the
+ * relation only when the pitches are untouched, so an inversion in doubled note
+ * values reads as `'inversion'` with a `timeRatio` of 2 rather than losing the
+ * inversion to the stretch.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifRelationKind = 'repetition' | 'transposition' | 'tonalTransposition' | 'inversion' | 'retrograde' | 'retrogradeInversion' | 'augmentation' | 'diminution';
+/**
+ * The transformation that turns one motif into another.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifRelation = {
+    /** The named transformation. */
+    kind: MotifRelationKind;
+    /**
+     * Whether the second statement begins where the first ends, which is what
+     * separates a sequence from a restatement elsewhere in the piece: a
+     * `'transposition'` that is one is a real sequence, a `'tonalTransposition'`
+     * that is one is a tonal sequence.
+     */
+    sequence: boolean;
+    /** Semitones from the first statement's first note to the second's. */
+    semitones: number;
+    /** The same distance named as a spelled interval. */
+    interval: SpelledInterval;
+    /** Scale degrees the second statement stands above the first, when tonal. */
+    degrees?: number;
+    /**
+     * How much the second statement is stretched against the first: 2 for doubled
+     * note values, 0.5 for halved, 1 for unchanged.
+     */
+    timeRatio: number;
+    /** Why the pair was given that name. */
+    rationale: string;
+};
+/**
+ * Anything that can be read as a melodic line: a motif, or plain note events.
+ *
+ * @category Arrangement & Analysis
+ */
+type MelodicPhrase = MotifData | readonly NoteEvent[];
+/**
+ * How alike two lines are, and how the answer was reached.
+ *
+ * @category Arrangement & Analysis
+ */
+type MelodicComparison = {
+    /** Overall likeness in [0, 1]; 1 for the same line, transposition included. */
+    similarity: number;
+    /** Likeness of the interval sequences alone, in [0, 1]. */
+    pitchSimilarity: number;
+    /** Likeness of the rhythmic profiles alone, in [0, 1]. */
+    rhythmSimilarity: number;
+    /** Why the lines scored what they did. */
+    rationale: string;
+};
+/**
+ * Find the cells a melody keeps coming back to.
+ *
+ * Every window of `minNotes` to `maxNotes` consecutive notes is reduced to its
+ * interval sequence and its rhythmic profile, and windows sharing both are
+ * statements of one motif — so a restatement a fifth higher, or one written in
+ * doubled note values, is found as the same cell rather than as a new one.
+ * Overlapping statements of a repetitive figure are counted once, and a cell
+ * whose statements all sit inside the statements of a longer cell that recurs at
+ * least as often is dropped, so the answer names the longest thing that recurs
+ * rather than every fragment of it.
+ *
+ * The melody is expected to be monophonic, as {@link analyzeVoice} expects a
+ * voice to be; split polyphonic material into lines first. Onsets are expected to
+ * be quantised, since two statements must agree on their rhythm to be recognised
+ * as one motif.
+ *
+ * @param notes The melody, in time order. Notes that never sound are dropped.
+ * @param opts Cell-length bounds and the recurrence threshold; see
+ *   {@link ExtractMotifsOptions}.
+ * @returns The motifs found, longest first, then by how often they recur, then
+ *   by where they first appear. Empty when nothing recurs.
+ * @example
+ * ```ts
+ * import { extractMotifs } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+ *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+ *   { pitch: 67, startBeat: 4, durationBeat: 1 },
+ *   { pitch: 69, startBeat: 5, durationBeat: 1 },
+ *   { pitch: 71, startBeat: 6, durationBeat: 1 },
+ * ];
+ * const motifs = extractMotifs(notes);
+ * motifs[0]?.occurrences.map((o) => o.startBeat); // [0, 4]
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function extractMotifs(notes: readonly NoteEvent[], opts?: ExtractMotifsOptions): MotifData[];
+/**
+ * Read a run of notes as a single-statement motif.
+ *
+ * {@link extractMotifs} answers with motifs it found recurring; this is how a
+ * caller names one it already has — a subject, an answer, a phrase lifted out of
+ * a score — so that it can be handed to {@link relateMotifs}.
+ *
+ * @param notes The cell, in time order. Notes that never sound are dropped.
+ * @returns The motif, carrying exactly one occurrence.
+ * @example
+ * ```ts
+ * import { motifFromNotes, relateMotifs } from '@libraz/libcantus';
+ * const subject = motifFromNotes([
+ *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+ *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+ * ]);
+ * const answer = motifFromNotes([
+ *   { pitch: 67, startBeat: 3, durationBeat: 1 },
+ *   { pitch: 69, startBeat: 4, durationBeat: 1 },
+ *   { pitch: 71, startBeat: 5, durationBeat: 1 },
+ * ]);
+ * relateMotifs(subject, answer)?.kind; // 'transposition'
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function motifFromNotes(notes: readonly NoteEvent[]): MotifData;
+/**
+ * Name how two statements of a motif relate.
+ *
+ * The two are compared as shapes, not as pitches: the interval sequences decide
+ * the pitch transformation and the onset gaps decide the timing, so a statement
+ * a fourth higher in doubled note values is recognised for what it is. A pair
+ * whose rhythms do not correspond — the same way round for a repetition or a
+ * transposition, back to front for a retrograde — is not a transformation of the
+ * motif but a different figure, and answers null; {@link melodicSimilarity} is
+ * what scores those.
+ *
+ * With a `key` in hand the search also asks whether the second statement is the
+ * first moved by scale degrees rather than by semitones. That is the tonal
+ * answer to the real one, and the two are kept apart: a real transposition keeps
+ * every interval literally, a tonal one lets the key resize them, so a subject
+ * answered a step higher reads as `'transposition'` when its major second stays
+ * major and as `'tonalTransposition'` when the scale turns it minor.
+ *
+ * @param a The model statement.
+ * @param b The statement to name against it.
+ * @param key Key context for the tonal reading; without it, a statement that
+ *   only holds diatonically is not recognised.
+ * @returns The relation, or null when the two stand in none.
+ * @example
+ * ```ts
+ * import { majorKey, motifFromNotes, relateMotifs } from '@libraz/libcantus';
+ * const model = motifFromNotes([
+ *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+ *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+ * ]);
+ * const answer = motifFromNotes([
+ *   { pitch: 62, startBeat: 3, durationBeat: 1 },
+ *   { pitch: 64, startBeat: 4, durationBeat: 1 },
+ *   { pitch: 65, startBeat: 5, durationBeat: 1 },
+ * ]);
+ * relateMotifs(model, answer, majorKey(0))?.kind; // 'tonalTransposition'
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function relateMotifs(a: MotifData, b: MotifData, key?: KeyScale): MotifRelation | null;
+/**
+ * Compare two lines and say why they scored what they did.
+ *
+ * The metric is a normalised edit distance over the interval sequence, weighted
+ * against the same over the rhythmic profile. Intervals rather than pitches,
+ * because the same tune in another key is the same tune; edit distance rather
+ * than a step-by-step correlation, because a variant that adds a passing note or
+ * drops one still has to line up with its model, and only an alignment-based
+ * measure can do that. Substituting one interval for another costs by how far
+ * apart they are rather than a flat step, so an answer that widens a third to a
+ * fourth stays close to its model while one that replaces it with a leap does
+ * not. The rhythm carries the smaller share: a melody is recognised mostly by
+ * its pitch shape, but a figure in a wholly different rhythm is a different
+ * figure.
+ *
+ * @param a The first line: a motif, or plain note events.
+ * @param b The second line.
+ * @returns The overall likeness, the two terms behind it, and a rationale.
+ * @example
+ * ```ts
+ * import { compareMelodies } from '@libraz/libcantus';
+ * const line = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+ *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+ * ];
+ * compareMelodies(line, line).similarity; // 1
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function compareMelodies(a: MelodicPhrase, b: MelodicPhrase): MelodicComparison;
+/**
+ * How alike two lines are, in [0, 1].
+ *
+ * The number {@link compareMelodies} reaches, for callers that only want to rank
+ * phrases: 1 for the same line — a transposition of it included, since the
+ * measure is built on intervals — and lower the further two lines are from being
+ * each other's variant. Symmetric in its arguments, and deterministic.
+ *
+ * @param a The first line: a motif, or plain note events.
+ * @param b The second line.
+ * @returns The likeness in [0, 1].
+ * @example
+ * ```ts
+ * import { melodicSimilarity } from '@libraz/libcantus';
+ * const line = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+ *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+ * ];
+ * melodicSimilarity(line, line); // 1
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function melodicSimilarity(a: MelodicPhrase, b: MelodicPhrase): number;
+/**
+ * Read the shape of a line.
+ *
+ * The step directions are the literal answer; the shape is what they add up to.
+ * A line is called ascending or descending when most of its motion runs one way,
+ * not only when every step does — a climb with one dip in it is still heard as a
+ * climb — and an arch when it rises to an interior peak and comes back down.
+ * Anything that keeps changing direction is a wave, and a line that does not move
+ * is static.
+ *
+ * @param notes The line: a motif, or plain note events. Notes that never sound
+ *   are dropped.
+ * @returns The directions, the shape, the peak and trough, and a rationale.
+ * @example
+ * ```ts
+ * import { melodicContour } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { pitch: 64, startBeat: 1, durationBeat: 1 },
+ *   { pitch: 60, startBeat: 2, durationBeat: 1 },
+ * ];
+ * melodicContour(notes).shape; // 'arch'
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function melodicContour(notes: MelodicPhrase): MelodicContour;
+
+/**
+ * Harmonic reduction: which chords carry the progression and which decorate it.
+ *
+ * `analyzeVoice` can say that a note is a passing tone; a timeline is flat, so
+ * nothing could say the same of a chord. This is that answer one level up — the
+ * middle chord of `Cmaj7 - C#dim7 - Dm7` is an embellishment, and the frame
+ * under `I - IV - #ivo7 - V - I` is `I - IV - V - I`.
+ *
+ * **The position taken here.** What counts as structural is a theoretical
+ * choice, not a fact, and this module makes the functional one: *a chord is
+ * structural unless it is demonstrably an embellishment of its neighbours*. The
+ * frame is what carries harmonic function in the prevailing key — the tonic, the
+ * dominant, and the chords that cadence — so those are never reduced away; a
+ * chord that tonicizes something other than the tonic is prolonging, not
+ * framing, however dominant its sonority. Everything else keeps its place unless
+ * its root traces one of two figures against the chords around it, the same two
+ * figures {@link analyzeVoice} matches at the note level: a step through
+ * (passing) and a step away and back (neighbor). Defaulting to structural, and
+ * demoting only on evidence, is what keeps a reduction from quietly deleting
+ * harmony it merely failed to recognize.
+ *
+ * The salience reading — that the frame is whatever lasts longest, regardless of
+ * function — is the main alternative, and it is a live one for repertoire where
+ * function is weak. {@link ReduceProgressionOptions.basis} switches to it: the
+ * figures stay the same, only what protects a chord from them changes.
+ *
+ * Both readings are deterministic: the same timeline and key always reduce the
+ * same way.
+ */
+
+/**
+ * The place a chord holds in a progression.
+ *
+ * `'structural'` is the frame; `'passing'` and `'neighbor'` are the two
+ * embellishing figures, spelled exactly as {@link TheoryLabel} spells them for
+ * a note, so one legend covers both levels of analysis.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReductionLevel = 'structural' | 'passing' | 'neighbor';
+/**
+ * A chord with the place it holds, the beats it holds it for, and a short
+ * rationale.
+ *
+ * One entry per timeline segment, in the same order. The entry carries the
+ * segment's own beat range, so the chords that survive a filter still say when
+ * they sound: holding the structural chords fixed is what a reharmonizer needs,
+ * and it cannot hold a chord at a place the filter threw away.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReducedChord = {
+    chord: Chord;
+    startBeat: number;
+    endBeat: number;
+    level: ReductionLevel;
+    rationale: string;
+};
+/**
+ * What a reduction treats as the frame.
+ *
+ * `'function'` is the functional reading: the tonic, the dominant and the
+ * chords that cadence are the frame. `'duration'` is the salience reading: the
+ * chords that hold the harmony at least as long as the median chord are the
+ * frame, whatever function they carry.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReductionBasis = 'function' | 'duration';
+/**
+ * Options for {@link reduceProgression}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReduceProgressionOptions = {
+    /**
+     * Which reading decides what the frame is; see {@link ReductionBasis}.
+     *
+     * @defaultValue `'function'`
+     */
+    basis?: ReductionBasis;
+};
+/**
+ * Reduce a chord progression to its frame, labelling every chord.
+ *
+ * One entry comes back per timeline segment, in the same order, so the two read
+ * in step. Filtering the result to `'structural'` is the skeleton view — the
+ * `I - IV - V - I` under a progression that spells far more chords than that —
+ * and holding those chords fixed is what a reharmonizer needs in order to
+ * rewrite the surface without moving the harmony. Each entry carries its own
+ * `startBeat` and `endBeat`, so a filtered chord still knows where it sounds
+ * once the segments it was read against are gone.
+ *
+ * A chord is structural unless one of two figures demotes it: its root stepping
+ * in from the previous chord and on to the next in the same direction (passing),
+ * or stepping away from a harmony that returns (neighbor). Chords carrying the
+ * frame are never demoted, and what carries the frame is the module's stated
+ * theoretical position — see {@link ReductionBasis} for the reading this takes
+ * by default and the one it can be switched to.
+ *
+ * Chords separated by a rest form no figure across it, the way
+ * {@link detectCadences} pairs no chords across one.
+ *
+ * @param timeline The chord timeline to reduce.
+ * @param key The prevailing key, or the key in force at a given beat, for music
+ *   that modulates.
+ * @param opts Which reading decides the frame; see
+ *   {@link ReduceProgressionOptions}.
+ * @returns One labelled chord per segment, in time order.
+ * @throws If `opts.basis` is not one of the readings {@link ReductionBasis}
+ *   names.
+ * @example
+ * ```ts
+ * import { chordTimelineFromChords, majorKey, reduceProgression } from '@libraz/libcantus';
+ * const timeline = chordTimelineFromChords(
+ *   [
+ *     { rootPc: 0, quality: 'maj7', startBeat: 0 },
+ *     { rootPc: 1, quality: 'dim7', startBeat: 4 },
+ *     { rootPc: 2, quality: 'min7', startBeat: 8 },
+ *   ],
+ *   12,
+ * );
+ * reduceProgression(timeline, majorKey(0)).map((entry) => entry.level);
+ * // ['structural', 'passing', 'structural']
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function reduceProgression(timeline: ChordTimeline, key: KeyContext, opts?: ReduceProgressionOptions): ReducedChord[];
+
+export { reduceProgression as $, type ArrangementAnalysis as A, type TrackRole as B, type ChordMatch as C, type DetectChordOptions as D, type ExtractMotifsOptions as E, type FormSection as F, analyzeArrangement as G, type Hypermeter as H, compareMelodies as I, createArrangementSession as J, type KeyMatch as K, detectChord as L, MODAL_SCALE_NAMES as M, detectChordBest as N, detectKey as O, type Phrase as P, detectKeyBest as Q, type ReduceProgressionOptions as R, type StructuralCadence as S, type TensionPoint as T, detectKeyFromNotes as U, extractMotifs as V, hypermeter as W, melodicContour as X, melodicSimilarity as Y, motifFromNotes as Z, phrasesFromTimeline as _, type ArrangementOptions as a, relateMotifs as a0, sectionsFromNotes as a1, structuralCadences as a2, tensionCurve as a3, tensionCurveFrom as a4, type ArrangementSession as b, type ArrangementTrack as c, type Conflict as d, type ContourDirection as e, type DetectKeyOptions as f, type FormSectionOptions as g, type HypermeterOptions as h, type KeyVariant as i, type MelodicComparison as j, type MelodicContour as k, type MelodicContourShape as l, type MelodicPhrase as m, type ModalCandidate as n, type ModalScaleName as o, type MotifData as p, type MotifOccurrence as q, type MotifRelation as r, type MotifRelationKind as s, type PhraseOptions as t, type PhraseSignal as u, type ReducedChord as v, type ReductionBasis as w, type ReductionLevel as x, type TrackAnalysis as y, type TrackEdit as z };