@libraz/libcantus 0.9.4 → 1.0.0

package/dist/index-Dzr13q3d.d.cts

@@ -0,0 +1,1343 @@
+import { c as ChordLike, K as KeyLike, j as ChordToneRole, b as Chord, k as KeyRelation, e as ChordSegment, V as VoiceSnapshot, g as ChordSpan } from './index-C_8o--VE.cjs';
+import { T as TimeSignature, c as MeterMap } from './index-BkGmlyI3.cjs';
+import { d as KeyScale, g as NoteEvent } from './index-B9MNZboQ.cjs';
+
+/**
+ * The vocabulary the analyze layer explains itself in.
+ *
+ * `analyzeVoice` has always returned a short `rationale` beside the labels it
+ * assigns; the chord, numeral, cadence and key readings say the same kind of
+ * thing about a larger unit. One vocabulary keeps a rationale readable wherever
+ * it comes from: the conclusion first, a colon, then the fact it rests on, as a
+ * phrase rather than a sentence.
+ *
+ * The reading that was turned down is worth as much to a reader arguing with the
+ * result as the one that was kept, so every entry point that ranks readings can
+ * report them in the one shape below.
+ */
+/**
+ * A reading that was considered and rejected, and why it lost.
+ *
+ * @category Arrangement & Analysis
+ */
+type RejectedCandidate = {
+    /** The rejected reading, named the way the accepted one is named. */
+    label: string;
+    /** Why the accepted reading was preferred over this one. */
+    reason: string;
+};
+
+/**
+ * Key-profile vectors for {@link detectKey}.
+ *
+ * A key profile is a 12-entry vector indexed from the tonic (0 = tonic, 1 = flat
+ * second, ... 11 = major seventh) giving how strongly each chromatic degree is
+ * expected to sound in that key. Ranking a candidate key means rotating its
+ * profile onto the candidate tonic and correlating it with the pitch-class
+ * distribution of the music, which is what separates a key from its relative:
+ * C major and A minor contain the same seven pitch classes, but they expect the
+ * weight to fall on different degrees.
+ *
+ * The published vectors below are transcribed from their sources and are not
+ * tuned for this library; a citation accompanies each so a reader can check the
+ * digits.
+ */
+/**
+ * A pair of 12-entry key profiles, one per mode, each indexed from its own
+ * tonic (index 0 = tonic, 1 = flat second, ... 11 = major seventh).
+ *
+ * @category Recognition
+ */
+type KeyProfilePair = {
+    /** Degree weights for a major candidate, indexed from the major tonic. */
+    major: readonly number[];
+    /** Degree weights for a minor candidate, indexed from the minor tonic. */
+    minor: readonly number[];
+};
+/**
+ * Name of a built-in key profile accepted by {@link DetectKeyOptions.profile}.
+ *
+ * @category Recognition
+ */
+type KeyProfileName = 'krumhansl' | 'temperley' | 'flat';
+
+/**
+ * Borrowed chords (modal interchange) and the Neapolitan.
+ *
+ * Roots are pitch classes measured against the key tonic, so borrowed and
+ * chromatic chords are handled by their semitone offset rather than requiring a
+ * spelled key signature.
+ */
+
+/**
+ * The origin of a recognized non-diatonic chord, or null when none applies.
+ *
+ * @category Functional Harmony
+ */
+type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
+/**
+ * Whether a chord is borrowed from the parallel mode (modal interchange).
+ *
+ * True when the chord is not diatonic to `key` but is diatonic to its
+ * {@link parallelKeyOf | parallel key} — e.g. iv, bVI, or bVII in a major key, or the Picardy
+ * tonic and major IV in a minor key — and true for the Neapolitan, which is
+ * counted as a borrowing of its own even though it belongs to neither parallel
+ * mode. Two non-diatonic families are excluded: any other chord diatonic to
+ * neither mode (those are chromatic, not borrowed), and, in a minor key, chords
+ * explained by the altered minor forms (the major dominant and
+ * raised-leading-tone chords), which are in-key alterations rather than
+ * interchange even though they happen to fit the parallel major.
+ *
+ * @param chord The chord to test, as a chord symbol, chord data, or a `Chord`.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns True if the chord is borrowed from the parallel mode.
+ * @category Functional Harmony
+ */
+declare function isBorrowedChord(chord: ChordLike, key: KeyLike): boolean;
+/**
+ * Identify where a non-diatonic chord comes from.
+ *
+ * The Neapolitan (major triad on b2 of a key that does not have that degree
+ * already) is recognized first, since it sits outside both parallel modes;
+ * parallel-mode borrowing follows the {@link isBorrowedChord} rules. Diatonic
+ * chords and altered-minor chords, and unrecognized chromatic chords all yield
+ * null.
+ *
+ * @param chord The chord to classify, as a chord symbol, chord data, or a
+ *   `Chord`.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns The borrowing source, or null.
+ * @category Functional Harmony
+ */
+declare function borrowedSource(chord: ChordLike, key: KeyLike): BorrowedSource;
+
+/**
+ * Cadence detection between two successive chords.
+ *
+ * Roots are pitch classes measured against the key tonic, so borrowed and
+ * chromatic chords are handled by their semitone offset rather than requiring a
+ * spelled key signature.
+ */
+
+/**
+ * A recognized cadence, with the voice-leading facts its reading rests on.
+ *
+ * @category Functional Harmony
+ */
+type CadenceResult = {
+    /**
+     * The cadence the chord pair forms, or null when it forms none.
+     *
+     * `'phrygian'` and `'modal'` are the two named species: the first is a
+     * specific half cadence and is reported in place of `'half'`, the second is
+     * the bVII-to-I arrival that no common-practice type covers. Code counting
+     * half cadences has to count `'phrygian'` alongside `'half'`.
+     */
+    type: 'authentic' | 'plagal' | 'half' | 'deceptive' | 'phrygian' | 'modal' | null;
+    /**
+     * How conclusive an authentic cadence is: `'perfect'` when it is a PAC,
+     * `'imperfect'` when it is an IAC.
+     *
+     * Null for every other cadence type — the distinction is only defined for the
+     * authentic cadence — and null for an authentic cadence whose soprano is
+     * unknown, which is the case whenever no `voicing` is given.
+     */
+    strength: 'perfect' | 'imperfect' | null;
+    /**
+     * The role the final chord's highest sounding pitch plays in that chord.
+     *
+     * Omitted when no `voicing` was given, and when the top voice is a tension
+     * with no basic chord-tone role.
+     */
+    soprano?: ChordToneRole;
+    /**
+     * True when both chords stand on their own root — the inversion condition a
+     * perfect authentic cadence has to meet.
+     */
+    rootPosition: boolean;
+    /**
+     * True when the dominant resolved onto an inverted tonic (V to I6 and its
+     * relatives) instead of the root-position arrival it prepared, so the
+     * cadential weight is withheld even though the type still holds.
+     */
+    evaded: boolean;
+    /**
+     * Why the pair reads this way: the motion the type rests on, what graded an
+     * authentic cadence, and what a null type failed to be. Always present, in
+     * the phrasing {@link analyzeVoice} uses for a note.
+     */
+    rationale: string;
+    /**
+     * The cadences that were considered and rejected, empty unless
+     * {@link DetectCadenceOptions.alternatives} asked for them.
+     *
+     * These are the near misses — the readings a condition or two away from
+     * holding — rather than every type that did not fire, which for most pairs
+     * would be all of them.
+     */
+    alternatives: RejectedCandidate[];
+};
+/**
+ * Options for {@link detectCadence}.
+ *
+ * @category Functional Harmony
+ */
+type DetectCadenceOptions = {
+    /**
+     * The pitches actually sounding, as MIDI note numbers: the penultimate
+     * chord's voicing first, then the final chord's.
+     *
+     * The lowest pitch of each is its bass and so decides inversion, overriding
+     * whatever the chords' own `bassPc` says; the highest pitch of the final
+     * chord is the soprano. Without a voicing the soprano is unknown, and a
+     * perfect authentic cadence cannot be told from an imperfect one.
+     */
+    voicing?: [number[], number[]];
+    /**
+     * Report the cadences this pair came close to forming and why each was
+     * turned down.
+     *
+     * Off by default: the rationale is built from facts the classification
+     * already established, while a rival has to be phrased against conditions
+     * that did not fire, and most callers read the type only.
+     *
+     * @defaultValue false
+     */
+    alternatives?: boolean;
+    /**
+     * The chord before `from`, which is what tells a cadential six-four from an
+     * inverted tonic.
+     *
+     * A dominant reached from the tonic triad standing on its own bass was
+     * already sounding when that six-four did, so the cadence began there. Only
+     * the chord before the dominant settles that, and a caller reading a pair at
+     * a time has it to hand; without it the pair is classified on its own, as
+     * before.
+     *
+     * Accepted as a chord symbol, chord data, or a `Chord`.
+     */
+    approach?: ChordLike;
+};
+/**
+ * Classify the cadence formed by moving from one chord to the next.
+ *
+ * - authentic: V (dominant a fifth above the tonic) to I
+ * - plagal: IV (a fourth above the tonic) to I
+ * - modal: bVII to I, the cadence of rock and modal writing
+ * - deceptive: V to the key's own submediant, plus the borrowed bVI of a major
+ *   key
+ * - phrygian: iv6 to V of a minor key, the half cadence whose bass falls a
+ *   semitone from b6 to 5
+ * - half: any other chord than the dominant itself to V
+ *
+ * Both are read as scale degrees rather than as semitone distances, so a mode
+ * cadences onto the submediant and the dominant it actually has: the deceptive
+ * arrival of dorian is a major sixth above the tonic and that of phrygian a
+ * minor sixth. A half cadence normally rests on the major third that carries
+ * the leading tone, but where the key's own dominant has no leading tone —
+ * aeolian and dorian, the modal `v` of pop writing — the arrival's own third
+ * suffices as long as the key contains it. That relaxation never applies to a
+ * key whose dominant does carry the leading tone, so a borrowed minor `v` in a
+ * major key is no half cadence.
+ *
+ * A static V-to-V repeat with no root motion is not a cadence and yields a null
+ * type, and so is the tonic six-four resolving onto the dominant it already
+ * stands on: that pair is one harmony moving inside itself. Passing that
+ * six-four as `approach` when the dominant is the `from` chord is what lets the
+ * cadence be reported as the single event it is — the type and the beat are
+ * still the dominant's resolution, while the `rationale` says the cadence began
+ * at the six-four. A six-four the bass leaves instead (`IV-I64-IV`, or a
+ * neighbouring one over the tonic) is an ordinary inverted tonic and is read as
+ * one.
+ *
+ * An authentic cadence is graded perfect or imperfect. Perfect takes the
+ * dominant to the tonic with both chords in root position and the tonic in the
+ * soprano; anything else authentic is imperfect, including the leading-tone
+ * cadence, which has no dominant root to stand on. Only a `voicing` names the
+ * soprano, so without one the grade is null — the pair could still be either,
+ * and reporting perfect would be a guess.
+ *
+ * The `rationale` says which motion the reading rests on, including for a pair
+ * that cadences not at all; `alternatives` is empty unless asked for, and then
+ * names the cadences the pair came close to forming.
+ *
+ * @param from The penultimate chord, as a chord symbol, chord data, or a
+ *   `Chord`.
+ * @param to The final chord, in any of the same forms.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @param opts Voice-leading detail, the chord before `from`, and whether to
+ *   collect the rejected readings; see {@link DetectCadenceOptions}.
+ * @returns The cadence, its strength, and the facts behind them.
+ * @example
+ * ```ts
+ * import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';
+ * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0));
+ * // { type: 'authentic', strength: null, rootPosition: true, evaded: false, ... }
+ * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0), {
+ *   voicing: [[55, 62, 71], [48, 64, 72]],
+ * });
+ * // { type: 'authentic', strength: 'perfect', soprano: 'root', ... }
+ * const sixFour = detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0), {
+ *   approach: makeChord(0, 'maj', 7), // C/G, the cadential six-four
+ * });
+ * sixFour.type; // 'authentic'
+ * // The rationale says where the cadence began.
+ * sixFour.rationale?.includes('cadential six-four'); // true
+ * ```
+ * @category Functional Harmony
+ */
+declare function detectCadence(from: ChordLike, to: ChordLike, key: KeyLike, opts?: DetectCadenceOptions): CadenceResult;
+
+/**
+ * Roman-numeral parsing and formatting.
+ *
+ * The {@link ROMAN_STYLE} table is the single source of truth for both
+ * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
+ * inverses by construction. The chromatic chords no numeral can spell — the
+ * augmented sixths, and the Neapolitan under its figured name — are matched as
+ * whole symbols beside that table.
+ */
+
+/**
+ * Build the chord denoted by a Roman numeral in a key.
+ *
+ * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
+ * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
+ * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
+ * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
+ * whose root becomes a local major tonic for the applied chord. Inverted chords
+ * carry a `bassPc`.
+ *
+ * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
+ * `m7b5`), since no half-diminished triad exists. Extension and added-tone
+ * suffixes are the canonical case-sensitive forms emitted by
+ * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
+ * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
+ * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
+ * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
+ * A figure string that is neither a recognized inversion nor a supported
+ * quality suffix throws rather than silently degrading to a triad.
+ *
+ * Four chromatic chords are named rather than numbered, and are accepted as
+ * whole symbols: the augmented sixths `It6`, `Fr6` and `Ger6` (also written
+ * `Ger65`), all three on the lowered submediant in the bass, and `N6` for the
+ * first-inversion Neapolitan, which builds exactly the chord `bII6` does.
+ * Each may be applied to a degree like any other numeral, so `Ger6/V` is the
+ * German sixth of the dominant.
+ *
+ * @param text The Roman numeral.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns The chord.
+ * @example
+ * ```ts
+ * import { romanToChord, majorKey } from '@libraz/libcantus';
+ * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
+ * romanToChord('Ger6', majorKey(0)); // Ab C Eb F#, bass Ab
+ * ```
+ * @category Functional Harmony
+ */
+declare function romanToChord(text: string, key: KeyLike): Chord;
+/**
+ * Options for {@link chordToRoman}.
+ *
+ * @category Functional Harmony
+ */
+type ChordToRomanOptions = {
+    /**
+     * Render a tonicizing chord as an applied numeral (`V7/V`, `viio7/ii`)
+     * instead of naming its root against the home key (`II7`, `#ivo7`).
+     *
+     * Off by default: naming the root is always a correct spelling, whereas
+     * whether a chromatic dominant is genuinely applied is a reading only the
+     * caller can make. Turning it on names the chords {@link secondaryDominant}
+     * builds as the applied numerals they are, except where the target degree
+     * carries no perfect fifth: nothing tonicizes a diminished triad, so a chord
+     * over the seventh degree of a major key stays `#IV7` rather than becoming a
+     * numeral no harmony text writes.
+     */
+    applied?: boolean;
+    /**
+     * Render a first-inversion Neapolitan under its figured name `N6` instead of
+     * the numeral `bII6`.
+     *
+     * Off by default, for the opposite reason to `applied`: both spellings name
+     * the same chord and `bII6` is already correct, so which one to write is a
+     * house-style choice rather than an analysis. `romanToChord` accepts either
+     * whatever this is set to. The augmented sixths need no such switch — no
+     * numeral spells them at all, so they always render as `It6`, `Fr6`
+     * and `Ger6`.
+     */
+    neapolitan?: boolean;
+};
+/**
+ * Render a chord as a Roman numeral relative to a key.
+ *
+ * Diatonic roots take their scale-degree numeral directly, so numerals are
+ * correct in both major and minor keys (and any custom scale). The quality
+ * selects the case and suffix; chromatic roots receive a flat/sharp spelling by
+ * convention. A key that is not heptatonic has no numeral of its own for every
+ * degree, so its roots are named against its parallel major.
+ *
+ * When the chord carries a `bassPc` on a chord tone, a figured-bass inversion
+ * (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true seventh
+ * chords; added-tone and extended qualities have no lossless figure and render
+ * in root position instead (the bass is dropped, pitch classes are preserved).
+ *
+ * A `bassPc` that is *not* a chord tone — a pedal or passing bass such as
+ * `C/D` — is likewise dropped, and the numeral names the upper chord alone.
+ * Roman-numeral notation spends its slash on applied chords (`V7/V`), so there
+ * is no unambiguous way to write such a bass; a caller that must keep it should
+ * read `chord.bassPc` alongside the numeral.
+ *
+ * A chord sounding one of the augmented sixths over an explicit bass on the
+ * lowered submediant renders as `It6`, `Fr6` or `Ger6`, since no numeral names
+ * those chords; see {@link augmentedSixthKind} for exactly when that applies.
+ *
+ * @param chord The chord to name, as a chord symbol, chord data, or a `Chord`.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @param opts `applied` renders tonicizing chords as `V7/V`-style numerals;
+ *   `neapolitan` renders a first-inversion Neapolitan as `N6`.
+ * @returns The Roman numeral string.
+ * @example
+ * ```ts
+ * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
+ * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
+ * chordToRoman(makeChord(2, 'dom7'), majorKey(0), { applied: true }); // => 'V7/V'
+ * ```
+ * @see {@link explainRoman} for the same numeral with the reasoning behind it.
+ * @category Functional Harmony
+ */
+declare function chordToRoman(chord: ChordLike, key: KeyLike, opts?: ChordToRomanOptions): string;
+/**
+ * A numeral with the reasoning behind it.
+ *
+ * @category Functional Harmony
+ */
+type RomanExplanation = {
+    /** The numeral, exactly as {@link chordToRoman} renders it. */
+    roman: string;
+    /** How the numeral was arrived at: the degree, the quality, and the bass. */
+    rationale: string;
+    /**
+     * The spellings the options turned down, empty unless the `alternatives`
+     * option of {@link ExplainRomanOptions} asked for them.
+     */
+    alternatives: RejectedCandidate[];
+};
+/**
+ * Options for {@link explainRoman}: {@link ChordToRomanOptions} plus the switch
+ * for the rival spellings.
+ *
+ * @category Functional Harmony
+ */
+type ExplainRomanOptions = ChordToRomanOptions & {
+    /**
+     * Report the numerals the other option settings would have rendered, and why
+     * this one was rendered instead.
+     *
+     * Off by default: each rival costs a further rendering pass, and a caller
+     * that only wants the numeral explained should not pay for the ones it did
+     * not get.
+     *
+     * @defaultValue false
+     */
+    alternatives?: boolean;
+};
+/**
+ * Render a chord as a Roman numeral and say how the numeral was arrived at.
+ *
+ * The numeral is exactly what {@link chordToRoman} returns for the same
+ * arguments — this is that function with its reasoning attached, for teaching
+ * material and for any interface whose users argue with the analysis. The
+ * rationale names the degree the root was spelled as, the quality that set the
+ * numeral's case and suffix, and what became of the bass, including the two
+ * cases where a bass exists and no numeral can carry it.
+ *
+ * @param chord The chord to name, as a chord symbol, chord data, or a `Chord`.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @param opts The rendering options of {@link chordToRoman}, plus
+ *   `alternatives` to collect the spellings they turned down.
+ * @returns The numeral, its rationale, and the rejected spellings.
+ * @example
+ * ```ts
+ * import { explainRoman, makeChord, majorKey } from '@libraz/libcantus';
+ * explainRoman(makeChord(7, 'dom7'), majorKey(0)).rationale;
+ * // 'V7: the root is the fifth degree of the key, the case and suffix come from the dom7 quality, and the chord stands on its own root'
+ * const applied = explainRoman(makeChord(2, 'dom7'), majorKey(0), { alternatives: true });
+ * applied.alternatives?.map((rejected) => rejected.label); // ['V7/V']
+ * ```
+ * @category Functional Harmony
+ */
+declare function explainRoman(chord: ChordLike, key: KeyLike, opts?: ExplainRomanOptions): RomanExplanation;
+
+/**
+ * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
+ * mirroring, and full chord analysis.
+ *
+ * Roots are pitch classes measured against the key tonic, so borrowed and
+ * chromatic chords are handled by their semitone offset rather than requiring a
+ * spelled key signature.
+ */
+
+/**
+ * The three broad harmonic functions of tonal music.
+ *
+ * @category Functional Harmony
+ */
+type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
+/**
+ * Whether a key's scale has a minor third and no major third (a minor key).
+ *
+ * @param key The key to test, as a key name, a key/scale, or a `Key`.
+ * @returns True if the key's scale is a minor one.
+ * @category Functional Harmony
+ */
+declare function isMinorKey(key: KeyLike): boolean;
+/**
+ * The harmonic function of a chord in a key.
+ *
+ * The root's offset above the tonic gives the baseline mapping, which follows
+ * common-practice major-key function and is a useful approximation in minor and
+ * for borrowed chords. Chord quality then refines it where the sonority settles
+ * an ambiguity the root offset cannot:
+ *
+ * - A chord that *sounds* like a dominant — a major third with a minor seventh,
+ *   or a diminished-family chord — and is not diatonic to the key has dominant
+ *   function when its root resolves down a fifth or by a semitone onto a
+ *   diatonic degree. This is what makes an applied dominant (`A7` in C, which
+ *   tonicizes ii) and its tritone substitute (`Db7`) read as dominant rather
+ *   than inheriting the function of the degree they happen to sit on.
+ * - The Neapolitan is subdominant.
+ * - An augmented sixth is subdominant. All three are altered predominants that
+ *   resolve outward onto the dominant, so they take subdominant function even
+ *   though the German sixth sounds a dominant seventh and would otherwise read
+ *   as the tritone substitute it shares its pitch classes with.
+ * - A major triad on bVI or bVII of a major key is subdominant — the borrowed
+ *   pop cadence chord, distinct from the bVII7 above, which has a seventh and
+ *   is a dominant sonority.
+ *
+ * @param chord The chord, as a chord symbol, chord data, or a `Chord`.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns The harmonic function.
+ * @example
+ * ```ts
+ * import { functionOf, makeChord, majorKey } from '@libraz/libcantus';
+ * functionOf(makeChord(9, 'dom7'), majorKey(0)); // 'dominant' — A7 tonicizes ii
+ * functionOf('Bb', 'C major'); // 'subdominant' — borrowed bVII
+ * ```
+ * @category Functional Harmony
+ */
+declare function functionOf(chord: ChordLike, key: KeyLike): HarmonicFunction;
+/**
+ * The result of {@link analyzeChord}: function, borrowing, and Roman numeral.
+ *
+ * @category Functional Harmony
+ */
+type ChordAnalysis = {
+    function: HarmonicFunction;
+    borrowed: boolean;
+    source: BorrowedSource;
+    roman: string;
+    /**
+     * Why the chord reads this way: the rule that settled its function, and where
+     * it was borrowed from when it was borrowed. Always present, in the phrasing
+     * {@link analyzeVoice} uses for a note.
+     */
+    rationale: string;
+    /**
+     * The readings that were considered and rejected, empty unless the
+     * `alternatives` option of {@link AnalyzeChordOptions} asked for them.
+     */
+    alternatives: RejectedCandidate[];
+};
+/**
+ * Options for {@link analyzeChord}: {@link ChordToRomanOptions} plus the switch
+ * for the rival readings.
+ *
+ * @category Functional Harmony
+ */
+type AnalyzeChordOptions = ChordToRomanOptions & {
+    /**
+     * Report the readings this analysis turned down: the function the chord's
+     * degree alone would have carried, the tonicizing reading a dominant sonority
+     * could have had, and the numerals the other rendering options would emit.
+     *
+     * Off by default. The rationale is built from facts the analysis already
+     * established, but a rival costs work nothing else needs — a second and third
+     * numeral rendering among them — and most callers read the conclusion only.
+     *
+     * @defaultValue false
+     */
+    alternatives?: boolean;
+};
+/**
+ * Whether every pitch class of a chord belongs to the key's scale.
+ *
+ * The test is strict against the key's own mode mask: in a natural-minor key
+ * the harmonic-minor dominant (major V) is *not* diatonic, since the raised
+ * leading tone lies outside the mask. Borrowing predicates treat that case as
+ * an in-key alteration separately (see {@link isBorrowedChord}).
+ *
+ * @param chord The chord to test, as a chord symbol, chord data, or a `Chord`.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns True if all chord pitch classes are scale tones.
+ * @category Functional Harmony
+ */
+declare function isDiatonic(chord: ChordLike, key: KeyLike): boolean;
+/**
+ * Analyze a chord in a key: harmonic function, borrowing, and Roman numeral.
+ *
+ * The function is quality-aware (see the predicates behind it), the source
+ * follows {@link borrowedSource}, and the numeral comes from
+ * {@link chordToRoman}. `borrowed` is true whenever a source is identified,
+ * which includes the Neapolitan: it belongs to neither parallel mode, and both
+ * this and {@link isBorrowedChord} count it as a borrowing all the same.
+ *
+ * The `rationale` says which of those rules settled the function, so a reader
+ * who disagrees can see what the reading rests on. `alternatives` is empty
+ * unless asked for, and then names the readings that were turned down.
+ *
+ * @param chord The chord to analyze, as a chord symbol, chord data, or a
+ *   `Chord`.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @param opts Options used when rendering the Roman numeral, plus
+ *   `alternatives` to collect the rejected readings.
+ * @returns The chord analysis.
+ * @example
+ * ```ts
+ * import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';
+ * analyzeChord(makeChord(7, 'dom7'), majorKey(0));
+ * // { function: 'dominant', borrowed: false, source: null, roman: 'V7', ... }
+ * analyzeChord(makeChord(9, 'dom7'), majorKey(0), { alternatives: true }).alternatives;
+ * // [{ label: 'tonic by scale degree', reason: '...' }, ...]
+ * ```
+ * @category Functional Harmony
+ */
+declare function analyzeChord(chord: ChordLike, key: KeyLike, opts?: AnalyzeChordOptions): ChordAnalysis;
+/**
+ * The secondary dominant (V7) that tonicizes a scale degree.
+ *
+ * @param targetDegree 1-based scale degree to tonicize: 5 is the dominant, so
+ *   `secondaryDominant(5, majorKey(0))` is the V of V.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns A dominant-seventh chord a fifth above the target's root.
+ * @throws If `targetDegree` is not an integer naming a degree in `key`.
+ * @see {@link secondaryDominantOf} to tonicize a chord that has no degree in
+ *   the key, or when no key is at hand.
+ * @category Functional Harmony
+ */
+declare function secondaryDominant(targetDegree: number, key: KeyLike): Chord;
+/**
+ * The secondary dominant (V7) that tonicizes a chord.
+ *
+ * {@link secondaryDominant} names its target by scale degree, so it only
+ * reaches the degrees a key actually has. This takes the target chord itself
+ * and needs no key at all, which is what lets a borrowed or chromatic target —
+ * bVI of a major key, a Neapolitan, any chord a modulation left behind — have
+ * its dominant built without first inventing a degree for it.
+ *
+ * A `rootSpelling` hint on the target moves with the root, so a flat-named
+ * target yields a flat-named dominant (Eb gives Bb7, not A#7).
+ *
+ * @param target The chord to tonicize, as a chord symbol, chord data, or a
+ *   `Chord`.
+ * @returns A dominant-seventh chord a perfect fifth above the target's root.
+ * @throws If the target's root pitch class is not a finite number.
+ * @example
+ * ```ts
+ * import { makeChord, secondaryDominantOf } from '@libraz/libcantus';
+ * secondaryDominantOf(makeChord(8, 'maj'));
+ * // { rootPc: 3, quality: 'dom7' } — Eb7 tonicizes the borrowed bVI of C major
+ * ```
+ * @category Functional Harmony
+ */
+declare function secondaryDominantOf(target: ChordLike): Chord;
+
+/**
+ * Pivot chords: the common ground two keys share for a modulation.
+ *
+ * Roots are pitch classes measured against the key tonic, so the two readings
+ * of a pivot follow from the chord's degree in each key rather than requiring a
+ * spelled key signature.
+ */
+
+/**
+ * A chord that is diatonic to two keys at once, with its reading in each.
+ *
+ * @category Functional Harmony
+ */
+type PivotChord = {
+    /** The shared chord. */
+    chord: Chord;
+    /** Roman numeral in the key being left. */
+    romanFrom: string;
+    /** Roman numeral in the key being entered. */
+    romanTo: string;
+};
+/**
+ * List the chords a modulation from `from` to `to` can pivot on.
+ *
+ * A pivot chord belongs to both keys at once, so it can be heard as a degree of
+ * the key being left and reinterpreted as a degree of the key being entered —
+ * the seamless way into the new key. Candidates are the diatonic triads of
+ * `from`, degrees 1 through 7, kept when every one of their pitch classes is
+ * also a scale tone of `to`; the result is ordered by their degree in `from`.
+ *
+ * Only triads are candidates. The textbook pivot is a triad: a seventh narrows
+ * the shared ground by a whole tone for no analytical gain, and the chord that
+ * turns the modulation is heard as a triad whether or not a seventh is played
+ * over it.
+ *
+ * A key that is not heptatonic has no diatonic triads at all — stacking scale
+ * thirds only lands on a triad over seven degrees — so such a `from` key yields
+ * an empty list rather than an error. A `to` key is only tested for membership,
+ * so it may be any scale; its numerals then follow the {@link chordToRoman}
+ * fallback of naming roots against the parallel major.
+ *
+ * @param from The key being left, as a key name, a key/scale, or a `Key`.
+ * @param to The key being entered, in any of the same forms.
+ * @returns The shared triads, ascending by their degree in `from`.
+ * @example
+ * ```ts
+ * import { majorKey, pivotChords } from '@libraz/libcantus';
+ * pivotChords(majorKey(0), majorKey(7)).map((p) => `${p.romanFrom}=${p.romanTo}`);
+ * // ['I=IV', 'iii=vi', 'V=I', 'vi=ii'] — C major into G major
+ * ```
+ * @category Functional Harmony
+ */
+declare function pivotChords(from: KeyLike, to: KeyLike): PivotChord[];
+
+/**
+ * The key as it changes over time.
+ *
+ * A piece that modulates has no single key, so a whole-piece answer is wrong
+ * for every bar after the modulation. This module answers instead with a run of
+ * regions, each carrying the key in force over one span, how it relates to the
+ * key before it, and — when chords are available — the chord the modulation
+ * turned on.
+ */
+
+/**
+ * A span of the piece over which one key is in force.
+ *
+ * @category Arrangement & Analysis
+ */
+type KeyRegion = {
+    /** First beat of the region. */
+    startBeat: number;
+    /** End of the region, exclusive. */
+    endBeat: number;
+    /** The key in force across the region. */
+    key: KeyScale;
+    /**
+     * How well the region's music fits the key, in [0, 1]: the correlation
+     * between the span's pitch-class distribution and the key's profile, with
+     * negative correlations reported as 0.
+     *
+     * One statistic whichever entry point built the region, so a threshold or a
+     * comparison means the same thing across them. Where the region came from
+     * chords rather than notes, the distribution is each chord's tones weighted
+     * by how long the chord holds.
+     */
+    confidence: number;
+    /**
+     * How this key relates to the previous region's — `'dominant'` for a move to
+     * the dominant, `'relative'` for a move to the relative minor, and so on.
+     * Absent on the first region, and absent when the two keys stand in none of
+     * the named relations.
+     *
+     * Never `'same'`: a region is the maximal span of one key, so consecutive
+     * regions never share one and a region carrying this field is a place the
+     * piece moved.
+     */
+    modulation?: KeyRelation;
+    /**
+     * The chord the modulation turned on, when one was identified. Only the
+     * chord-aware entry points fill this in: a pivot is a chord that reads in
+     * both keys, so it cannot be named without knowing which chord sounded.
+     */
+    pivot?: PivotChord;
+};
+/**
+ * Options shared by the key-region entry points.
+ *
+ * @category Arrangement & Analysis
+ */
+type KeyTimelineOptions = {
+    /**
+     * 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, downbeats and the metric
+     * accents the search discounts a modulation by all follow the signature in
+     * force at the beat in question, so a piece that changes meter is not read in
+     * the one it opened in.
+     *
+     * @defaultValue 4/4 throughout
+     */
+    meters?: MeterMap;
+    /**
+     * Expected length of one key area in beats; defaults to four bars of the
+     * opening meter.
+     *
+     * This is a prior, not a window: the longer a key is expected to hold, the
+     * more evidence a modulation needs before the search will report one. Keys
+     * change far more slowly than chords do, which is why the default is measured
+     * in bars rather than beats.
+     *
+     * @defaultValue four bars of the opening meter
+     */
+    expectedKeyBeats?: number;
+    /**
+     * Shortest key area the search may report, in beats; defaults to one bar of
+     * the opening meter. Values above `expectedKeyBeats` are clamped to it.
+     *
+     * @defaultValue one bar of the opening meter
+     */
+    minKeyBeats?: number;
+    /**
+     * End of the analyzed span in beats; defaults to the end of the last note or
+     * chord segment.
+     *
+     * @defaultValue the end of the input
+     */
+    totalBeats?: number;
+    /**
+     * Key profile the regions are scored against; defaults to `'krumhansl'`.
+     * Same meaning as the option of the same name on the key detectors.
+     *
+     * Every entry point reports `confidence` as the correlation between a
+     * region's pitch-class distribution and this profile, so the option is what
+     * that number is measured against. Which keys {@link detectModulations}
+     * reports is settled by how each chord reads in a key rather than by a
+     * pitch-class profile, so there the profile scores the answer without
+     * choosing it.
+     *
+     * @defaultValue `'krumhansl'`
+     */
+    profile?: KeyProfileName | KeyProfilePair;
+    /**
+     * Upper bound on the work this call may do.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * Infer where the key changes from raw notes.
+ *
+ * The span is examined in `minKeyBeats` slots. Each slot's pitch-class
+ * distribution is correlated against all 24 major and minor key profiles, and
+ * the run of keys that best explains the piece is chosen, paying a cost per
+ * modulation that rises with the distance travelled around the circle of
+ * fifths and falls on strong beats. Adjacent slots agreeing on a key become one
+ * region.
+ *
+ * The metric accents that discount a modulation follow the signature in force
+ * at the beat in question, so a piece that changes meter is read in the meter
+ * it is actually in. The first downbeat is beat 0, so a pickup is written at
+ * negative beats and its notes argue for the key like any others rather than
+ * falling outside the span.
+ *
+ * Pivot chords are not reported here: naming one requires knowing which chord
+ * sounded at the boundary, which raw notes do not say. Use
+ * {@link detectModulations} when a chord timeline is in hand.
+ *
+ * @param notes The notes to analyze (any number of tracks, flattened).
+ * @param opts Analysis options; see {@link KeyTimelineOptions}.
+ * @returns The key regions in time order; empty when nothing sounds.
+ * @example
+ * ```ts
+ * import { keyTimelineFromNotes } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 4 },
+ *   { pitch: 64, startBeat: 4, durationBeat: 4 },
+ * ];
+ * const regions = keyTimelineFromNotes(notes);
+ * regions[0]?.key; // the key in force at the start
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function keyTimelineFromNotes(notes: readonly NoteEvent[], opts?: KeyTimelineOptions): KeyRegion[];
+/**
+ * Infer where the key changes from a chord sequence, naming the pivot chords.
+ *
+ * Each chord segment is one slot of the same search {@link keyTimelineFromNotes}
+ * runs, scored by how well the chord belongs to each key rather than by a
+ * pitch-class profile — a dominant seventh argues for its key far more strongly
+ * than its three or four pitch classes alone would suggest. Where the key
+ * changes, the chord sounding into the boundary is reported as the pivot if it
+ * reads in both keys.
+ *
+ * The chords supply the slots, so `minKeyBeats` cannot size them as it does in
+ * the note path; a region shorter than it is folded into the neighbouring key
+ * that reads its chords best instead, which is the same guarantee — a shorter
+ * region is reported only where the analyzed span itself ends, or across a gap
+ * in the chords that no neighbour adjoins. `profile` scores each region's
+ * confidence, as it does in the note path, but takes no part in choosing which
+ * keys are reported: that is settled by how the chords read.
+ *
+ * @param chords The chord segments to analyze, in time order; pass a chord
+ *   timeline's `segments`.
+ * @param opts Analysis options; see {@link KeyTimelineOptions}.
+ * @returns The key regions in time order; empty when no chords were given.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes, detectModulations } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 4 },
+ *   { pitch: 64, startBeat: 0, durationBeat: 4 },
+ *   { pitch: 67, startBeat: 0, durationBeat: 4 },
+ * ];
+ * const { timeline } = chordTimelineFromNotes(notes);
+ * const regions = detectModulations(timeline.segments);
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function detectModulations(chords: readonly ChordSegment[], opts?: KeyTimelineOptions): KeyRegion[];
+/**
+ * The single key that holds for most of a run of regions.
+ *
+ * Callers that only want one key — a key signature to print, a scale to offer —
+ * need the one the piece spends the most time in, not the one it happens to
+ * start on.
+ *
+ * @param regions The regions to weigh, as returned by the key-region entry points.
+ * @returns The longest-held key, or null when there are no regions.
+ * @example
+ * ```ts
+ * import { keyTimelineFromNotes, prevailingKeyOf } from '@libraz/libcantus';
+ * const notes = [{ pitch: 60, startBeat: 0, durationBeat: 4 }];
+ * const key = prevailingKeyOf(keyTimelineFromNotes(notes));
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function prevailingKeyOf(regions: readonly KeyRegion[]): KeyScale | null;
+
+/**
+ * A suspension figure, named by the interval above the bass and the interval it
+ * resolves to.
+ *
+ * A figure is reported only when the suspended note forms the interval the
+ * figure names. A dissonance that resolves by step from anywhere else — a
+ * retardation rising a semitone from the seventh to the octave, say — is left
+ * unfigured rather than named after an interval it does not form.
+ *
+ * @category Arrangement & Analysis
+ */
+type SuspensionFigure = 'sus4-3' | 'sus6-5' | 'sus7-6' | 'sus9-8' | 'sus2-3';
+/**
+ * A theory annotation attached to a note.
+ *
+ * @category Arrangement & Analysis
+ */
+type TheoryLabel = {
+    kind: 'chordTone';
+    role: ChordToneRole;
+} | {
+    kind: 'tension';
+    degree: 9 | 11 | 13;
+} | {
+    kind: 'avoid';
+} | {
+    kind: 'passing';
+} | {
+    kind: 'neighbor';
+} | {
+    kind: 'suspension';
+    type: SuspensionFigure;
+    resolveTo: number;
+}
+/**
+ * A note leant on: reached by leap and given up by step the other way, with
+ * `resolveTo` naming the pitch it gives way to. The word is the one
+ * {@link MelodyToneRole} uses for the same figure, so a melody read through
+ * this layer and through the harmonizer comes back under one vocabulary
+ * rather than under two names for one note.
+ */
+ | {
+    kind: 'appoggiatura';
+    resolveTo: number;
+} | {
+    kind: 'anticipation';
+} | {
+    kind: 'escape';
+} | {
+    kind: 'needsResolution';
+    resolveTo: number;
+} | {
+    kind: 'leadingTone';
+    resolveTo: number;
+};
+/**
+ * A note with its theory labels and a short rationale.
+ *
+ * The labels describe the note against the chord sounding at its **onset**;
+ * they are not re-derived for the later chords a long note sustains across.
+ * `analyzeArrangement` does re-check every crossed chord change, and reports
+ * what it finds as conflicts, so a note labelled a chord tone here can still
+ * appear in `conflicts` at a later beat.
+ *
+ * The identity fields make an annotation mappable back to the caller's input:
+ * `originalIndex` is the note's position in the array that was passed in, and
+ * `trackIndex` is set by {@link analyzeArrangement}.
+ *
+ * @category Arrangement & Analysis
+ */
+type AnalyzedNote = {
+    noteId: number;
+    /** The note's index in the caller's own array, when the caller supplied one. */
+    originalIndex?: number;
+    /** The note's track, set by `analyzeArrangement`. */
+    trackIndex?: number;
+    pitch: number;
+    startBeat: number;
+    durationBeat: number;
+    labels: TheoryLabel[];
+    rationale?: string;
+};
+/**
+ * A single note in a monophonic voice: a {@link NoteEvent} with a stable id and,
+ * optionally, its index in the caller's original array.
+ *
+ * @category Arrangement & Analysis
+ */
+type VoiceNote = NoteEvent & {
+    id?: number;
+    originalIndex?: number;
+};
+/**
+ * A voice note whose id has been assigned, as {@link toVoiceNotes} returns and
+ * {@link analyzeArrangement} works in.
+ *
+ * @category Arrangement & Analysis
+ */
+type IdentifiedVoiceNote = VoiceNote & {
+    id: number;
+};
+/**
+ * A key that applies to the whole voice, or the key in force at a given beat.
+ *
+ * The callback form is what a piece that modulates needs: it is asked for the
+ * key at a specific beat, the same way a chord is asked for with `chordAtBeat`.
+ *
+ * @example
+ * ```ts
+ * import { majorKey } from '@libraz/libcantus';
+ * const wholePiece = majorKey(0); // C major throughout
+ * const modulating = (beat: number) => (beat < 8 ? majorKey(5) : majorKey(0));
+ * ```
+ * @category Arrangement & Analysis
+ */
+type KeyContext = KeyScale | ((beat: number) => KeyScale);
+/**
+ * Give plain note events the ids {@link analyzeVoice} reports back.
+ *
+ * The id is only an identity handle, so the array position serves; this exists
+ * so the mapping is a named call rather than a `map` every caller writes.
+ *
+ * @param events The note events, in time order.
+ * @returns The same notes as voice notes, each carrying its index as its id.
+ * @category Arrangement & Analysis
+ */
+declare function toVoiceNotes(events: readonly NoteEvent[]): IdentifiedVoiceNote[];
+/**
+ * Label every note of a voice with its theory roles.
+ *
+ * Each note is classified against the chord sounding at its beat. Chord tones
+ * get a role label; non-chord tones are matched, in order, as suspensions
+ * (prepared by an identical consonant pitch and resolving by step), passing
+ * tones, neighbors, anticipations, appoggiaturas (approached by leap and
+ * resolving by step the other way), and escape tones, then fall back to
+ * tension, avoid, or an unresolved-dissonance label. The figures are named as
+ * {@link classifyMelodyTones} names them, so a caller reading a melody through
+ * both layers gets one vocabulary; that classifier weighs the metre as well,
+ * which this one is not given, so it is the stricter of the two. Leading-tone resolutions are noted
+ * additionally, judged against the key in force at the beat the resolution
+ * lands on, so a modulation is heard from its new tonic.
+ *
+ * The voice is expected to be monophonic (one note at a time). Notes sharing an
+ * onset are treated as simultaneous cluster members, not melodic neighbors, so
+ * they receive no melodic labels (suspension, passing, neighbor, anticipation,
+ * escape) — only harmonic ones. Callers with truly polyphonic material should
+ * split it into monophonic sub-voices first, as `analyzeArrangement` does.
+ *
+ * @param voice The monophonic voice, in time order. A note without an `id` is
+ *   identified by its position, so plain note events can be passed straight in.
+ * @param chordAtBeat Chord sounding at a given beat, or null.
+ * @param key Key context for leading-tone detection: a single {@link KeyScale}
+ *   covering the whole voice, or a callback giving the key in force at a given
+ *   beat, for music that modulates.
+ * @param otherVoicesAtBeat Other sounding voices at a given beat; defaults to
+ *   none, which is the whole story for a solo line.
+ * @returns One annotation per input note.
+ * @example
+ * ```ts
+ * import { analyzeVoice, makeChord, majorKey } from '@libraz/libcantus';
+ * const voice = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+ *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+ * ];
+ * const cMajor = makeChord(0, 'maj');
+ * const labels = analyzeVoice(voice, () => cMajor, majorKey(0));
+ * labels; // one AnalyzedNote per input note, in the same order
+ * // A voice that modulates to C major at beat 2:
+ * analyzeVoice(voice, () => cMajor, (beat) => (beat < 2 ? majorKey(5) : majorKey(0)));
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function analyzeVoice(voice: readonly VoiceNote[], chordAtBeat: (beat: number) => Chord | null, key: KeyContext, otherVoicesAtBeat?: (beat: number) => VoiceSnapshot[]): AnalyzedNote[];
+
+/**
+ * A beat-indexed sequence of chord segments.
+ *
+ * @category Arrangement & Analysis
+ */
+type ChordTimeline = {
+    /** The chord sounding at a beat, or null when no segment covers it. */
+    at: (beat: number) => Chord | null;
+    segments: ChordSegment[];
+};
+/**
+ * Build a chord timeline from placed chords.
+ *
+ * Each chord spans from its `startBeat` to the next chord's `startBeat`; the last
+ * chord runs to `totalBeats`. Segments with no positive length (from duplicate
+ * onsets or a last chord at or past `totalBeats`) are dropped. `at(beat)` returns
+ * the covering segment's chord, or null when the beat lies outside every segment.
+ *
+ * @param chords Placed chords in time order.
+ * @param totalBeats End of the timeline in beats.
+ * @returns A queryable chord timeline.
+ * @category Arrangement & Analysis
+ */
+declare function chordTimelineFromChords(chords: readonly ChordSpan[], totalBeats: number): ChordTimeline;
+/**
+ * How {@link chordTimelineFromNotes} decides where one chord ends and the next
+ * begins.
+ *
+ * `'dynamic'` searches for the boundaries the notes actually imply, so a bar
+ * holding two chords yields two segments and a bar holding one yields one.
+ * `'grid'` cuts a segment every `harmonicRhythm` beats regardless of what
+ * sounds, which is only right when the harmonic rhythm is known to be fixed.
+ *
+ * @category Arrangement & Analysis
+ */
+type ChordSegmentation = 'dynamic' | 'grid';
+/**
+ * Options controlling {@link chordTimelineFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ChordTimelineOptions = {
+    /**
+     * Key context held across the whole span. Omit it to have the key searched
+     * for over time with {@link keyTimelineFromNotes}, which is what lets a piece
+     * that modulates be analysed against the key actually in force.
+     */
+    key?: KeyScale;
+    /**
+     * 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, downbeats and metric
+     * weight all follow the signature in force at the beat in question, so a
+     * piece that changes meter is not read in the one it opened in.
+     *
+     * @defaultValue 4/4 throughout
+     */
+    meters?: MeterMap;
+    /**
+     * Length of the pickup in beats, when the piece starts with one.
+     *
+     * The first downbeat is beat 0 whatever precedes it, so an upbeat is written
+     * at negative beats — a one-beat pickup in 4/4 sounds at beat -1. 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;
+    /**
+     * Where chord boundaries may fall; defaults to `'dynamic'`.
+     *
+     * @defaultValue `'dynamic'`
+     */
+    segmentation?: ChordSegmentation;
+    /**
+     * Expected chord length in beats; defaults to the length of the opening bar.
+     *
+     * Under `'grid'` segmentation this is the exact window length. Under
+     * `'dynamic'` it is a prior: the longer a chord is expected to last, the more
+     * evidence a change needs before the search will place one.
+     *
+     * @defaultValue the length of the opening bar
+     */
+    harmonicRhythm?: number;
+    /**
+     * Shortest chord the `'dynamic'` search may report, in beats; defaults to one
+     * beat. Lower it to catch changes on off-beats, at the cost of proportionally
+     * more work. Values above `harmonicRhythm` are clamped to it, and the option
+     * is ignored under `'grid'` segmentation.
+     *
+     * The search reads it as a resolution rather than as an exact slot length: it
+     * rounds down to a whole division of `harmonicRhythm`, so `0.6` against a
+     * four-beat chord is read in sevenths of it. That keeps the beats one
+     * expected chord gives way to the next on the grid whatever resolution is
+     * asked for, and with them every change a coarser setting found.
+     *
+     * @defaultValue `1`
+     */
+    minChordBeats?: number;
+    /**
+     * End of the analyzed 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 — 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;
+};
+/**
+ * The result of {@link chordTimelineFromNotes}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ChordTimelineResult = {
+    /** The inferred timeline, with adjacent identical chords merged. */
+    timeline: ChordTimeline;
+    /**
+     * The key regions the analysis ran against, in time order. A piece that does
+     * not modulate yields one region covering the whole span; a given `key`
+     * yields exactly one region too, since the caller has already answered the
+     * question. Either way the first region starts where the analysis does, which
+     * is before beat 0 when the piece opens with a pickup. Pivot chords are filled
+     * in where the chords support one.
+     */
+    keys: KeyRegion[];
+    /**
+     * The key held longest across {@link ChordTimelineResult.keys} — the one to
+     * print on a key signature or hand to a generator that takes a single key.
+     */
+    prevailingKey: KeyScale;
+    /** One confidence value in [0, 1] per segment, in segment order. */
+    segmentConfidence: number[];
+};
+/**
+ * Infer a chord timeline from raw multi-track notes.
+ *
+ * Chord boundaries are searched for rather than assumed: the span is examined
+ * in `minChordBeats` slots, and the change points that best explain the notes
+ * are chosen, trading each slot's harmonic fit against a cost per chord change
+ * that a strong beat discounts. A bar holding two chords therefore yields two
+ * segments and a bar holding one yields one, without the caller having to know
+ * the harmonic rhythm in advance. Pass `segmentation: 'grid'` to cut a segment
+ * every `harmonicRhythm` beats instead.
+ *
+ * Each settled segment's chord is inferred from a pitch-class weight histogram
+ * of the notes overlapping it (weight = overlap duration x velocity x
+ * metric-accent bonus for onsets in the segment). Adjacent segments carrying
+ * the identical chord are merged; a stretch with no notes produces no segment,
+ * so `at(beat)` returns null there. Each segment carries a confidence in [0, 1]
+ * — the fraction of its weight explained by chord tones, reduced when the match
+ * is inexact, and duration-weighted across anything merged into it.
+ *
+ * Notes with a zero or negative duration never sound, so they are dropped at
+ * ingest: they contribute to neither the key inference, the span, nor any
+ * window's histogram.
+ *
+ * Bar lines, downbeats and the metric accents the boundary search discounts by
+ * all follow the signature in force at the beat in question, so a piece that
+ * changes meter is read in the meter it is actually in. The first downbeat is
+ * beat 0, so a pickup is written at negative beats and the search still finds
+ * the bar lines where the score has them.
+ *
+ * @param notes The notes to analyze (any number of tracks, flattened).
+ * @param opts Analysis options; see {@link ChordTimelineOptions}.
+ * @returns The inferred timeline, the key regions it ran against, the key that
+ *   prevails across them, and per-segment confidences.
+ * @throws If `harmonicRhythm` is not positive.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 2 }, // C
+ *   { pitch: 64, startBeat: 0, durationBeat: 2 }, // E
+ *   { pitch: 67, startBeat: 0, durationBeat: 2 }, // G
+ * ];
+ * const { timeline, prevailingKey } = chordTimelineFromNotes(notes);
+ * timeline.at(0); // the chord inferred over beat 0, or null
+ * prevailingKey; // the key held longest across the piece
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function chordTimelineFromNotes(notes: readonly NoteEvent[], opts?: ChordTimelineOptions): ChordTimelineResult;
+/**
+ * A cadence found between two consecutive timeline segments.
+ *
+ * @category Arrangement & Analysis
+ */
+type CadenceHit = {
+    /** The beat where the cadence arrives (the second chord's onset). */
+    atBeat: number;
+    /**
+     * The cadence formed by the pair. Its `type` is never null: a pair forming no
+     * cadence is not a hit. A timeline names no voicing, so `strength` is null for
+     * an authentic cadence whose chords are both in root position.
+     */
+    cadence: CadenceResult;
+    from: Chord;
+    to: Chord;
+};
+/**
+ * Find cadences between consecutive segments of a chord timeline.
+ *
+ * Each temporally adjacent segment pair is classified with
+ * {@link detectCadence}; pairs forming no cadence are skipped. Segments
+ * separated by a gap (a rest in the timeline) are not a chord-to-chord
+ * progression, so they are never paired.
+ *
+ * The segment before the pair is passed as the approach, which is what tells a
+ * cadential six-four from an inverted tonic: `I I64 V I` is one cadence
+ * arriving on the final tonic, described from the six-four the dominant was
+ * already sounding under, rather than a half cadence onto the dominant
+ * followed by an authentic one. A passing six-four — one whose dominant is not
+ * what follows it — is unaffected, and so is a pair whose predecessor is
+ * separated from it by a rest.
+ *
+ * @param timeline The chord timeline to scan.
+ * @param key The prevailing key, or the key in force at a given beat.
+ * @returns The cadences found, in time order.
+ * @example
+ * ```ts
+ * import { chordTimelineFromNotes, detectCadences } from '@libraz/libcantus';
+ * const notes = [
+ *   { pitch: 67, startBeat: 0, durationBeat: 4 }, // G, a dominant
+ *   { pitch: 60, startBeat: 4, durationBeat: 4 }, // C, the tonic
+ * ];
+ * const { timeline, prevailingKey } = chordTimelineFromNotes(notes);
+ * const cadences = detectCadences(timeline, prevailingKey);
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function detectCadences(timeline: ChordTimeline, key: KeyContext): CadenceHit[];
+
+export { type AnalyzeChordOptions as A, type BorrowedSource as B, type CadenceHit as C, type DetectCadenceOptions as D, type ExplainRomanOptions as E, isMinorKey as F, keyTimelineFromNotes as G, type HarmonicFunction as H, type IdentifiedVoiceNote as I, pivotChords as J, type KeyContext as K, prevailingKeyOf as L, romanToChord as M, secondaryDominant as N, secondaryDominantOf as O, type PivotChord as P, toVoiceNotes as Q, type RejectedCandidate as R, type SuspensionFigure as S, type TheoryLabel as T, type VoiceNote as V, type AnalyzedNote as a, type CadenceResult as b, type ChordAnalysis as c, type ChordSegmentation as d, type ChordTimeline as e, type ChordTimelineOptions as f, type ChordTimelineResult as g, type ChordToRomanOptions as h, type KeyProfileName as i, type KeyProfilePair as j, type KeyRegion as k, type KeyTimelineOptions as l, type RomanExplanation as m, analyzeChord as n, analyzeVoice as o, borrowedSource as p, chordTimelineFromChords as q, chordTimelineFromNotes as r, chordToRoman as s, detectCadence as t, detectCadences as u, detectModulations as v, explainRoman as w, functionOf as x, isBorrowedChord as y, isDiatonic as z };