@libraz/libcantus 0.9.3 → 0.9.4

package/dist/analyze/index.d.cts

@@ -1,11 +1,12 @@
-import { T as TimeSignature } from '../index-Cl7mhOFM.cjs';
-import { K as KeyScale, N as NoteEvent } from '../types-MGP29r3t.cjs';
-import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-CxqBQtH1.cjs';
-import { b as ChordTimeline, C as CadenceHit } from '../index-CpOsP1y9.cjs';
-export { a as ChordSegment, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from '../index-CpOsP1y9.cjs';
-import { C as Chord } from '../index-BNlGP86A.cjs';
-export { C as ChordMatch, D as DetectChordOptions, K as KeyMatch, d as detectChord, a as detectChordBest, b as detectKey } from '../index-CnZCo29u.cjs';
-export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from '../function-DYt4iKsn.cjs';
+import { T as TimeSignature } from '../index-DXd9JikN.cjs';
+import { K as KeyScale, N as NoteEvent } from '../types-BN6_Q9Kl.cjs';
+import { C as Chord, d as ChordToneRole } from '../index-y_ak9_Hi.cjs';
+export { a as ChordQuality, b as ChordSegment, c as ChordSpan, P as PitchSpelling } from '../index-y_ak9_Hi.cjs';
+import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-tJhkmQgE.cjs';
+import { a as ChordTimeline, C as CadenceHit } from '../index-Be74mcon.cjs';
+export { b as ChordTimelineOptions, c as ChordTimelineResult, d as chordTimelineFromChords, e as chordTimelineFromNotes, f as detectCadences } from '../index-Be74mcon.cjs';
+export { C as ChordMatch, D as DetectChordOptions, a as DetectKeyOptions, K as KeyMatch, b as KeyVariant, d as detectChord, c as detectChordBest, e as detectKey, f as detectKeyBest, g as detectKeyFromNotes } from '../index-BtXT6UQ0.cjs';
+export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFunction, b as analyzeChord, c as borrowedSource, d as detectCadence, f as functionOf, i as isBorrowedChord, e as isDiatonic, g as isMinorKey, p as parallelKey, s as secondaryDominant } from '../function-DNugAOrt.cjs';
 
 /**
  * Roman-numeral parsing and formatting.
@@ -46,30 +47,64 @@ export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, H as HarmonicFun
  * @category Functional Harmony
  */
 declare function romanToChord(text: string, key: KeyScale): Chord;
+/**
+ * Options for {@link chordToRoman}.
+ *
+ * @category Functional Harmony
+ */
+type ChordToRomanOptions = {
+    /**
+     * Render a tonicizing chord as an applied numeral (`V7/V`, `viio7/ii`)
+     * instead of naming its root against the home key (`II7`, `#ivo7`).
+     *
+     * Off by default: naming the root is always a correct spelling, whereas
+     * whether a chromatic dominant is genuinely applied is a reading only the
+     * caller can make. Turning it on makes {@link chordToRoman} the exact inverse
+     * of {@link romanToChord} for the chords {@link secondaryDominant} builds.
+     */
+    applied?: boolean;
+};
 /**
  * Render a chord as a Roman numeral relative to a key.
  *
  * Diatonic roots take their scale-degree numeral directly, so numerals are
  * correct in both major and minor keys (and any custom scale). The quality
  * selects the case and suffix; chromatic roots receive a flat/sharp spelling by
- * convention. When the chord carries a `bassPc` on a chord tone, a figured-bass
- * inversion (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true
- * seventh chords; added-tone and extended qualities have no lossless figure and
- * render in root position instead (the bass is dropped, pitch classes are
- * preserved).
+ * convention. A key that is not heptatonic has no numeral of its own for every
+ * degree, so its roots are named against its parallel major.
+ *
+ * When the chord carries a `bassPc` on a chord tone, a figured-bass inversion
+ * (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true seventh
+ * chords; added-tone and extended qualities have no lossless figure and render
+ * in root position instead (the bass is dropped, pitch classes are preserved).
+ *
+ * A `bassPc` that is *not* a chord tone — a pedal or passing bass such as
+ * `C/D` — is likewise dropped, and the numeral names the upper chord alone.
+ * Roman-numeral notation spends its slash on applied chords (`V7/V`), so there
+ * is no unambiguous way to write such a bass; a caller that must keep it should
+ * read `chord.bassPc` alongside the numeral.
  *
  * @param chord The chord to name.
  * @param key The prevailing key.
+ * @param opts `applied` renders tonicizing chords as `V7/V`-style numerals.
  * @returns The Roman numeral string.
  * @example
  * ```ts
  * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
  * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
+ * chordToRoman(makeChord(2, 'dom7'), majorKey(0), { applied: true }); // => 'V7/V'
  * ```
  * @category Functional Harmony
  */
