@libraz/libcantus 1.2.0 → 1.4.0

package/dist/{index-CJBBiAmU.d.ts → types-7mGFwvMm.d.ts}

@@ -1,6 +1,6 @@
-import { c as ChordLike, K as KeyLike, i as ChordToneRole, r as SpelledKeyLike, b as Chord, n as ResolvedKey, j as KeyRelation, e as ChordSegment, V as VoiceSnapshot, g as ChordSpan } from './coerce-DP0vYu-x.js';
-import { b as MeterLike } from './index-CL4b4gUQ.js';
-import { h as NoteEvent, e as KeyScale } from './index-Cy15oTvh.js';
+import { b as MeterLike, T as TimeSignature, c as MeterMap } from './index-Bf0Sv8a9.js';
+import { c as ChordLike, K as KeyLike, i as ChordToneRole, r as SpelledKeyLike, b as Chord, n as ResolvedKey, j as KeyRelation, e as ChordSegment, V as VoiceSnapshot, g as ChordSpan } from './coerce-CUhHc3Tu.js';
+import { h as NoteEvent, e as KeyScale, S as SpelledInterval } from './index-C9MYbuKS.js';
 
 /**
  * The vocabulary the analyze layer explains itself in.
@@ -119,21 +119,31 @@ declare function borrowedSource(chord: ChordLike, key: KeyLike): BorrowedSource;
  * spelled key signature.
  */
 
+/**
+ * The named cadence types {@link detectCadence} classifies a chord pair as.
+ *
+ * @category Functional Harmony
+ */
+declare const CADENCE_TYPES: readonly ["authentic", "plagal", "half", "deceptive", "phrygian", "modal"];
+/**
+ * The cadence a chord pair forms.
+ *
+ * `'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'`.
+ *
+ * @category Functional Harmony
+ */
+type CadenceType = (typeof CADENCE_TYPES)[number];
 /**
  * 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;
+    /** The cadence the chord pair forms, or null when it forms none. */
+    type: CadenceType | null;
     /**
      * How conclusive an authentic cadence is: `'perfect'` when it is a PAC,
      * `'imperfect'` when it is an IAC.
@@ -336,6 +346,8 @@ declare function detectCadence(from: ChordLike, to: ChordLike, key: KeyLike, opt
  * @param text The Roman numeral.
  * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
  * @returns The chord.
+ * @throws If `key` names no key, `text` is not a string, or it is no numeral
+ *   this reads.
  * @example
  * ```ts
  * import { romanToChord, majorKey } from '@libraz/libcantus';
@@ -358,7 +370,7 @@ type ChordToRomanOptions = {
      * 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 in three cases, where the
+     * builds as the applied numerals they are, except in four cases, where the
      * numeral names the root against the home key as it does with this off:
      *
      * - The target degree carries no perfect fifth: nothing tonicizes a
@@ -369,6 +381,9 @@ type ChordToRomanOptions = {
      * - The chord is diatonic to the key, which keeps the function of its degree
      *   rather than tonicizing another. `G7` is `VII7` in A minor and `I7` in C
      *   mixolydian, not `V7/III` and `V7/IV`.
+     * - The chord is borrowed from the parallel mode, which sounds its own degree:
+     *   the Picardy tonic and the major IV of a minor key are `I` and `IV`, not
+     *   `V/iv` and `V/VII`.
      */
     applied?: boolean;
     /**
@@ -499,12 +514,18 @@ declare function explainRoman(chord: ChordLike, key: KeyLike, opts?: ExplainRoma
  * spelled key signature.
  */
 
+/**
+ * The harmonic functions {@link functionOf} can assign.
+ *
+ * @category Functional Harmony
+ */
+declare const HARMONIC_FUNCTIONS: readonly ["tonic", "subdominant", "dominant"];
 /**
  * The three broad harmonic functions of tonal music.
  *
  * @category Functional Harmony
  */
