@libraz/libcantus 1.0.1 → 1.1.0

package/dist/{index-BO6xE9YU.d.cts → index-BUtIf2go.d.ts}

@@ -1,8 +1,8 @@
-import { d as KeyScale, g as NoteEvent, S as SpelledInterval } from './index-B9MNZboQ.cjs';
-import { d as ChordQuality, b as Chord, N as NoteSafety, S as SafetyProfile } from './index-C_8o--VE.cjs';
-import { r as ScaleName } from './masks-DYbE485J.cjs';
-import { i as KeyProfileName, j as KeyProfilePair, R as RejectedCandidate, k as KeyRegion, e as ChordTimeline, C as CadenceHit, a as AnalyzedNote, T as TheoryLabel, K as KeyContext, b as CadenceResult } from './index-Dzr13q3d.cjs';
-import { T as TimeSignature, c as MeterMap, b as MeterLike } from './index-BkGmlyI3.cjs';
+import { e as KeyScale, h as NoteEvent, i as NoteLike, g as Note, S as SpelledInterval } from './index-Cy15oTvh.js';
+import { d as ChordQuality, k as KeyVariant, b as Chord, q as SpelledKeyLike, c as ChordLike, K as KeyLike, n as ResolvedKey, N as NoteSafety, S as SafetyProfile } from './coerce-wwdELNYS.js';
+import { r as ScaleName } from './masks-O73Rhj5d.js';
+import { i as KeyProfileName, j as KeyProfilePair, R as RejectedCandidate, k as KeyRegion, e as ChordTimeline, C as CadenceHit, a as AnalyzedNote, T as TheoryLabel, K as KeyContext, b as CadenceResult } from './index-BpWOhkkE.js';
+import { b as MeterLike } from './index-Ci3xyows.js';
 
 /**
  * Church-mode candidates for {@link detectKey}.
@@ -164,12 +164,7 @@ type KeyMatch = {
      */
     alternatives?: RejectedCandidate[];
 };
-/**
- * Which form of a scale a {@link KeyMatch} settled on.
- *
- * @category Recognition
- */
-type KeyVariant = 'major' | 'natural' | 'harmonic' | 'melodic' | 'modal';
+
 /**
  * Input weighting for {@link detectKey}.
  *
@@ -249,8 +244,13 @@ type DetectKeyOptions = {
  * A match is reported when all of the chord's tones are present in the input, or
  * when the only absent tone is the perfect fifth (a common omission in shell
  * voicings); matches are ranked best-first by fewest extra notes, then fewest
- * missing notes, then most specific (largest) chord. An exact match (no extras,
- * no missing) is flagged and ranked first.
+ * missing notes, then root position over an inversion, then most specific
+ * (largest) chord. An exact match (no extras, no missing) is flagged and ranked
+ * first.
+ *
+ * The root-position step decides between readings of the same pitches that are
+ * otherwise equally good: `[55, 59, 62, 64]` is read as G6 rather than Em7,
+ * because G is in the bass.
  *
  * @param pitches MIDI pitches or bare pitch classes (octave-agnostic).
  * @returns Ranked chord interpretations (may be empty).
@@ -329,7 +329,7 @@ declare function detectChordBest(pitches: readonly number[], opts?: DetectChordO
  * import { detectKey } from '@libraz/libcantus';
  * const keys = detectKey([60, 62, 64, 65, 67, 69, 71]); // C major scale
  * keys[0].mode; // 'major', with keys[0].key.rootPc === 0
- * keys[1].mode; // 'minor' on 9: A minor, the relative, ranked just below
+ * keys[1].mode; // 'minor' — on 9: A minor, the relative, ranked just below
  * const riff = detectKey([62, 62, 65, 69, 71, 69, 65, 62], { modes: true });
  * riff[0].scaleName; // 'dorian', on rootPc 2, still reported as mode 'minor'
  * ```
@@ -342,11 +342,21 @@ declare function detectKey(pitches: readonly number[], opts?: DetectKeyOptions):
  *
  * {@link detectKey} counts every pitch once, which lets a run of fast ornamental
  * notes outvote the sustained harmony that establishes the key. This weighs
- * each note by duration times velocity, the same measure chord inference uses,
- * so the two agree on what the music emphasises. Notes that never sound (zero
- * or negative duration) are ignored. The weighted distribution is then ranked
- * exactly as {@link detectKey} ranks it, by correlation against a key profile,
- * so `score` is a finite correlation in [-1, 1].
+ * each note by the same measure chord inference weighs its own histogram by, so
+ * the two agree on what the music emphasises: duration times
+ * velocity, with a note that carries no velocity counted at full weight rather
+ * than at an assumed one. Notes that never sound (zero or negative duration)
+ * are ignored. The weighted distribution is then ranked exactly as
+ * {@link detectKey} ranks it, by correlation against a key profile, so `score`
+ * is a finite correlation in [-1, 1].
+ *
+ * The one term of that measure this cannot share is the metric accent, which
+ * chord inference adds to an onset by the beat it falls on: the notes arrive
+ * here without the meter they are counted in, and reading them against an
+ * assumed one would rank the same notes differently under a signature the
+ * caller never named. Ranking a whole piece is the coarser question, and the
+ * accents are what separate one window from the next rather than one key from
+ * another.
  *
  * @param notes The note events to weigh.
  * @param opts Which profile to rank with, whether the modes take part, and the
@@ -398,6 +408,158 @@ declare function detectKeyFromNotes(notes: readonly NoteEvent[], opts?: Omit<Det
  */
 declare function detectKeyBest(pitches: readonly number[], opts?: DetectKeyOptions): KeyMatch | null;
 
