@libraz/libcantus 1.1.0 → 1.3.0

package/dist/{index-BUtIf2go.d.ts → profile-DLdlIpS9.d.ts}

@@ -1,8 +1,8 @@
-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';
+import { e as KeyScale, h as NoteEvent, i as NoteLike, g as Note } from './index-Cy15oTvh.js';
+import { d as ChordQuality, k as KeyVariant, b as Chord, r as SpelledKeyLike, c as ChordLike, K as KeyLike, n as ResolvedKey, N as NoteSafety, o as SafetyProfile } from './coerce-DP0vYu-x.js';
+import { r as ScaleName } from './masks-Cc7-MzzY.js';
+import { p as KeyProfileName, q as KeyProfilePair, a6 as RejectedCandidate, r as KeyRegion, h as ChordTimeline, c as CadenceHit, a as AnalyzedNote, ab as TheoryLabel, K as KeyContext, d as CadenceResult, a5 as ReferenceProfile } from './types-Dh7C064C.js';
+import { b as MeterLike } from './index-CL4b4gUQ.js';
 
 /**
  * Church-mode candidates for {@link detectKey}.
@@ -603,6 +603,21 @@ type TrackAnalysis = {
     /** One {@link AnalyzedNote} per note, labelled against the inferred chords. */
     notes: AnalyzedNote[];
 };
+/**
+ * A note sounding with a {@link Conflict} that raises a pairwise flag against it.
+ *
+ * @category Arrangement & Analysis
+ */
+type ConflictPartner = {
+    /** The partner's track index in the caller's input array. */
+    trackIndex: number;
+    /** The partner note's index in that track's own note array. */
+    originalIndex?: number;
+    /** The id the partner note carries in {@link TrackAnalysis.notes}. */
+    noteId: number;
+    /** The pairwise flags this note raises, as {@link SafetyPartner.reasons}. */
+    reasons: number;
+};
 /**
  * A note that clashes with the harmony sounding beneath it.
  *
@@ -632,6 +647,11 @@ type Conflict = {
     resolveTo?: number;
     /** Nearby fully safe replacement pitches, nearest first. */
     suggestions?: number[];
+    /**
+     * The notes behind the pairwise flags in `reasons` — a parallel fifth, a
+     * crossing, a vertical clash — when any are set.
+     */
+    partners?: ConflictPartner[];
     rationale?: string;
 };
 /**
@@ -1367,56 +1387,24 @@ declare function phrasesFromTimeline(timeline: ChordTimeline, notes: readonly No
 declare function structuralCadences(phrases: readonly Phrase[]): StructuralCadence[];
 
 /**
- * Sections: the largest unit this library reads, recovered from repetition.
- *
- * A section is found, not named. What the analysis can see is that a span of
- * music is a restatement of an earlier one, so the spans are labelled by order
- * of first appearance — A, B, C — and nothing more is claimed. Calling a
- * repeated span a chorus would be a guess dressed as a finding: repetition
- * alone cannot tell a chorus from a second verse, and the label a listener
- * would give depends on lyrics, arrangement and loudness that the notes do not
- * carry.
- */
-
-/**
- * A span of music labelled by which earlier span it restates.
+ * Reading a piece into a {@link ReferenceProfile}.
  *
- * @category Arrangement & Analysis
+ * The profile is assembled from analyses the library already runs — chord and
+ * key inference, hypermeter, phrases, sections, reduction, motifs and rhythm —
+ * each run exactly once and all read against one span: every analysis is handed
+ * the same `totalBeats`, so the phrases, sections and both rhythm readings
+ * describe the same stretch of music. The harmonic reading enters as a bundle
+ * of its own, so a caller already holding one (a score's kept chord analysis,
+ * an arrangement's session) builds the profile from it without inferring the
+ * harmony a second time.
  */
-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}.
+ * Options for {@link analyzeReference}.
  *
  * @category Arrangement & Analysis
  */