-type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
+type HarmonicFunction = (typeof HARMONIC_FUNCTIONS)[number];
 /**
  * Whether a key's scale has a minor third and no major third (a minor key).
  *
@@ -643,13 +664,14 @@ declare function analyzeChord(chord: ChordLike, key: KeyLike, opts?: AnalyzeChor
  * @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.
+ * @returns A dominant-seventh chord a fifth above the target's root, spelled the
+ *   way the key writes it (in Ab major the V of IV is Eb7, not D#7).
  * @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;
+declare function secondaryDominant(targetDegree: number, key: SpelledKeyLike): Chord;
 /**
  * The secondary dominant (V7) that tonicizes a chord.
  *
@@ -717,7 +739,8 @@ type PivotChord = {
  * 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 from The key being left, as a key name, a key/scale, or a `Key`; the
+ *   shared chords are spelled the way it writes them.
  * @param to The key being entered, in any of the same forms.
  * @returns The shared triads, ascending by their degree in `from`.
  * @example
@@ -728,7 +751,7 @@ type PivotChord = {
  * ```
  * @category Functional Harmony
  */
-declare function pivotChords(from: KeyLike, to: KeyLike): PivotChord[];
+declare function pivotChords(from: SpelledKeyLike, to: SpelledKeyLike): PivotChord[];
 
 /**
  * The key as it changes over time.
@@ -1107,7 +1130,9 @@ declare function toVoiceNotes(events: readonly NoteEvent[]): IdentifiedVoiceNote
  * 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.
+ * split it into monophonic sub-voices first, as `analyzeArrangement` does. A
+ * note of zero length sounds nothing: it gets no melodic labels and is no other
+ * note's neighbour.
  *
  * @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.
@@ -1116,7 +1141,8 @@ declare function toVoiceNotes(events: readonly NoteEvent[]): IdentifiedVoiceNote
  *   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.
+ *   none, which is the whole story for a solo line: a suspension's dissonance
+ *   is then judged against the chord.
  * @returns One annotation per input note.
  * @example
  * ```ts
@@ -1142,7 +1168,11 @@ declare function analyzeVoice(voice: readonly VoiceNote[], chordAtBeat: (beat: n
  * @category Arrangement & Analysis
  */
 type ChordTimeline = {
-    /** The chord sounding at a beat, or null when no segment covers it. */
+    /**
+     * The chord sounding at a beat, or null when no segment covers it. An
+     * inferred timeline covers a rest shorter than its harmonic rhythm with the
+     * chord around it; see {@link chordTimelineFromNotes}.
+     */
     at: (beat: number) => Chord | null;
     segments: ChordSegment[];
 };