+/**
+ * Augmented-sixth chords: the Italian, French, and German sixths.
+ *
+ * All three stand on the lowered submediant (b6) in the bass and carry an
+ * augmented sixth above it, and all three are predominants whose two outer
+ * voices resolve outward onto the dominant. The family is defined by that bass
+ * and that interval rather than by a stack of thirds, so a chord is recognized
+ * here from the tones sounding over that bass rather than through the
+ * Roman-numeral degree tables.
+ *
+ * The interval is spelled, so recognition reads letters and not only pitch
+ * classes: over an Ab bass the augmented sixth is F# and the minor seventh of
+ * the bVI7 it otherwise sounds exactly like is Gb. A caller holding pitch
+ * classes alone — an analysis of a MIDI track, which names no accidentals —
+ * makes that reading with {@link augmentedSixthFromPitchClasses}, and the chord
+ * it hands back carries the spelling that decided it.
+ */
+
+/**
+ * The three augmented-sixth chords, under the nationalities convention gives
+ * them.
+ *
+ * Over an Ab bass in C: the Italian sixth is Ab C F#, the French sixth adds the
+ * supertonic (Ab C D F#), and the German sixth adds the lowered mediant
+ * (Ab C Eb F#).
+ *
+ * @category Functional Harmony
+ */
+type AugmentedSixthKind = 'italian' | 'french' | 'german';
+/**
+ * Build an augmented-sixth chord in a key.
+ *
+ * The chord always carries an explicit `bassPc` on the lowered submediant,
+ * which is what makes it an augmented sixth rather than the dominant seventh or
+ * the altered supertonic seventh it shares pitch classes with, and an explicit
+ * interval template naming exactly the tones that sound.
+ *
+ * It also carries its spelling: the tones as `toneSpellings`, and the root and
+ * bass as the usual hints. Those are what let the ordinary chord speller and
+ * the symbol formatter name the chord — `Ab C Eb F#` and `Ab7` for the German
+ * sixth of C major — since a stack of thirds over that root would put a Gb
+ * where the augmented sixth belongs. The spelling is the one the key is written
+ * on, so a flat-side key takes the double flats it genuinely needs.
+ *
+ * The lowered submediant is taken as eight semitones above the tonic in every
+ * mode, since the chord is a chromatic alteration rather than a degree of the
+ * prevailing scale.
+ *
+ * @param kind Which of the three augmented sixths to build.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns The chord, with its bass on the lowered submediant.
+ * @throws If `kind` is not one of the three, or the key's root is not finite.
+ * @see {@link spellAugmentedSixth} to spell the family from a tonic without
+ *   building a chord at all.
+ * @example
+ * ```ts
+ * import { augmentedSixthChord, majorKey } from '@libraz/libcantus';
+ * augmentedSixthChord('german', majorKey(0));
+ * // Ab C Eb F# in C: { rootPc: 8, quality: 'dom7', intervals: [0, 4, 7, 10], bassPc: 8, ... }
+ * ```
+ * @category Functional Harmony
+ */
+declare function augmentedSixthChord(kind: AugmentedSixthKind, key: SpelledKeyLike): Chord;
+/**
+ * Identify a chord as one of the augmented sixths, or null when it is none.
+ *
+ * A chord qualifies when it sounds the lowered submediant of `key` in the bass,
+ * its pitch classes are exactly one of the three sets built over that bass, and
+ * its own letters spell the augmented sixth above it. All three are needed: the
+ * same pitch classes over the same bass are an ordinary bVI7 when the tone ten
+ * semitones above the bass is written as a minor seventh, and the letters are
+ * the only place that distinction lives.
+ *
+ * A chord naming no `bassPc` sounds its root lowest, which is how the two
+ * conventions for that field — the sounding bass always, or only a bass that
+ * differs from the root — are read alike here.
+ *
+ * The root the chord is measured from is not consulted, so a chord voiced or
+ * rebuilt around any of its own tones still identifies as long as it keeps its
+ * spelling.
+ *
+ * @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 The kind of augmented sixth, or null.
+ * @see {@link augmentedSixthFromPitchClasses} to make the reading from pitch
+ *   classes that carry no spelling at all.
+ * @example
+ * ```ts
+ * import { augmentedSixthKind, majorKey, romanToChord } from '@libraz/libcantus';
+ * augmentedSixthKind(romanToChord('Fr6', majorKey(0)), majorKey(0)); // 'french'
+ * ```
+ * @category Functional Harmony
+ */
+declare function augmentedSixthKind(chord: ChordLike, key: KeyLike): AugmentedSixthKind | null;
+/**
+ * Read a set of sounding pitch classes over a sounding bass as an augmented
+ * sixth, or null when they are none.
+ *
+ * The reading a caller holding no spelling has to make for itself: pitch
+ * classes name no accidentals, so nothing downstream can tell the German sixth
+ * from the bVI7 it sounds like once the letters are gone. The chord returned is
+ * the one {@link augmentedSixthChord} builds, spelling and all, so it keeps
+ * identifying as an augmented sixth everywhere it travels.
+ *
+ * Not every b6-1-b3-#4 over a b6 bass is an augmented sixth, and this cannot
+ * know which one is: it answers what the tones would spell, and the caller
+ * decides whether that reading is the one the music supports.
+ *
+ * @param pcs The sounding pitch classes; duplicates and unreduced values are
+ *   fine.
+ * @param bassPc The pitch class sounding in the bass.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns The augmented-sixth chord, or null.
+ * @see {@link augmentedSixthKind} to read a chord that already carries its
+ *   spelling.
+ * @example
+ * ```ts
+ * import { augmentedSixthFromPitchClasses, majorKey } from '@libraz/libcantus';
+ * // Ab C Eb Gb sounding over Ab in C: the German sixth, spelled with its F#.
+ * augmentedSixthFromPitchClasses([8, 0, 3, 6], 8, majorKey(0))?.quality; // 'dom7'
+ * ```
+ * @category Functional Harmony
+ */
+declare function augmentedSixthFromPitchClasses(pcs: readonly number[], bassPc: number, key: SpelledKeyLike): Chord | null;
+/**
+ * Spell an augmented-sixth chord from a spelled tonic, lowest note first.
+ *
+ * This is the spelled counterpart of {@link augmentedSixthChord}, and the table
+ * the chord's own spelling is built from: every tone is placed by a named
+ * interval above the bass, so the outer interval is an augmented sixth in every
+ * key rather than the minor seventh its ten semitones would otherwise imply.
+ * Reach for it when a spelled tonic is all there is; spelling the chord itself
+ * with {@link spellChord} names the same notes, in the chord's own order.
+ *
+ * A tonic carrying an octave yields notes carrying octaves, ascending from the
+ * bass; an octave-less tonic yields octave-less notes.
+ *
+ * @param kind Which of the three augmented sixths to spell.
+ * @param tonic The spelled tonic of the key, as a note name, a MIDI number,
+ *   note data, or a `Note`.
+ * @returns The spelled tones, bass first and ascending.
+ * @throws If `kind` is not one of the three, or `tonic` is not a note.
+ * @example
+ * ```ts
+ * import { noteNames, parseNote, spellAugmentedSixth } from '@libraz/libcantus';
+ * noteNames(spellAugmentedSixth('german', parseNote('C'))); // ['Ab', 'C', 'Eb', 'F#']
+ * noteNames(spellAugmentedSixth('italian', 'E')); // ['C', 'E', 'A#']
+ * ```
+ * @category Functional Harmony
+ */
+declare function spellAugmentedSixth(kind: AugmentedSixthKind, tonic: NoteLike): Note[];
+
 /**
  * Arrangement track-role analysis: a single harmony is inferred from every
  * track's notes pooled together, each track is then analysed against that shared
@@ -485,8 +647,11 @@ type ArrangementAnalysis = {
      * started in for every bar after it leaves.
      */
     keys: KeyRegion[];