-type FormSectionOptions = {
+type ReferenceProfileOptions = {
     /**
      * 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.
@@ -1425,586 +1413,85 @@ type FormSectionOptions = {
      */
     ts?: MeterLike;
     /**
-     * The meter as it changes over the span, so a piece that changes metre is cut
-     * at its own bar lines.
+     * The meter as it changes over the span.
      *
      * @defaultValue 4/4 throughout
      */
     meters?: MeterLike;
     /**
-     * Length of the unit spans are compared in, in bars; defaults to one hyperbar.
+     * The key, when it is already known: read as one key across the whole span,
+     * as {@link chordTimelineFromNotes} reads it. Omit it to have the keys
+     * searched for over time.
      *
-     * 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.
+     * @defaultValue the keys inferred from the notes over time
      */
-    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 = {
+    key?: KeyLike;
     /**
-     * Shortest cell to report, in notes.
+     * The harmony, given rather than inferred — the shape an arrangement's
+     * `timeline` option takes. The key regions are still read from `key` or,
+     * without one, from the notes.
      *
-     * @defaultValue 3
+     * @defaultValue inferred from the notes
      */
-    minNotes?: number;
+    timeline?: ChordTimeline;
     /**
-     * Longest cell to report, in notes.
+     * The melodic line. Omit it to read the top line of `notes`, where notes
+     * struck together are one event and the highest of them stands for it.
      *
-     * @defaultValue 8
+     * @defaultValue the top line of the notes
      */
-    maxNotes?: number;
+    melody?: readonly NoteEvent[];
     /**
-     * How many statements a cell needs before it is reported.
+     * End of the analysed span in beats.
      *
-     * @defaultValue 2
+     * @defaultValue the end of the last note or chord segment
      */
-    minOccurrences?: number;
+    totalBeats?: number;
     /**
-     * Upper bound on the work this call may do.
+     * Upper bound on the work each analysis 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.
+ * Read a piece's structure into a {@link ReferenceProfile}: its form, phrase
+ * shapes, harmonic function and rhythm, motif derivations and melodic rhythm,
+ * without the notes themselves.
+ *
+ * The melody is the `melody` option when given, and otherwise the top line of
+ * the notes — notes struck together read as one event, the highest standing
+ * for it — so a piano part read whole answers for its upper voice. The harmony
+ * is the `timeline` option when given, and otherwise inferred from all the
+ * notes. The motif search expects quantized onsets.
+ *
+ * The sections are cut on the hyperbar grouping the phrase reading settles
+ * on, which weighs where the harmony cadences; `sectionsFromNotes` alone
+ * groups without the cadences, so the two can differ.
+ *
+ * @param notes The piece's notes, in any order. Notes that never sound are dropped.
+ * @param opts The meter, key, harmony, melody, span end and budget; see
+ *   {@link ReferenceProfileOptions}.
+ * @returns The profile.
+ * @throws {InvalidInputError} If the notes or an option cannot be read.
+ * @throws {BudgetExceededError} If an analysis would exceed the budget.
  * @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 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, 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';
+ * import { analyzeReference } from '@libraz/libcantus';
+ * const triad = (pitches: number[], startBeat: number) =>
+ *   pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
  * const notes = [
- *   { pitch: 60, startBeat: 0, durationBeat: 1 },
- *   { pitch: 64, startBeat: 1, durationBeat: 1 },
- *   { pitch: 60, startBeat: 2, durationBeat: 1 },
+ *   ...triad([60, 64, 67], 0),
+ *   ...triad([65, 69, 72], 4),
+ *   ...triad([67, 71, 74], 8),
+ *   ...triad([60, 64, 67], 12),
  * ];
- * 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.
- */
-
-/**
- * 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.
- *
- * `analyzeVoice` can say that a note is a passing tone; a timeline is flat, so
- * nothing could say the same of a chord. This is that answer one level up — the
- * middle chord of `Cmaj7 - C#dim7 - Dm7` is an embellishment, and the frame
- * under `I - IV - #ivo7 - V - I` is `I - IV - V - I`.
- *
- * **The position taken here.** What counts as structural is a theoretical
- * choice, not a fact, and this module makes the functional one: *a chord is
- * structural unless it is demonstrably an embellishment of its neighbours*. The
- * frame is what carries harmonic function in the prevailing key — the tonic, the
- * dominant, and the chords that cadence — so those are never reduced away; a
- * chord that tonicizes something other than the tonic is prolonging, not
- * framing, however dominant its sonority. Everything else keeps its place unless
- * its root traces one of two figures against the chords around it, the same two
- * figures {@link analyzeVoice} matches at the note level: a step through
- * (passing) and a step away and back (neighbor). Defaulting to structural, and
- * demoting only on evidence, is what keeps a reduction from quietly deleting
- * harmony it merely failed to recognize.
- *
- * The salience reading — that the frame is whatever lasts longest, regardless of
- * function — is the main alternative, and it is a live one for repertoire where
- * function is weak. {@link ReduceProgressionOptions.basis} switches to it: the
- * figures stay the same, only what protects a chord from them changes.
- *
- * Both readings are deterministic: the same timeline and key always reduce the
- * same way.
- */
-
-/**
- * The place a chord holds in a progression.
- *
- * `'structural'` is the frame; `'passing'` and `'neighbor'` are the two
- * embellishing figures, spelled exactly as {@link TheoryLabel} spells them for
- * a note, so one legend covers both levels of analysis.
- *
- * @category Arrangement & Analysis
- */
-type ReductionLevel = 'structural' | 'passing' | 'neighbor';
-/**
- * A chord with the place it holds, the beats it holds it for, and a short
- * rationale.
- *
- * One entry per timeline segment, in the same order. The entry carries the
- * segment's own beat range, so the chords that survive a filter still say when
- * they sound: holding the structural chords fixed is what a reharmonizer needs,
- * and it cannot hold a chord at a place the filter threw away.
- *
- * @category Arrangement & Analysis
- */
-type ReducedChord = {
-    chord: Chord;
-    startBeat: number;
-    endBeat: number;
-    level: ReductionLevel;
-    rationale: string;
-};
-/**
- * What a reduction treats as the frame.
- *
- * `'function'` is the functional reading: the tonic, the dominant and the
- * chords that cadence are the frame. `'duration'` is the salience reading: 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']
+ * const profile = analyzeReference(notes, { key: 'C major' });
+ * profile.harmony.chords.map((chord) => chord.roman); // ['I', 'IV', 'V', 'I']
+ * profile.span.bars; // 4
  * ```
  * @category Arrangement & Analysis
  */
-declare function reduceProgression(timeline: ChordTimeline, key: KeyContext, opts?: ReduceProgressionOptions): ReducedChord[];
+declare function analyzeReference(notes: readonly NoteEvent[], opts?: ReferenceProfileOptions): ReferenceProfile;
 
-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 };
+export { type ArrangementAnalysis as A, detectKeyFromNotes as B, type ChordMatch as C, type DetectChordOptions as D, hypermeter as E, phrasesFromTimeline as F, spellAugmentedSixth as G, type Hypermeter as H, structuralCadences as I, tensionCurve as J, type KeyMatch as K, tensionCurveFrom as L, MODAL_SCALE_NAMES as M, type Phrase as P, type ReferenceProfileOptions as R, type StructuralCadence as S, type TensionPoint as T, type ArrangementOptions as a, type ArrangementSession as b, type ArrangementTrack as c, type AugmentedSixthKind as d, type Conflict as e, type ConflictPartner as f, type DetectKeyOptions as g, type HypermeterOptions as h, type ModalCandidate as i, type ModalScaleName as j, type PhraseOptions as k, type PhraseSignal as l, type TrackAnalysis as m, type TrackEdit as n, type TrackRole as o, analyzeArrangement as p, analyzePolyphony as q, analyzeReference as r, augmentedSixthChord as s, augmentedSixthFromPitchClasses as t, augmentedSixthKind as u, createArrangementSession as v, detectChord as w, detectChordBest as x, detectKey as y, detectKeyBest as z };