@@ -1235,13 +1265,14 @@ type ChordTimelineOptions = {
      * 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.
+     * unset to accept any onset within ±`Number.MAX_SAFE_INTEGER` (2^53 - 1).
      *
      * @defaultValue no declared pickup
      */
     pickupBeats?: number;
     /**
-     * Where chord boundaries may fall; defaults to `'dynamic'`.
+     * Where chord boundaries may fall; defaults to `'dynamic'`. Any other value
+     * is an input error.
      *
      * @defaultValue `'dynamic'`
      */
@@ -1332,8 +1363,13 @@ type ChordTimelineResult = {
  * 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 identical chord are merged. Under `'dynamic'` segmentation a silence at
+ * least `harmonicRhythm` long produces no segment, so `at(beat)` returns null
+ * there, while a shorter rest is absorbed into the chord around it — a C triad
+ * for two beats, two beats of rest and a G triad read C over beats 0-4. Under `'grid'` any
+ * window with nothing sounding produces no segment. A window whose notes give
+ * fewer than two tones of any chord produces none either: a lone pitch class
+ * names no chord. 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.
  *
@@ -1351,7 +1387,8 @@ type ChordTimelineResult = {
  * @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.
+ * @throws If `harmonicRhythm` is not positive, or `segmentation` names neither
+ *   mode.
  * @example
  * ```ts
  * import { chordTimelineFromNotes } from '@libraz/libcantus';
@@ -1406,10 +1443,9 @@ type CadenceHit = {
  * @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 triad = (pitches: number[], startBeat: number) =>
+ *   pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
+ * const notes = [...triad([55, 59, 62], 0), ...triad([48, 52, 55], 4)]; // G, then C
  * const { timeline, prevailingKey } = chordTimelineFromNotes(notes);
  * const cadences = detectCadences(timeline, prevailingKey);
  * ```
@@ -1417,4 +1453,1147 @@ type CadenceHit = {
  */
 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, isDiatonic as F, isMinorKey as G, type HarmonicFunction as H, type IdentifiedVoiceNote as I, keyTimelineFromNotes as J, type KeyContext as K, pivotChords as L, prevailingKeyOf as M, romanToChord as N, secondaryDominant as O, type PivotChord as P, secondaryDominantOf as Q, type RejectedCandidate as R, type SuspensionFigure as S, type TheoryLabel as T, toVoiceNotes as U, 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, assertChordTimeline as p, borrowedSource as q, chordTimelineFromChords as r, chordTimelineFromNotes as s, chordToRoman as t, detectCadence as u, detectCadences as v, detectModulations as w, explainRoman as x, functionOf as y, isBorrowedChord as z };
+/**
+ * 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?: MeterLike;
+    /**
+     * 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?: MeterLike;
+    /**
+     * 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[];
+
+/**
+ * The recurring cells a melody is built from.
+ *
+ * A motif is the interval contour plus the rhythmic profile, so every statement
+ * of it carries the same identity however far it has been transposed or however
+ * wide its note values are written. What this module does is find them: every
+ * window of the melody is reduced to that identity, windows that agree are
+ * grouped, and a group stated often enough is a motif.
+ */
+
+/**
+ * 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;
+};
+/**
+ * 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. Notes struck together
+ * are read as one event, the highest of them standing for it, so a chord is
+ * reduced to its top voice rather than read as a line of its own. 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}.
+ *
+ * The cell is expected to be monophonic, as {@link analyzeVoice} expects a voice
+ * to be. Notes struck together are read as one event, the highest of them
+ * standing for it, so a chord is reduced to its top voice rather than read as a
+ * line of its own.
+ *
+ * @param notes The cell, in time order. Notes that never sound are dropped, and
+ *   notes sharing an onset are folded to their top voice.
+ * @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;
+
+/**
+ * What every reading of a melody has to agree on first.
+ *
+ * A melody is compared, named and classified by three modules here, and all
+ * three start from the same two questions: which notes sound, in what order,
+ * and what the gaps between their onsets are. Answered separately they would
+ * drift — one reading folding a chord to its top voice and another not — so
+ * they are answered once, here.
+ */
+
+/**
+ * Anything that can be read as a melodic line: a motif, or plain note events.
+ *
+ * @category Arrangement & Analysis
+ */
+type MelodicPhrase = MotifData | readonly NoteEvent[];
+
+/**
+ * The shape of a line: which way it moves, and what that adds up to.
+ *
+ * A contour is the melody with its pitches forgotten — the sequence of ups and
+ * downs alone — which is what lets a phrase be called an arch whatever key it
+ * is in and whatever intervals it is built from.
+ */
+
+/**
+ * Step direction between two consecutive notes.
+ *
+ * @category Arrangement & Analysis
+ */
+type ContourDirection = 'up' | 'down' | 'same';
+/**
+ * The overall shapes a line can be read as.
+ *
+ * @category Arrangement & Analysis
+ */
+declare const MELODIC_CONTOUR_SHAPES: readonly ["arch", "ascending", "descending", "wave", "static"];
+/**
+ * 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 = (typeof MELODIC_CONTOUR_SHAPES)[number];
+/**
+ * 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, and -1 for a line with no notes. */
+    peakIndex: number;
+    /** Index of the lowest note; ties keep the earliest, and -1 for a line with no notes. */
+    troughIndex: number;
+    /** Semitone distance from the lowest note to the highest. */
+    range: number;
+    /** Why the line was given that shape. */
+    rationale: string;
+};
+/**
+ * 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.
+ *
+ * The line is expected to be monophonic, as {@link analyzeVoice} expects a voice
+ * to be; split polyphonic material into lines first. Notes struck together are
+ * read as one event, the highest of them standing for it — a chord and the note
+ * after it trace one step, not a climb through the chord — so a piano part read
+ * whole answers for its top voice rather than for a line no one plays.
+ *
+ * @param notes The line: a motif, or plain note events. Notes that never sound
+ *   are dropped, and notes sharing an onset are folded to their top voice.
+ * @returns The directions, the shape, the peak and trough, and a rationale. A
+ *   line with no sounding notes is static with a range of 0, and its peak and
+ *   trough are -1: there is no note for them to point at.
+ * @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;
+
+/**
+ * The transformation between two statements of a motif, named.
+ *
+ * Two cells stand in a relation when one is the other put through a device the
+ * repertoire has a name for — repetition, transposition, inversion, retrograde,
+ * augmentation — and naming it is what turns a pair of similar phrases into an
+ * account of how the second was made from the first.
+ */
+
+/**
+ * The named transformations {@link relateMotifs} can report between two motif
+ * statements.
+ *
+ * @category Arrangement & Analysis
+ */
+declare const MOTIF_RELATION_KINDS: readonly ["repetition", "transposition", "tonalTransposition", "inversion", "retrograde", "retrogradeInversion", "augmentation", "diminution"];
+/**
+ * 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 = (typeof MOTIF_RELATION_KINDS)[number];
+/**
+ * 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.
+     *
+     * Measured in the direction the relation names, so a retrograde that kept
+     * every note value reports 1 however uneven those values are: it is compared
+     * against the model played backwards, not against the model as written.
+     */
+    timeRatio: number;
+    /** Why the pair was given that name. */
+    rationale: string;
+};
+/**
+ * The part of a {@link MotifRelation} that names the transformation itself,
+ * without the rationale prose that explains it.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifRelationSummary = Pick<MotifRelation, 'kind' | 'sequence' | 'semitones' | 'degrees' | 'timeRatio'>;
+/**
+ * Name how two statements of a motif relate.
+ *
+ * The two are compared as shapes, not as pitches: the interval sequences say
+ * which transformations could name the pair and the onset gaps say which of
+ * them does, so a statement a fourth higher in doubled note values is
+ * recognised for what it is, and a cell that reads as both an inversion and a
+ * retrograde is named by the way its rhythm runs rather than by which name came
+ * to hand first. An evenly timed cell runs the same both ways, so there the
+ * reading that needs no transposition wins: a cell played backwards on its own
+ * pitches is a retrograde. A pair whose rhythms correspond in neither direction — the same
+ * way round for a repetition or a transposition, the model played backwards for
+ * a retrograde, note values and all — 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 keyLike Key context for the tonal reading. Without one that reading is
+ *   unavailable, and a statement holding only diatonically is left unnamed
+ *   unless its interval pattern also fits a member of the retrograde family, in
+ *   which case it is named there: a triad restated a degree higher swaps two
+ *   adjacent interval sizes, which is what a retrograde inversion does to it as
+ *   well, and equal note values read the same way round in both directions, so
+ *   the notes alone cannot separate the two. A key separates them.
+ * @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, keyLike?: SpelledKeyLike): MotifRelation | null;
+
+/**
+ * How the statements of a melody's motifs derive from one another.
+ *
+ * {@link extractMotifs} groups statements into motifs; this reads across that
+ * grouping and asks, for every statement after the first, which earlier
+ * statement it most plausibly grew out of. The answer is a forest rather than a
+ * graph proper — every statement has at most one parent — because a derivation
+ * only ever has one source, however many statements it could be heard against.
+ */
+
+/**
+ * Options controlling {@link motifGraph}.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifGraphOptions = {
+    /** Key context for the tonal reading `relateMotifs` can offer. */
+    key?: SpelledKeyLike;
+    /**
+     * Lower bound on `melodicSimilarity` for a pair with no named transformation
+     * to still be drawn as a variation.
+     *
+     * @defaultValue 0.75
+     */
+    variationThreshold?: number;
+    /**
+     * Upper bound on the work this call may do.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * One statement of a motif, as a node of {@link MotifGraph}.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifGraphNode = {
+    /** Index into the `motifs` array this statement belongs to. */
+    motif: number;
+    /** Index into that motif's `occurrences`. */
+    occurrence: number;
+    /** Onset of the statement's first note. */
+    startBeat: number;
+    /** End of the statement's last note, exclusive. */
+    endBeat: number;
+};
+/**
+ * The derivation drawn from one statement to a later one.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifGraphEdge = {
+    /** Index of the preceding node this statement derives from. */
+    from: number;
+    /** Index of the derived node. */
+    to: number;
+    /** The named transformation, or null when none explains the pair. */
+    relation: MotifRelationSummary | null;
+    /** `melodicSimilarity` between the two statements. */
+    similarity: number;
+};
+/**
+ * How a melody's motif statements derive from one another.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifGraph = {
+    /** Every statement of every motif, ordered by `startBeat` then by `motif`. */
+    nodes: MotifGraphNode[];
+    /**
+     * The derivation drawn to each node from an earlier one, ordered by `to`.
+     * Every node has at most one edge into it, so the edges describe a forest.
+     */
+    edges: MotifGraphEdge[];
+};
+/**
+ * Read a melody's motif statements as a derivation forest.
+ *
+ * Every statement after the first is compared against every statement that
+ * precedes it: the pair {@link relateMotifs} can name outranks any it cannot,
+ * the closest-scoring precedent among equals outranks the rest, and a
+ * statement whose best precedent is neither named nor close enough by
+ * `melodicSimilarity` is a root — new material, not a derivation of what came
+ * before it. The derivation traced this way explains a subject restated,
+ * transposed, inverted, augmented, or loosely varied by what it grew out of,
+ * and leaves a truly new idea unattached rather than forcing it onto whatever
+ * came earliest.
+ *
+ * `motifs` is read against `line` rather than against its own prime
+ * statements: an occurrence's notes can differ from the motif's first
+ * statement in duration even where their intervals and onset gaps agree, and a
+ * retrograde reading depends on that duration. So every occurrence is read
+ * back off `line` and named fresh, occurrence to occurrence.
+ *
+ * @param line The melody `motifs` was extracted from. Notes that never sound
+ *   are dropped, exactly as {@link extractMotifs} drops them, so the two agree
+ *   on which note an occurrence's `noteIndex` addresses.
+ * @param motifs The motifs to graph, as {@link extractMotifs} reports them.
+ * @param opts Key context, the variation threshold, and a work budget; see
+ *   {@link MotifGraphOptions}.
+ * @returns The statements as nodes, and the derivation drawn to each from an
+ *   earlier one.
+ * @example
+ * ```ts
+ * import { extractMotifs, motifGraph } 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 graph = motifGraph(notes, extractMotifs(notes));
+ * graph.edges[0]?.relation?.kind; // 'transposition'
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function motifGraph(line: readonly NoteEvent[], motifs: readonly MotifData[], opts?: MotifGraphOptions): MotifGraph;
+
+/**
+ * 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 places a chord can hold in a progression.
+ *
+ * @category Arrangement & Analysis
+ */
+declare const REDUCTION_LEVELS: readonly ["structural", "passing", "neighbor"];
+/**
+ * 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 = (typeof REDUCTION_LEVELS)[number];
+/**
+ * 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: a
+ * chord is the frame when it outlasts the chords around it — its length beats
+ * the median of the other chords' — whatever function it carries. Nothing
+ * outlasts anything in an even harmonic rhythm, so a loop or a vamp protects no
+ * chord by length and the two figures decide, as they do under either reading.
+ *
+ * @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[];
+
+/**
+ * Where a line places its onsets against the meter: how dense they are, which
+ * metric positions they favour, and how far they push against the beat.
+ *
+ * A phrase and a whole piece are read the same way — a run of onsets over a
+ * span of beats — so a single reading serves both a melodic line and a
+ * harmonic-rhythm reading of chord changes turned into onsets of their own.
+ */
+
+/**
+ * Options for {@link analyzeRhythm}.
+ *
+ * @category Arrangement & Analysis
+ */
+type RhythmAnalysisOptions = {
+    /**
+     * 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?: MeterLike;
+    /**
+     * The meter as it changes over the span, so a piece that changes metre is
+     * read against its own bar lines throughout.
+     *
+     * @defaultValue 4/4 throughout
+     */
+    meters?: MeterLike;
+    /**
+     * 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;
+};
+/**
+ * How a line's onsets sit against one time signature: which slot of its bar
+ * they favour, mass-normalized.
+ *
+ * @category Arrangement & Analysis
+ */
+type BarPositionProfile = {
+    /** The time signature this profile's bar is read in. */
+    ts: TimeSignature;
+    /** Slots in one bar of `ts`, at one twelfth of a quarter-note beat each. */
+    slotsPerBar: number;
+    /** Onset mass per slot, in bar order starting at the downbeat; sums to 1. */
+    shares: number[];
+    /** Onsets read under this signature. */
+    onsets: number;
+};
+/**
+ * How a line places its onsets against the meter.
+ *
+ * @category Arrangement & Analysis
+ */
+type RhythmAnalysis = {
+    /** First beat of the analysed span. */
+    startBeat: number;
+    /** End of the analysed span, exclusive. */
+    endBeat: number;
+    /** The span's length in bars, counted across any meter changes it crosses. */
+    bars: number;
+    /** Onsets read, folding onsets within 0.05 beat of one another into one. */
+    onsets: number;
+    /** Onsets per bar; 0 for a span with no bars. */
+    onsetDensity: number;
+    /** Onsets per bar of the span, one entry per bar including a part bar at either end. */
+    barOnsets: number[];
+    /**
+     * Onset mass by rhythmic level, indexed 0–5: 0 off the first pulse
+     * subdivision, 1 on it, 2–5 on a main pulse (`metricWeight` plus 2). Sums to 1.
+     */
+    onsetLevels: number[];
+    /** Onset placement within the bar, one profile per time signature the span reads under. */
+    barPositions: BarPositionProfile[];
+    /** Inter-onset-interval mass, binned to {@link RHYTHM_IOI_BINS}; sums to 1. */
+    interOnsetShares: number[];
+    /** Share of the span during which nothing sounds. */
+    restRatio: number;
+    /** Longuet-Higgins & Lee syncopation, in [0, 1]. */
+    syncopation: number;
+    /** Share of onsets further than 1/32 beat from the nearest grid slot. */
+    offGridRatio: number;
+    /** Why the line reads as it does. */
+    rationale: string;
+};
+/**
+ * Inter-onset intervals, in quarter-note beats, at half-octave steps from a
+ * sixteenth of a beat to sixteen beats.
+ *
+ * @category Arrangement & Analysis
+ */
+declare const RHYTHM_IOI_BINS: readonly number[];
+/**
+ * How a line places its onsets against the meter: density, metric placement,
+ * interval spacing, rest, and Longuet-Higgins & Lee syncopation.
+ *
+ * Onsets within 0.05 beat of one another read as one, and an
+ * onset further than 1/32 beat from the nearest twelfth-of-a-beat slot is read
+ * as off grid; every onset is moved to its nearest slot for everything
+ * downstream of it, so an unquantized line reads a real but reduced
+ * syncopation rather than a spurious one from a grid it never intended to sit
+ * on.
+ *
+ * @param notes The line's notes, in any order. Notes that never sound
+ *   (`durationBeat <= 0`) are dropped.
+ * @param opts Analysis options; see {@link RhythmAnalysisOptions}.
+ * @returns The rhythm reading; see {@link RhythmAnalysis}.
+ * @example
+ * ```ts
+ * import { analyzeRhythm } from '@libraz/libcantus';
+ * const rhythm = analyzeRhythm(
+ *   [
+ *     { pitch: 60, startBeat: 0, durationBeat: 1.5 },
+ *     { pitch: 62, startBeat: 1.5, durationBeat: 2.5 },
+ *   ],
+ *   { ts: '4/4' },
+ * );
+ * rhythm.onsets; // 2
+ * rhythm.syncopation > 0; // true
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function analyzeRhythm(notes: readonly NoteEvent[], opts?: RhythmAnalysisOptions): RhythmAnalysis;
+
+/**
+ * A structural fingerprint of a piece: form, phrase shape, harmonic function
+ * and rhythm, and how its motifs derive from one another — everything
+ * `compareReferences` needs to measure two pieces against each other,
+ * dimension by dimension, without carrying the note sequence itself.
+ *
+ * A profile is plain data, JSON-serializable end to end: nothing in it is a
+ * class instance or a function. `profileVersion` gates the shape this file
+ * declares, not the analysis behind it — a schema change bumps it, a reading
+ * that changes only because the analyzer improved does not.
+ */
+
+/**
+ * Schema version {@link ReferenceProfile} is written at.
+ *
+ * {@link assertReferenceProfile} rejects any other value outright rather than
+ * guess at an older shape a caller's stored JSON might be in.
+ *
+ * @category Arrangement & Analysis
+ */
+declare const REFERENCE_PROFILE_VERSION = 1;
+/**
+ * A structural fingerprint of a piece, recovered from its notes and held
+ * without the notes themselves.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferenceProfile = {
+    /** Schema version this record is written at; see {@link REFERENCE_PROFILE_VERSION}. */
+    profileVersion: number;
+    /** The analysed span. */
+    span: {
+        startBeat: number;
+        endBeat: number;
+        bars: number;
+    };
+    /** The piece's meter across the analysed span. */
+    meters: MeterMap;
+    /** Sections, phrases and the hypermetric grouping they sit in. */
+    form: ReferenceForm;
+    /** Keys, structural harmony, and harmonic rhythm. */
+    harmony: ReferenceHarmony;
+    /** Register, contour, motifs and their derivations, and melodic rhythm. */
+    melody: ReferenceMelody;
+};
+/**
+ * The formal reading of a profiled piece: its hypermetric grouping, the
+ * sections that grouping and repetition reveal, and the phrases within them.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferenceForm = {
+    /** The hyperbar grouping the phrase and section boundaries are read against. */
+    hypermeter: {
+        groupBars: number;
+        confidence: number;
+    };
+    /** Sections, labelled by which earlier section they restate. */
+    sections: FormSection[];
+    /** Phrases, in time order. */
+    phrases: ReferencePhrase[];
+};
+/**
+ * One phrase: its span, the section it opens in, how it cadences, and the
+ * melodic and motivic content within it.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferencePhrase = {
+    /** First beat of the phrase. */
+    startBeat: number;
+    /** End of the phrase, exclusive. */
+    endBeat: number;
+    /** The phrase's length in bars. */
+    bars: number;
+    /** Index into `form.sections` of the section this phrase's start beat falls in. */
+    section: number | null;
+    /** Confidence of the phrase boundary, in [0, 1]. */
+    confidence: number;
+    /** The cadence the phrase ends on, or null when it closes on none. */
+    cadence: ReferenceCadence | null;
+    /** The phrase's melodic descriptors, or null when fewer than two notes sound within it. */
+    melody: ReferencePhraseMelody | null;
+    /** Indices into `melody.graph.nodes` of every motif statement that starts within this phrase. */
+    motifNodes: number[];
+};
+/**
+ * How a melodic line reads within one phrase.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferencePhraseMelody = {
+    /** The phrase's overall shape. */
+    shape: MelodicContourShape;
+    /** Lowest pitch sounding in the phrase. */
+    low: number;
+    /** Highest pitch sounding in the phrase. */
+    high: number;
+    /** Duration-weighted mean pitch, truncated to the phrase's span. */
+    mean: number;
+    /** Pitch of the phrase's highest note (the first, when several tie). */
+    peakPitch: number;
+    /** Onset of the phrase's peak note, as a fraction of the phrase's length, in [0, 1]. */
+    peakPosition: number;
+    /**
+     * Eight sampled points across the phrase, each the sounding pitch at that
+     * point minus the piece's overall melodic mean, in semitones.
+     */
+    outline: number[];
+    /** Onsets per bar within the phrase; see {@link RhythmAnalysis.onsetDensity}. */
+    onsetDensity: number;
+    /** Share of the phrase during which nothing sounds. */
+    restRatio: number;
+};
+/**
+ * A cadence read at a structural boundary.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferenceCadence = {
+    /** Beat the cadence arrives at. */
+    atBeat: number;
+    /** The cadence type. */
+    type: CadenceType;
+    /** How strongly the cadence closes the boundary it sits at, in [0, 1]. */
+    weight: number;
+};
+/**
+ * The harmonic reading of a profiled piece: its key regions, its structural
+ * chords, and how densely those chords change.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferenceHarmony = {
+    /** Key regions across the analysed span. */
+    keys: ReferenceKeyRegion[];
+    /** Chords reduced from the piece's harmony. */
+    chords: ReferenceChord[];
+    /** Onset placement of chord changes, read the way a melodic line's onsets are. */
+    rhythm: RhythmAnalysis;
+};
+/**
+ * One span of the piece read in a single key.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferenceKeyRegion = {
+    /** First beat of the region. */
+    startBeat: number;
+    /** End of the region, exclusive. */
+    endBeat: number;
+    /** The key the region is read in. */
+    key: ResolvedKey;
+    /** Confidence of the key reading, in [0, 1]. */
+    confidence: number;
+};
+/**
+ * One reduced chord, named against the key region it falls in.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferenceChord = {
+    /** First beat of the chord. */
+    startBeat: number;
+    /** End of the chord, exclusive. */
+    endBeat: number;
+    /** Index into `harmony.keys` of the region this chord is read against. */
+    key: number;
+    /** The chord, as a Roman numeral in the region's key. */
+    roman: string;
+    /** The chord's harmonic function. */
+    function: HarmonicFunction;
+    /** How the chord survived harmonic reduction. */
+    level: ReductionLevel;
+};
+/**
+ * The melodic reading of a profiled piece: register and contour, its motifs
+ * and how they derive from one another, and its rhythm.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferenceMelody = {
+    /** The melodic line's pitch range and mean, or null when no note sounds. */
+    register: {
+        low: number;
+        high: number;
+        mean: number;
+    } | null;
+    /** The melodic line's overall shape, or null when fewer than two notes sound. */
+    shape: MelodicContourShape | null;
+    /** Motifs found in the melodic line. */
+    motifs: ReferenceMotif[];
+    /** How the motifs' statements derive from one another. */
+    graph: MotifGraph;
+    /** Onset placement of the melodic line. */
+    rhythm: RhythmAnalysis;
+};
+/**
+ * One motif, held as the interval and rhythm ratios it repeats under
+ * transformation rather than as the notes of any one statement.
+ *
+ * @category Arrangement & Analysis
+ */
+type ReferenceMotif = {
+    /** Semitones between consecutive notes of the first statement (`MotifData.intervals`). */
+    intervals: number[];
+    /** Onset-to-onset ratios of the first statement (`MotifData.rhythm`), each gap over the first. */
+    rhythm: number[];
+    /**
+     * Onset gap between the first two notes of the first statement, in beats:
+     * the unit `rhythm` is measured in. 0 for a one-note motif.
+     */
+    unitBeats: number;
+    /** Length of the first statement, in beats. */
+    spanBeats: number;
+    /** How many statements of this motif were found. */
+    occurrences: number;
+};
+
+export { CADENCE_TYPES as C, HARMONIC_FUNCTIONS as H, MELODIC_CONTOUR_SHAPES as M, REDUCTION_LEVELS as R, REFERENCE_PROFILE_VERSION as S, RHYTHM_IOI_BINS as T, reduceProgression as aA, relateMotifs as aB, romanToChord as aC, secondaryDominant as aD, secondaryDominantOf as aE, sectionsFromNotes as aF, toVoiceNotes as aG, analyzeChord as ad, analyzeRhythm as ae, analyzeVoice as af, assertChordTimeline as ag, borrowedSource as ah, chordTimelineFromChords as ai, chordTimelineFromNotes as aj, chordToRoman as ak, detectCadence as al, detectCadences as am, detectModulations as an, explainRoman as ao, extractMotifs as ap, functionOf as aq, isBorrowedChord as ar, isDiatonic as as, isMinorKey as at, keyTimelineFromNotes as au, melodicContour as av, motifFromNotes as aw, motifGraph as ax, pivotChords as ay, prevailingKeyOf as az, MOTIF_RELATION_KINDS as t };
+export type { ReferenceHarmony as $, AnalyzeChordOptions as A, BarPositionProfile as B, DetectCadenceOptions as D, ExplainRomanOptions as E, FormSection as F, MotifGraphNode as G, IdentifiedVoiceNote as I, MotifGraphOptions as J, KeyContext as K, MotifOccurrence as L, MotifRelation as N, MotifRelationKind as O, MotifRelationSummary as P, PivotChord as Q, ReduceProgressionOptions as U, ReducedChord as V, ReductionBasis as W, ReductionLevel as X, ReferenceCadence as Y, ReferenceChord as Z, ReferenceForm as _, AnalyzedNote as a, ReferenceKeyRegion as a0, ReferenceMelody as a1, ReferenceMotif as a2, ReferencePhrase as a3, ReferencePhraseMelody as a4, ReferenceProfile as a5, RejectedCandidate as a6, RhythmAnalysis as a7, RhythmAnalysisOptions as a8, RomanExplanation as a9, SuspensionFigure as aa, TheoryLabel as ab, VoiceNote as ac, BorrowedSource as b, CadenceHit as c, CadenceResult as d, CadenceType as e, ChordAnalysis as f, ChordSegmentation as g, ChordTimeline as h, ChordTimelineOptions as i, ChordTimelineResult as j, ChordToRomanOptions as k, ContourDirection as l, ExtractMotifsOptions as m, FormSectionOptions as n, HarmonicFunction as o, KeyProfileName as p, KeyProfilePair as q, KeyRegion as r, KeyTimelineOptions as s, MelodicContour as u, MelodicContourShape as v, MelodicPhrase as w, MotifData as x, MotifGraph as y, MotifGraphEdge as z };