-    /** The key held longest across {@link ArrangementAnalysis.keys}. */
-    prevailingKey: KeyScale;
+    /**
+     * The key held longest across {@link ArrangementAnalysis.keys}, whole: the
+     * pitch classes with the spelling and the scale form the regions carry.
+     */
+    prevailingKey: ResolvedKey;
     timeline: ChordTimeline;
     segmentConfidence: number[];
     cadences: CadenceHit[];
@@ -504,8 +669,11 @@ type ArrangementOptions = {
      * A single key held across the whole arrangement. Omit it, and `keys` with
      * it, to have the key searched for over time so a modulating piece is read
      * against the key actually in force.
+     *
+     * Taken in whatever form the caller holds a key, and kept whole: the region
+     * built from it carries the spelling and the scale form it was named with.
      */
-    key?: KeyScale;
+    key?: KeyLike;
     /**
      * Key regions to judge against, when a previous pass already worked them out.
      * Takes precedence over `key`; supplying both is answering the same question
@@ -536,14 +704,14 @@ type ArrangementOptions = {
      *
      * @defaultValue `4/4`
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * The meter as it changes over the arrangement. Bar lines, downbeats and
      * metric weight all follow the signature in force at the beat in question.
      *
      * @defaultValue 4/4 throughout
      */
-    meters?: MeterMap;
+    meters?: MeterLike;
     /**
      * Length of the pickup in beats, when the piece starts with one.
      *
@@ -555,7 +723,13 @@ type ArrangementOptions = {
      */
     pickupBeats?: number;
     /**
-     * Chord-slot length in beats; defaults to the length of the opening bar.
+     * Expected chord length in beats; defaults to the length of the opening bar.
+     *
+     * A prior rather than a grid: the arrangement analysis infers its harmony
+     * with dynamic segmentation, where the longer a chord is expected to last the
+     * more evidence a change needs before the search will place one. A chord may
+     * still begin at any position the notes argue for. Supply `timeline` to
+     * analyse against boundaries you have fixed yourself.
      *
      * @defaultValue the length of the opening bar
      */
@@ -578,6 +752,26 @@ type ArrangementOptions = {
      */
     budget?: number;
 };
+/**
+ * Label every note of one polyphonic passage against the harmony under it and
+ * the voices around it.
+ *
+ * {@link analyzeVoice} reads a single line: it takes the note before and the note
+ * after each note as that note's melodic neighbours, and it is given no other
+ * voices, so over a flat array of everything that sounds it invents figures
+ * across parts — the alto between two soprano notes becomes a passing tone —
+ * and can never find a suspension, which is by definition a dissonance against
+ * something else sounding. So the passage is partitioned into monophonic
+ * sub-voices first and each is read with the others handed to it, which is what
+ * {@link analyzeArrangement} does with the tracks it is given.
+ *
+ * @param notes The passage, in any order; the ids are indices into this array.
+ * @param chordAtBeat Chord sounding at a given beat, or null.
+ * @param key The key, or the key in force at a given beat.
+ * @returns One annotation per note, in the order the notes were given, each
+ *   carrying its position in that array as its id.
+ */
+declare function analyzePolyphony(notes: readonly NoteEvent[], chordAtBeat: (beat: number) => Chord | null, key: KeyContext): AnalyzedNote[];
 /**
  * Analyse a whole arrangement against the harmony inferred from it.
  *
@@ -622,7 +816,7 @@ type ArrangementOptions = {
  *   { pitch: 67, startBeat: 2, durationBeat: 2 },
  * ];
  * const { prevailingKey, conflicts } = analyzeArrangement([{ role: 'melody', notes: melody }]);
- * prevailingKey.rootPc; // the key held longest across the analysis
+ * prevailingKey.scale.rootPc; // the key held longest across the analysis
  * conflicts; // notes clashing with the inferred harmony, worst severity first
  * ```
  * @category Arrangement & Analysis
@@ -786,6 +980,11 @@ declare function tensionCurve(tracks: ArrangementTrack[], opts?: ArrangementOpti
  * twice over the same notes. This takes the analysis it already produced, so
  * the curve and the annotations describe the same harmony by construction.
  *
+ * The analysis is the harmony to fall back on rather than one laid over the
+ * caller: `key`, `keys` and `harmonyTracks` each name a harmony the analysis
+ * does not hold, so naming one is asking for a different reading, and the curve
+ * is taken under it. Nothing else about the analysis is re-derived.
+ *
  * @param tracks The same tracks that were analysed.
  * @param analysis The result of {@link analyzeArrangement} for those tracks.
  * @param opts Analysis options plus an optional `step` (default one beat).
@@ -875,9 +1074,11 @@ type HypermeterOptions = {
  * Groupings of 2, 3, 4, 6, and 8 bars are tried at every phase, and each
  * reading is scored on two counts: how much more harmonic change lands on the
  * bars it calls group heads than on the bars between them, and how many of the
- * cadences it is given arrive where it says a hyperbar ends. The commonest
- * groupings are believed a little more readily than the rare ones, which
- * settles ties without letting a prior overrule the music.
+ * hyperbar ends it predicts are closed by one of the cadences it is given.
+ * Where cadences are given they settle the phase, since a hyperbar is what a
+ * cadence ends; the harmony then chooses among the phases they agree with. The
+ * commonest groupings are believed a little more readily than the rare ones,
+ * which settles ties without letting a prior overrule the music.
  *
  * The meter is read at the beat in question rather than at the start, so a
  * piece that changes metre keeps being cut at its own bar lines. Bar 0 is the
@@ -989,15 +1190,17 @@ type PhraseOptions = {
      *
      * @defaultValue `4/4`
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
-     * The meter as it changes over the span. Bar lines, hypermetric downbeats and
-     * the default phrase length all follow the signature in force at the beat in
-     * question, so a piece that changes metre is not read in the one it opened in.
+     * The meter as it changes over the span. Bar lines and hypermetric downbeats
+     * follow the signature in force at the beat in question, so a piece that
+     * changes metre is cut at its own bar lines; the length defaults below are
+     * lengths rather than positions, and each is taken once from the meter the
+     * span opens in.
      *
      * @defaultValue 4/4 throughout
      */
-    meters?: MeterMap;
+    meters?: MeterLike;
     /**
      * Key context for cadence detection: one key for the whole span, or the key
      * in force at a given beat. Omit it to have the key searched for over time,
@@ -1084,7 +1287,10 @@ type StructuralCadence = {
  *
  * Three kinds of evidence are gathered independently and then reconciled. The
  * harmony contributes its cadences, each closing at the end of the chord it
- * arrives on. The melody contributes the rests it breathes at and the notes it
+ * arrives on, and at the bar line where that chord is held across one — a tonic
+ * still sounding into the next phrase closed this one at the bar line. The
+ * cadence reported for a phrase is always one that arrived inside it. The
+ * melody contributes the rests it breathes at and the notes it
  * holds long enough to read as arrivals. Repetition contributes the beats where
  * the music restarts material it has just played. The metre contributes its
  * hypermetric downbeats, which confirm a boundary but never declare one on
@@ -1107,18 +1313,25 @@ type StructuralCadence = {
  *   that never sound are dropped.
  * @param opts Analysis options; see {@link PhraseOptions}.
  * @returns The phrases, in time order; one phrase covering the whole span when
- *   the span is too short to divide.
+ *   the span is too short to divide, and none at all when nothing sounds —
+ *   silence is no material to hear a phrase in.
  * @example
  * ```ts
  * import { chordTimelineFromNotes, phrasesFromTimeline } from '@libraz/libcantus';
+ * // Four bars of C - F - G - C. Triads rather than single notes: one line at a
+ * // time names no harmony, so nothing would cadence.
+ * const triad = (pitches: number[], startBeat: number) =>
+ *   pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
  * const notes = [
- *   { pitch: 60, startBeat: 0, durationBeat: 4 },
- *   { pitch: 67, startBeat: 4, durationBeat: 4 },
- *   { pitch: 60, startBeat: 8, durationBeat: 8 },
+ *   ...triad([60, 64, 67], 0),
+ *   ...triad([65, 69, 72], 4),
+ *   ...triad([67, 71, 74], 8),
+ *   ...triad([60, 64, 67], 12),
  * ];
  * const { timeline } = chordTimelineFromNotes(notes);
  * const phrases = phrasesFromTimeline(timeline, notes);
- * phrases[phrases.length - 1]?.cadence?.cadence.type; // 'authentic', when one closes it
+ * phrases[phrases.length - 1]?.cadence?.cadence.type; // 'authentic'
+ * phrases[phrases.length - 1]?.cadence?.atBeat; // 12, inside the phrase it closes
  * ```
  * @category Arrangement & Analysis
  */
@@ -1136,14 +1349,18 @@ declare function phrasesFromTimeline(timeline: ChordTimeline, notes: readonly No
  * @example
  * ```ts
  * import { chordTimelineFromNotes, phrasesFromTimeline, structuralCadences } from '@libraz/libcantus';
+ * const triad = (pitches: number[], startBeat: number) =>
+ *   pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
  * const notes = [
- *   { pitch: 60, startBeat: 0, durationBeat: 4 },
- *   { pitch: 67, startBeat: 4, durationBeat: 4 },
- *   { pitch: 60, startBeat: 8, durationBeat: 8 },
+ *   ...triad([60, 64, 67], 0),
+ *   ...triad([65, 69, 72], 4),
+ *   ...triad([67, 71, 74], 8),
+ *   ...triad([60, 64, 67], 12),
  * ];
  * const { timeline } = chordTimelineFromNotes(notes);
  * const ranked = structuralCadences(phrasesFromTimeline(timeline, notes));
- * ranked[0]; // the cadence carrying the most structural weight, if any
+ * ranked[0]?.cadence.type; // 'authentic' — the cadence carrying the most weight
+ * ranked[0]?.atBeat; // 12
  * ```
  * @category Arrangement & Analysis
  */
@@ -1206,14 +1423,14 @@ type FormSectionOptions = {
      *
      * @defaultValue `4/4`
      */
-    ts?: TimeSignature;
+    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?: MeterMap;
+    meters?: MeterLike;
     /**
      * Length of the unit spans are compared in, in bars; defaults to one hyperbar.
      *
@@ -1278,58 +1495,15 @@ type FormSectionOptions = {
 declare function sectionsFromNotes(notes: readonly NoteEvent[], opts?: FormSectionOptions): FormSection[];
 
 /**
- * Melody as a shape, rather than as a run of notes.
+ * The recurring cells a melody is built from.
  *
- * A motif is held here as an interval contour plus a rhythmic profile, which is
- * what makes a restatement at another pitch level the same motif; the absolute
- * pitches only ever describe one statement of it. On that footing two statements
- * can be compared and the transformation between them named — repetition,
- * transposition, inversion, retrograde, augmentation — and phrases that stand in
- * no such relation can still be scored for similarity.
+ * 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.
  */
 
-/**
- * Step direction between two consecutive notes.
- *
- * @category Arrangement & Analysis
- */
-type ContourDirection = 'up' | 'down' | 'same';
-/**
- * The overall shape of a line.
- *
- * The first four names are the vocabulary the motif generator's contours are
- * written in, and mean the same here. `'static'` is the shape a generator never
- * asks for and an analysis regularly meets: a line that does not move. A line
- * that dips and comes back — an arch upside down — reads as `'wave'`, since the
- * shared vocabulary has no name of its own for it.
- *
- * A wave has to turn more than once to be heard as one, so a cell the generator
- * writes for `'wave'` reads back as `'wave'` only from three bars up; the one-
- * and two-bar cells turn once and read as `'arch'`. The other three shapes come
- * back under their own name at every length.
- *
- * @category Arrangement & Analysis
- */
-type MelodicContourShape = 'arch' | 'ascending' | 'descending' | 'wave' | 'static';
-/**
- * The abstract shape of a line: its step directions and what they add up to.
- *
- * @category Arrangement & Analysis
- */
-type MelodicContour = {
-    /** One direction per adjacent pair of notes, in time order. */
-    directions: ContourDirection[];
-    /** What the directions add up to. */
-    shape: MelodicContourShape;
-    /** Index of the highest note; ties keep the earliest. */
-    peakIndex: number;
-    /** Index of the lowest note; ties keep the earliest. */
-    troughIndex: number;
-    /** Semitone distance from the lowest note to the highest. */
-    range: number;
-    /** Why the line was given that shape. */
-    rationale: string;
-};
 /**
  * One statement of a motif, addressed in the melody it was found in.
  *
@@ -1418,71 +1592,6 @@ type ExtractMotifsOptions = {
      */
     budget?: number;
 };
-/**
- * How one statement of a motif stands to another.
- *
- * `'transposition'` is the literal one — every interval preserved, which is what
- * makes a sequence built on it a *real* sequence. `'tonalTransposition'` shifts
- * by scale degrees instead and lets the key resize the intervals, which is what
- * makes a sequence built on it a *tonal* sequence; the two are different devices
- * and are never reported as one. `'augmentation'` and `'diminution'` name the
- * relation only when the pitches are untouched, so an inversion in doubled note
- * values reads as `'inversion'` with a `timeRatio` of 2 rather than losing the
- * inversion to the stretch.
- *
- * @category Arrangement & Analysis
- */
-type MotifRelationKind = 'repetition' | 'transposition' | 'tonalTransposition' | 'inversion' | 'retrograde' | 'retrogradeInversion' | 'augmentation' | 'diminution';
-/**
- * The transformation that turns one motif into another.
- *
- * @category Arrangement & Analysis
- */
-type MotifRelation = {
-    /** The named transformation. */
-    kind: MotifRelationKind;
-    /**
-     * Whether the second statement begins where the first ends, which is what
-     * separates a sequence from a restatement elsewhere in the piece: a
-     * `'transposition'` that is one is a real sequence, a `'tonalTransposition'`
-     * that is one is a tonal sequence.
-     */
-    sequence: boolean;
-    /** Semitones from the first statement's first note to the second's. */
-    semitones: number;
-    /** The same distance named as a spelled interval. */
-    interval: SpelledInterval;
-    /** Scale degrees the second statement stands above the first, when tonal. */
-    degrees?: number;
-    /**
-     * How much the second statement is stretched against the first: 2 for doubled
-     * note values, 0.5 for halved, 1 for unchanged.
-     */
-    timeRatio: number;
-    /** Why the pair was given that name. */
-    rationale: string;
-};
-/**
- * Anything that can be read as a melodic line: a motif, or plain note events.
- *
- * @category Arrangement & Analysis
- */
-type MelodicPhrase = MotifData | readonly NoteEvent[];
-/**
- * How alike two lines are, and how the answer was reached.
- *
- * @category Arrangement & Analysis
- */
-type MelodicComparison = {
-    /** Overall likeness in [0, 1]; 1 for the same line, transposition included. */
-    similarity: number;
-    /** Likeness of the interval sequences alone, in [0, 1]. */
-    pitchSimilarity: number;
-    /** Likeness of the rhythmic profiles alone, in [0, 1]. */
-    rhythmSimilarity: number;
-    /** Why the lines scored what they did. */
-    rationale: string;
-};
 /**
  * Find the cells a melody keeps coming back to.
  *
@@ -1496,9 +1605,11 @@ type MelodicComparison = {
  * rather than every fragment of it.
  *
  * The melody is expected to be monophonic, as {@link analyzeVoice} expects a
- * voice to be; split polyphonic material into lines first. Onsets are expected to
- * be quantised, since two statements must agree on their rhythm to be recognised
- * as one motif.
+ * 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
@@ -1529,7 +1640,13 @@ declare function extractMotifs(notes: readonly NoteEvent[], opts?: ExtractMotifs
  * caller names one it already has — a subject, an answer, a phrase lifted out of
  * a score — so that it can be handed to {@link relateMotifs}.
  *
- * @param notes The cell, in time order. Notes that never sound are dropped.
+ * 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
@@ -1549,102 +1666,74 @@ declare function extractMotifs(notes: readonly NoteEvent[], opts?: ExtractMotifs
  * @category Arrangement & Analysis
  */
 declare function motifFromNotes(notes: readonly NoteEvent[]): MotifData;
+
 /**
- * Name how two statements of a motif relate.
- *
- * The two are compared as shapes, not as pitches: the interval sequences decide
- * the pitch transformation and the onset gaps decide the timing, so a statement
- * a fourth higher in doubled note values is recognised for what it is. A pair
- * whose rhythms do not correspond — the same way round for a repetition or a
- * transposition, back to front for a retrograde — is not a transformation of the
- * motif but a different figure, and answers null; {@link melodicSimilarity} is
- * what scores those.
+ * What every reading of a melody has to agree on first.
  *
- * 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.
+ * 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.
  *
- * @param a The model statement.
- * @param b The statement to name against it.
- * @param key Key context for the tonal reading; without it, a statement that
- *   only holds diatonically is not recognised.
- * @returns The relation, or null when the two stand in none.
- * @example
- * ```ts
- * import { majorKey, motifFromNotes, relateMotifs } from '@libraz/libcantus';
- * const model = motifFromNotes([
- *   { pitch: 60, startBeat: 0, durationBeat: 1 },
- *   { pitch: 62, startBeat: 1, durationBeat: 1 },
- *   { pitch: 64, startBeat: 2, durationBeat: 1 },
- * ]);
- * const answer = motifFromNotes([
- *   { pitch: 62, startBeat: 3, durationBeat: 1 },
- *   { pitch: 64, startBeat: 4, durationBeat: 1 },
- *   { pitch: 65, startBeat: 5, durationBeat: 1 },
- * ]);
- * relateMotifs(model, answer, majorKey(0))?.kind; // 'tonalTransposition'
- * ```
  * @category Arrangement & Analysis
  */
-declare function relateMotifs(a: MotifData, b: MotifData, key?: KeyScale): MotifRelation | null;
-/**
- * Compare two lines and say why they scored what they did.
- *
- * The metric is a normalised edit distance over the interval sequence, weighted
- * against the same over the rhythmic profile. Intervals rather than pitches,
- * because the same tune in another key is the same tune; edit distance rather
- * than a step-by-step correlation, because a variant that adds a passing note or
- * drops one still has to line up with its model, and only an alignment-based
- * measure can do that. Substituting one interval for another costs by how far
- * apart they are rather than a flat step, so an answer that widens a third to a
- * fourth stays close to its model while one that replaces it with a leap does
- * not. The rhythm carries the smaller share: a melody is recognised mostly by
- * its pitch shape, but a figure in a wholly different rhythm is a different
- * figure.
- *
- * @param a The first line: a motif, or plain note events.
- * @param b The second line.
- * @returns The overall likeness, the two terms behind it, and a rationale.
- * @example
- * ```ts
- * import { compareMelodies } from '@libraz/libcantus';
- * const line = [
- *   { pitch: 60, startBeat: 0, durationBeat: 1 },
- *   { pitch: 62, startBeat: 1, durationBeat: 1 },
- *   { pitch: 64, startBeat: 2, durationBeat: 1 },
- * ];
- * compareMelodies(line, line).similarity; // 1
- * ```
+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
  */
-declare function compareMelodies(a: MelodicPhrase, b: MelodicPhrase): MelodicComparison;
+type ContourDirection = 'up' | 'down' | 'same';
 /**
- * How alike two lines are, in [0, 1].
+ * The overall shape of a line.
  *
- * The number {@link compareMelodies} reaches, for callers that only want to rank
- * phrases: 1 for the same line — a transposition of it included, since the
- * measure is built on intervals — and lower the further two lines are from being
- * each other's variant. Symmetric in its arguments, and deterministic.
+ * The first four names are the vocabulary the motif generator's contours are
+ * written in, and mean the same here. `'static'` is the shape a generator never
+ * asks for and an analysis regularly meets: a line that does not move. A line
+ * that dips and comes back — an arch upside down — reads as `'wave'`, since the
+ * shared vocabulary has no name of its own for it.
+ *
+ * A wave has to turn more than once to be heard as one, so a cell the generator
+ * writes for `'wave'` reads back as `'wave'` only from three bars up; the one-
+ * and two-bar cells turn once and read as `'arch'`. The other three shapes come
+ * back under their own name at every length.
+ *
+ * @category Arrangement & Analysis
+ */
+type MelodicContourShape = 'arch' | 'ascending' | 'descending' | 'wave' | 'static';
+/**
+ * The abstract shape of a line: its step directions and what they add up to.
  *
- * @param a The first line: a motif, or plain note events.
- * @param b The second line.
- * @returns The likeness in [0, 1].
- * @example
- * ```ts
- * import { melodicSimilarity } from '@libraz/libcantus';
- * const line = [
- *   { pitch: 60, startBeat: 0, durationBeat: 1 },
- *   { pitch: 62, startBeat: 1, durationBeat: 1 },
- *   { pitch: 64, startBeat: 2, durationBeat: 1 },
- * ];
- * melodicSimilarity(line, line); // 1
- * ```
  * @category Arrangement & Analysis
  */
-declare function melodicSimilarity(a: MelodicPhrase, b: MelodicPhrase): number;
+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.
  *
@@ -1655,9 +1744,17 @@ declare function melodicSimilarity(a: MelodicPhrase, b: MelodicPhrase): number;
  * 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.
- * @returns The directions, the shape, the peak and trough, and a rationale.
+ *   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';
@@ -1672,6 +1769,113 @@ declare function melodicSimilarity(a: MelodicPhrase, b: MelodicPhrase): number;
  */
 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.
+ */
+
+/**
+ * How one statement of a motif stands to another.
+ *
+ * `'transposition'` is the literal one — every interval preserved, which is what
+ * makes a sequence built on it a *real* sequence. `'tonalTransposition'` shifts
+ * by scale degrees instead and lets the key resize the intervals, which is what
+ * makes a sequence built on it a *tonal* sequence; the two are different devices
+ * and are never reported as one. `'augmentation'` and `'diminution'` name the
+ * relation only when the pitches are untouched, so an inversion in doubled note
+ * values reads as `'inversion'` with a `timeRatio` of 2 rather than losing the
+ * inversion to the stretch.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifRelationKind = 'repetition' | 'transposition' | 'tonalTransposition' | 'inversion' | 'retrograde' | 'retrogradeInversion' | 'augmentation' | 'diminution';
+/**
+ * The transformation that turns one motif into another.
+ *
+ * @category Arrangement & Analysis
+ */
+type MotifRelation = {
+    /** The named transformation. */
+    kind: MotifRelationKind;
+    /**
+     * Whether the second statement begins where the first ends, which is what
+     * separates a sequence from a restatement elsewhere in the piece: a
+     * `'transposition'` that is one is a real sequence, a `'tonalTransposition'`
+     * that is one is a tonal sequence.
+     */
+    sequence: boolean;
+    /** Semitones from the first statement's first note to the second's. */
+    semitones: number;
+    /** The same distance named as a spelled interval. */
+    interval: SpelledInterval;
+    /** Scale degrees the second statement stands above the first, when tonal. */
+    degrees?: number;
+    /**
+     * How much the second statement is stretched against the first: 2 for doubled
+     * note values, 0.5 for halved, 1 for unchanged.
+     *
+     * 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;
+};
+/**
+ * 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. 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;
+
 /**
  * Harmonic reduction: which chords carry the progression and which decorate it.
  *
@@ -1734,9 +1938,11 @@ type ReducedChord = {
  * What a reduction treats as the frame.
  *
  * `'function'` is the functional reading: the tonic, the dominant and the
- * chords that cadence are the frame. `'duration'` is the salience reading: the
- * chords that hold the harmony at least as long as the median chord are the
- * frame, whatever function they carry.
+ * 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
  */
@@ -1801,4 +2007,4 @@ type ReduceProgressionOptions = {
  */
 declare function reduceProgression(timeline: ChordTimeline, key: KeyContext, opts?: ReduceProgressionOptions): ReducedChord[];
 
-export { reduceProgression as $, type ArrangementAnalysis as A, type TrackRole as B, type ChordMatch as C, type DetectChordOptions as D, type ExtractMotifsOptions as E, type FormSection as F, analyzeArrangement as G, type Hypermeter as H, compareMelodies as I, createArrangementSession as J, type KeyMatch as K, detectChord as L, MODAL_SCALE_NAMES as M, detectChordBest as N, detectKey as O, type Phrase as P, detectKeyBest as Q, type ReduceProgressionOptions as R, type StructuralCadence as S, type TensionPoint as T, detectKeyFromNotes as U, extractMotifs as V, hypermeter as W, melodicContour as X, melodicSimilarity as Y, motifFromNotes as Z, phrasesFromTimeline as _, type ArrangementOptions as a, relateMotifs as a0, sectionsFromNotes as a1, structuralCadences as a2, tensionCurve as a3, tensionCurveFrom as a4, type ArrangementSession as b, type ArrangementTrack as c, type Conflict as d, type ContourDirection as e, type DetectKeyOptions as f, type FormSectionOptions as g, type HypermeterOptions as h, type KeyVariant as i, type MelodicComparison as j, type MelodicContour as k, type MelodicContourShape as l, type MelodicPhrase as m, type ModalCandidate as n, type ModalScaleName as o, type MotifData as p, type MotifOccurrence as q, type MotifRelation as r, type MotifRelationKind as s, type PhraseOptions as t, type PhraseSignal as u, type ReducedChord as v, type ReductionBasis as w, type ReductionLevel as x, type TrackAnalysis as y, type TrackEdit as z };
+export { phrasesFromTimeline as $, type ArrangementAnalysis as A, analyzeArrangement as B, type ChordMatch as C, type DetectChordOptions as D, type ExtractMotifsOptions as E, type FormSection as F, analyzePolyphony as G, type Hypermeter as H, augmentedSixthChord as I, augmentedSixthFromPitchClasses as J, type KeyMatch as K, augmentedSixthKind as L, MODAL_SCALE_NAMES as M, createArrangementSession as N, detectChord as O, type Phrase as P, detectChordBest as Q, type ReduceProgressionOptions as R, type StructuralCadence as S, type TensionPoint as T, detectKey as U, detectKeyBest as V, detectKeyFromNotes as W, extractMotifs as X, hypermeter as Y, melodicContour as Z, motifFromNotes as _, type ArrangementOptions as a, reduceProgression as a0, relateMotifs as a1, sectionsFromNotes as a2, spellAugmentedSixth as a3, structuralCadences as a4, tensionCurve as a5, tensionCurveFrom as a6, type ArrangementSession as b, type ArrangementTrack as c, type AugmentedSixthKind as d, type Conflict as e, type ContourDirection as f, type DetectKeyOptions as g, type FormSectionOptions as h, type HypermeterOptions as i, type MelodicContour as j, type MelodicContourShape as k, type MelodicPhrase as l, type ModalCandidate as m, type ModalScaleName as n, type MotifData as o, type MotifOccurrence as p, type MotifRelation as q, type MotifRelationKind as r, type PhraseOptions as s, type PhraseSignal as t, type ReducedChord as u, type ReductionBasis as v, type ReductionLevel as w, type TrackAnalysis as x, type TrackEdit as y, type TrackRole as z };