-declare function chordToRoman(chord: Chord, key: KeyScale): string;
+declare function chordToRoman(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): string;
 
+/**
+ * A suspension figure, named by the interval above the bass and the interval it
+ * resolves to.
+ *
+ * @category Arrangement & Analysis
+ */
+type SuspensionFigure = 'sus4-3' | 'sus6-5' | 'sus7-6' | 'sus9-8' | 'sus2-3';
 /**
  * A theory annotation attached to a note.
  *
@@ -77,7 +112,7 @@ declare function chordToRoman(chord: Chord, key: KeyScale): string;
  */
 type TheoryLabel = {
     kind: 'chordTone';
-    role: 'root' | 'third' | 'fifth' | 'sixth' | 'seventh';
+    role: ChordToneRole;
 } | {
     kind: 'tension';
     degree: 9 | 11 | 13;
@@ -89,7 +124,7 @@ type TheoryLabel = {
     kind: 'neighbor';
 } | {
     kind: 'suspension';
-    type: 'sus4-3' | 'sus7-6' | 'sus9-8' | 'sus2-3';
+    type: SuspensionFigure;
     resolveTo: number;
 } | {
     kind: 'anticipation';
@@ -105,21 +140,60 @@ type TheoryLabel = {
 /**
  * A note with its theory labels and a short rationale.
  *
+ * The labels describe the note against the chord sounding at its **onset**;
+ * they are not re-derived for the later chords a long note sustains across.
+ * `analyzeArrangement` does re-check every crossed chord change, and reports
+ * what it finds as conflicts, so a note labelled a chord tone here can still
+ * appear in `conflicts` at a later beat.
+ *
+ * The identity fields make an annotation mappable back to the caller's input:
+ * `originalIndex` is the note's position in the array that was passed in, and
+ * `trackIndex` is set by {@link analyzeArrangement}.
+ *
  * @category Arrangement & Analysis
  */
 type AnalyzedNote = {
     noteId: number;
+    /** The note's index in the caller's own array, when the caller supplied one. */
+    originalIndex?: number;
+    /** The note's track, set by `analyzeArrangement`. */
+    trackIndex?: number;
+    pitch: number;
+    startBeat: number;
+    durationBeat: number;
     labels: TheoryLabel[];
     rationale?: string;
 };
 /**
- * A single note in a monophonic voice: a {@link NoteEvent} with a stable id.
+ * A single note in a monophonic voice: a {@link NoteEvent} with a stable id and,
+ * optionally, its index in the caller's original array.
  *
  * @category Arrangement & Analysis
  */
 type VoiceNote = NoteEvent & {
+    id?: number;
+    originalIndex?: number;
+};
+/**
+ * A voice note whose id has been assigned, as {@link toVoiceNotes} returns and
+ * {@link analyzeArrangement} works in.
+ *
+ * @category Arrangement & Analysis
+ */
+type IdentifiedVoiceNote = VoiceNote & {
     id: number;
 };
+/**
+ * Give plain note events the ids {@link analyzeVoice} reports back.
+ *
+ * The id is only an identity handle, so the array position serves; this exists
+ * so the mapping is a named call rather than a `map` every caller writes.
+ *
+ * @param events The note events, in time order.
+ * @returns The same notes as voice notes, each carrying its index as its id.
+ * @category Arrangement & Analysis
+ */
+declare function toVoiceNotes(events: readonly NoteEvent[]): IdentifiedVoiceNote[];
 /**
  * Label every note of a voice with its theory roles.
  *
@@ -136,26 +210,28 @@ type VoiceNote = NoteEvent & {
  * escape) — only harmonic ones. Callers with truly polyphonic material should
  * split it into monophonic sub-voices first, as `analyzeArrangement` does.
  *
- * @param voice The monophonic voice, in time order.
+ * @param voice The monophonic voice, in time order. A note without an `id` is
+ *   identified by its position, so plain note events can be passed straight in.
  * @param chordAtBeat Chord sounding at a given beat, or null.
  * @param key Key context for leading-tone detection.
- * @param otherVoicesAtBeat Other sounding voices at a given beat.
+ * @param otherVoicesAtBeat Other sounding voices at a given beat; defaults to
+ *   none, which is the whole story for a solo line.
  * @returns One annotation per input note.
  * @example
  * ```ts
  * import { analyzeVoice, makeChord, majorKey } from '@libraz/libcantus';
  * const voice = [
- *   { id: 0, pitch: 60, startBeat: 0, durationBeat: 1 },
- *   { id: 1, pitch: 62, startBeat: 1, durationBeat: 1 },
- *   { id: 2, pitch: 64, startBeat: 2, durationBeat: 1 },
+ *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+ *   { pitch: 64, startBeat: 2, durationBeat: 1 },
  * ];
  * const cMajor = makeChord(0, 'maj');
- * const labels = analyzeVoice(voice, () => cMajor, majorKey(0), () => []);
+ * const labels = analyzeVoice(voice, () => cMajor, majorKey(0));
  * labels; // one AnalyzedNote per input note, in the same order
  * ```
  * @category Arrangement & Analysis
  */
-declare function analyzeVoice(voice: VoiceNote[], chordAtBeat: (beat: number) => Chord | null, key: KeyScale, otherVoicesAtBeat: (beat: number) => VoiceSnapshot[]): AnalyzedNote[];
+declare function analyzeVoice(voice: readonly VoiceNote[], chordAtBeat: (beat: number) => Chord | null, key: KeyScale, otherVoicesAtBeat?: (beat: number) => VoiceSnapshot[]): AnalyzedNote[];
 
 /**
  * Arrangement track-role analysis: a single harmony is inferred from every
@@ -167,9 +243,18 @@ declare function analyzeVoice(voice: VoiceNote[], chordAtBeat: (beat: number) =>
 /**
  * The musical role a track plays in the arrangement.
  *
+ * Only `drums` changes the analysis: its pitches select instruments rather than
+ * naming harmony, so such a track is excluded from chord and key inference and
+ * from every voice-leading comparison, and is reported back with no
+ * annotations. `harmony` is meaningful through
+ * {@link ArrangementOptions.harmonyTracks}, which names the tracks the chords
+ * are inferred from. The rest are labels carried through to
+ * {@link TrackAnalysis.role} for the caller's own use; nothing is inferred, so
+ * a track left unlabelled reports `'other'` rather than a guess.
+ *
  * @category Arrangement & Analysis
  */
-type TrackRole = 'melody' | 'harmony' | 'bass' | 'other';
+type TrackRole = 'melody' | 'harmony' | 'bass' | 'drums' | 'other';
 /**
  * One input track: its notes plus optional name and role.
  *
@@ -178,7 +263,7 @@ type TrackRole = 'melody' | 'harmony' | 'bass' | 'other';
 type ArrangementTrack = {
     name?: string;
     role?: TrackRole;
-    notes: NoteEvent[];
+    notes: readonly NoteEvent[];
 };
 /**
  * A track after analysis: its resolved name, role, and per-note annotations.
@@ -199,10 +284,22 @@ type TrackAnalysis = {
 type Conflict = {
     beat: number;
     trackName: string;
+    /** The clashing track's index in the caller's input array. */
+    trackIndex: number;
+    /** The note's index in that track's own note array. */
+    originalIndex?: number;
+    /** The id the note carries in {@link TrackAnalysis.notes}. */
+    noteId: number;
     pitch: number;
+    /**
+     * The note's theory labels at its onset, so a caller can tell a genuine clash
+     * from a passing tone, a neighbour, or a prepared suspension — all of which
+     * are ordinary non-chord tones that still evaluate as unsafe.
+     */
+    labels: TheoryLabel[];
     /** The clash severity: {@link NoteSafety.Warning} or {@link NoteSafety.Dissonant}. */
     safety: NoteSafety;
-    /** {@link import('../safety/index.js').SafetyResult.reasons} bitmask. */
+    /** {@link SafetyResult.reasons} bitmask. */
     reasons: number;
     /** Preferred stepwise resolution, when the safety evaluator provides one. */
     resolveTo?: number;
@@ -232,6 +329,23 @@ type ArrangementAnalysis = {
 type ArrangementOptions = {
     /** Key context; inferred from the pooled notes when omitted. */
     key?: KeyScale;
+    /**
+     * A chord timeline to analyse against, instead of inferring one from the
+     * notes. Supply it to analyse a hand-written progression, or to reuse the
+     * timeline of an earlier call rather than re-running chord inference.
+     */
+    timeline?: ChordTimeline;
+    /**
+     * Indices of the tracks the harmony is inferred from. Defaults to every
+     * pitched track. Percussion tracks are excluded either way.
+     */
+    harmonyTracks?: number[];
+    /**
+     * Lowest severity reported in `conflicts`.
+     *
+     * @defaultValue {@link NoteSafety.Warning}
+     */
+    minSeverity?: NoteSafety;
     /**
      * Time signature; defaults to 4/4.
      *
@@ -250,16 +364,31 @@ type ArrangementOptions = {
      * @defaultValue `'pop'`
      */
     profile?: SafetyProfile;
+    /**
+     * Upper bound on the work this call may do — note counts, windows, and
+     * candidate counts are each checked against it before anything is allocated.
+     *
+     * Raise it to analyse a piece larger than the default allows; the default is
+     * {@link DEFAULT_GENERATION_BUDGET}, chosen so a runaway input fails fast
+     * rather than blocking the thread.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
 };
 /**
  * Analyse a whole arrangement against a single inferred harmony.
  *
- * The chord timeline and key are inferred from the pooled notes of every track
- * (see {@link chordTimelineFromNotes}); pooling all voices is robust even when
- * roles are absent or a track doubles the harmony, so it is preferred over
- * deriving the harmony from a subset. Zero- and negative-length notes never
- * sound, so they are dropped at ingest and appear in neither the annotations
- * nor the conflicts.
+ * The chord timeline and key are inferred from the pooled notes of every
+ * pitched track (see {@link chordTimelineFromNotes}); pooling all voices is
+ * robust even when roles are absent or a track doubles the harmony, so it is
+ * preferred over deriving the harmony from a subset. A track marked
+ * `role: 'drums'` is excluded — its pitches name instruments, not harmony, and
+ * pooling them would corrupt the key, the timeline and every reading built on
+ * them. Pass `harmonyTracks` to restrict inference further, or `timeline` to
+ * analyse against a progression you already have. Zero- and negative-length
+ * notes never sound, so they are dropped at ingest and appear in neither the
+ * annotations nor the conflicts.
  *
  * Voice analysis assumes one monophonic voice at a time, so each track is
  * first partitioned into monophonic sub-voices (a polyphonic block-chord track
@@ -272,6 +401,13 @@ type ArrangementOptions = {
  * evaluations that are not {@link NoteSafety.Safe} become conflicts, one per
  * clashing beat, sorted worst severity first and then by beat.
  *
+ * Every ordinary non-chord tone — a passing note, a neighbour, a prepared
+ * suspension — is by definition unsafe against the chord under it, so the
+ * conflict list is a report, not a fault list. Each conflict carries the note's
+ * `labels` and its `trackIndex`/`originalIndex`, so a caller can tell those
+ * apart and map a conflict back to the note it passed in; `minSeverity` narrows
+ * the list to outright dissonance.
+ *
  * @param tracks The tracks to analyse.
  * @param opts Analysis options; see {@link ArrangementOptions}.
  * @returns The inferred harmony, per-track annotations, cadences, and conflicts.
@@ -311,12 +447,12 @@ type TensionPoint = {
  *
  * At each sample beat the tension combines three normalized terms:
  *  - the sounding chord's harmonic function (dominant `1`, subdominant `0.5`,
- *    tonic or no chord `0`), weighted {@link FUNCTION_WEIGHT};
+ *    tonic or no chord `0`), weighted `FUNCTION_WEIGHT`;
  *  - the dissonance of the sounding notes — the larger of the share of sounding
  *    pitches that are not chord tones and the share that {@link evaluateSafety}
- *    rates {@link NoteSafety.Dissonant} — weighted {@link DISSONANCE_WEIGHT};
+ *    rates {@link NoteSafety.Dissonant} — weighted `DISSONANCE_WEIGHT`;
  *  - the registral span of the sounding notes, saturating at
- *    {@link SPAN_SATURATION} semitones, weighted {@link SPAN_WEIGHT}.
+ *    `SPAN_SATURATION` semitones, weighted `SPAN_WEIGHT`.
  *
  * The weighted sum is clamped to [0, 1]. The harmony is inferred from all tracks
  * pooled together, so the result is deterministic and self-contained.
@@ -337,5 +473,29 @@ type TensionPoint = {
 declare function tensionCurve(tracks: ArrangementTrack[], opts?: ArrangementOptions & {
     step?: number;
 }): TensionPoint[];
+/**
+ * Sample the tension of an arrangement already analysed by
+ * {@link analyzeArrangement}, reusing its harmony instead of inferring it again.
+ *
+ * `analyzeArrangement` followed by `tensionCurve` runs chord and key inference
+ * twice over the same notes. This takes the analysis it already produced, so
+ * the curve and the annotations describe the same harmony by construction.
+ *
+ * @param tracks The same tracks that were analysed.
+ * @param analysis The result of {@link analyzeArrangement} for those tracks.
+ * @param opts Analysis options plus an optional `step` (default one beat).
+ * @returns One {@link TensionPoint} per sampled beat, in beat order.
+ * @example
+ * ```ts
+ * import { analyzeArrangement, tensionCurveFrom } from '@libraz/libcantus';
+ * const tracks = [{ notes: [{ pitch: 60, startBeat: 0, durationBeat: 4 }] }];
+ * const analysis = analyzeArrangement(tracks);
+ * tensionCurveFrom(tracks, analysis, { step: 1 });
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function tensionCurveFrom(tracks: ArrangementTrack[], analysis: ArrangementAnalysis, opts?: ArrangementOptions & {
+    step?: number;
+}): TensionPoint[];
 
-export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, ChordTimeline, type Conflict, type TensionPoint, type TheoryLabel, type TrackAnalysis, type TrackRole, type VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, romanToChord, tensionCurve };
+export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, Chord as ChordData, ChordTimeline, type ChordToRomanOptions, ChordToneRole, type Conflict, type IdentifiedVoiceNote, KeyScale, NoteEvent, NoteSafety, SafetyProfile, type SuspensionFigure, type TensionPoint, type TheoryLabel, TimeSignature, type TrackAnalysis, type TrackRole, type VoiceNote, VoiceSnapshot, analyzeArrangement, analyzeVoice, chordToRoman, romanToChord, tensionCurve, tensionCurveFrom, toVoiceNotes };