@libraz/libcantus 0.9.1 → 0.9.3

package/dist/analyze/index.d.cts

@@ -0,0 +1,341 @@
+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';
+
+/**
+ * Roman-numeral parsing and formatting.
+ *
+ * The {@link ROMAN_STYLE} table is the single source of truth for both
+ * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
+ * inverses by construction.
+ */
+
+/**
+ * Build the chord denoted by a Roman numeral in a key.
+ *
+ * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
+ * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
+ * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
+ * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
+ * whose root becomes a local major tonic for the applied chord. Inverted chords
+ * carry a `bassPc`.
+ *
+ * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
+ * `m7b5`), since no half-diminished triad exists. Extension and added-tone
+ * suffixes are the canonical case-sensitive forms emitted by
+ * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
+ * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
+ * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
+ * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
+ * A figure string that is neither a recognized inversion nor a supported
+ * quality suffix throws rather than silently degrading to a triad.
+ *
+ * @param text The Roman numeral.
+ * @param key The prevailing key.
+ * @returns The chord.
+ * @example
+ * ```ts
+ * import { romanToChord, majorKey } from '@libraz/libcantus';
+ * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
+ * ```
+ * @category Functional Harmony
+ */
+declare function romanToChord(text: string, key: KeyScale): Chord;
+/**
+ * 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).
+ *
+ * @param chord The chord to name.
+ * @param key The prevailing key.
+ * @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)
+ * ```
+ * @category Functional Harmony
+ */
+declare function chordToRoman(chord: Chord, key: KeyScale): string;
+
+/**
+ * A theory annotation attached to a note.
+ *
+ * @category Arrangement & Analysis
+ */
+type TheoryLabel = {
+    kind: 'chordTone';
+    role: 'root' | 'third' | 'fifth' | 'sixth' | 'seventh';
+} | {
+    kind: 'tension';
+    degree: 9 | 11 | 13;
+} | {
+    kind: 'avoid';
+} | {
+    kind: 'passing';
+} | {
+    kind: 'neighbor';
+} | {
+    kind: 'suspension';
+    type: 'sus4-3' | 'sus7-6' | 'sus9-8' | 'sus2-3';
+    resolveTo: number;
+} | {
+    kind: 'anticipation';
+} | {
+    kind: 'escape';
+} | {
+    kind: 'needsResolution';
+    resolveTo: number;
+} | {
+    kind: 'leadingTone';
+    resolveTo: number;
+};
+/**
+ * A note with its theory labels and a short rationale.
+ *
+ * @category Arrangement & Analysis
+ */
+type AnalyzedNote = {
+    noteId: number;
+    labels: TheoryLabel[];
+    rationale?: string;
+};
+/**
+ * A single note in a monophonic voice: a {@link NoteEvent} with a stable id.
+ *
+ * @category Arrangement & Analysis
+ */
+type VoiceNote = NoteEvent & {
+    id: number;
+};
+/**
+ * Label every note of a voice with its theory roles.
+ *
+ * Each note is classified against the chord sounding at its beat. Chord tones
+ * get a role label; non-chord tones are matched, in order, as suspensions
+ * (prepared by an identical consonant pitch and resolving by step), passing
+ * tones, neighbors, anticipations, and escape tones, then fall back to tension,
+ * avoid, or an unresolved-dissonance label. Leading-tone resolutions are noted
+ * additionally.
+ *
+ * The voice is expected to be monophonic (one note at a time). Notes sharing an
+ * onset are treated as simultaneous cluster members, not melodic neighbors, so
+ * they receive no melodic labels (suspension, passing, neighbor, anticipation,
+ * escape) — only harmonic ones. Callers with truly polyphonic material should
+ * split it into monophonic sub-voices first, as `analyzeArrangement` does.
+ *
+ * @param voice The monophonic voice, in time order.
+ * @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.
+ * @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 },
+ * ];
+ * const cMajor = makeChord(0, 'maj');
+ * 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[];
+
+/**
+ * Arrangement track-role analysis: a single harmony is inferred from every
+ * track's notes pooled together, each track is then analysed against that shared
+ * harmony, and notes that clash with the sounding chord are collected as
+ * conflicts.
+ */
+
+/**
+ * The musical role a track plays in the arrangement.
+ *
+ * @category Arrangement & Analysis
+ */
+type TrackRole = 'melody' | 'harmony' | 'bass' | 'other';
+/**
+ * One input track: its notes plus optional name and role.
+ *
+ * @category Arrangement & Analysis
+ */
+type ArrangementTrack = {
+    name?: string;
+    role?: TrackRole;
+    notes: NoteEvent[];
+};
+/**
+ * A track after analysis: its resolved name, role, and per-note annotations.
+ *
+ * @category Arrangement & Analysis
+ */
+type TrackAnalysis = {
+    name: string;
+    role: TrackRole;
+    /** One {@link AnalyzedNote} per note, labelled against the inferred chords. */
+    notes: AnalyzedNote[];
+};
+/**
+ * A note that clashes with the harmony sounding beneath it.
+ *
+ * @category Arrangement & Analysis
+ */
+type Conflict = {
+    beat: number;
+    trackName: string;
+    pitch: number;
+    /** The clash severity: {@link NoteSafety.Warning} or {@link NoteSafety.Dissonant}. */
+    safety: NoteSafety;
+    /** {@link import('../safety/index.js').SafetyResult.reasons} bitmask. */
+    reasons: number;
+    /** Preferred stepwise resolution, when the safety evaluator provides one. */
+    resolveTo?: number;
+    /** Nearby fully safe replacement pitches, nearest first. */
+    suggestions?: number[];
+    rationale?: string;
+};
+/**
+ * The full result of {@link analyzeArrangement}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ArrangementAnalysis = {
+    key: KeyScale;
+    timeline: ChordTimeline;
+    segmentConfidence: number[];
+    cadences: CadenceHit[];
+    tracks: TrackAnalysis[];
+    /** Notes clashing with the sounding harmony, worst severity first. */
+    conflicts: Conflict[];
+};
+/**
+ * Options controlling {@link analyzeArrangement} and {@link tensionCurve}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ArrangementOptions = {
+    /** Key context; inferred from the pooled notes when omitted. */
+    key?: KeyScale;
+    /**
+     * Time signature; defaults to 4/4.
+     *
+     * @defaultValue `4/4`
+     */
+    ts?: TimeSignature;
+    /**
+     * Chord-slot length in beats; defaults to one bar of `ts`.
+     *
+     * @defaultValue one bar of `ts`
+     */
+    harmonicRhythm?: number;
+    /**
+     * Safety profile used for conflict detection; defaults to `pop`.
+     *
+     * @defaultValue `'pop'`
+     */
+    profile?: SafetyProfile;
+};
+/**
+ * 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.
+ *
+ * Voice analysis assumes one monophonic voice at a time, so each track is
+ * first partitioned into monophonic sub-voices (a polyphonic block-chord track
+ * fans out into one sub-voice per simultaneous note; a monophonic track is
+ * unaffected). Each sub-voice is labelled note-by-note against the harmony
+ * with {@link analyzeVoice}, seeing every other sub-voice — including siblings
+ * within the same track — as its accompaniment. Every note is then re-checked
+ * with {@link evaluateSafety} at its onset and again at each chord change it
+ * sustains across, so a held note that clashes with a later chord is caught:
+ * evaluations that are not {@link NoteSafety.Safe} become conflicts, one per
+ * clashing beat, sorted worst severity first and then by beat.
+ *
+ * @param tracks The tracks to analyse.
+ * @param opts Analysis options; see {@link ArrangementOptions}.
+ * @returns The inferred harmony, per-track annotations, cadences, and conflicts.
+ * @example
+ * ```ts
+ * import { analyzeArrangement } from '@libraz/libcantus';
+ * const melody = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 2 },
+ *   { pitch: 67, startBeat: 2, durationBeat: 2 },
+ * ];
+ * const { key, conflicts } = analyzeArrangement([{ role: 'melody', notes: melody }]);
+ * conflicts; // notes clashing with the inferred harmony, worst severity first
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function analyzeArrangement(tracks: ArrangementTrack[], opts?: ArrangementOptions): ArrangementAnalysis;
+
+/**
+ * Arrangement tension analysis: a coarse harmonic-tension curve sampled at
+ * regular beats across a whole multi-track piece, combining the sounding
+ * chord's harmonic function, the dissonance of the sounding notes, and their
+ * registral span into a single normalized reading.
+ */
+
+/**
+ * A tension reading sampled at a beat.
+ *
+ * @category Arrangement & Analysis
+ */
+type TensionPoint = {
+    beat: number;
+    /** Combined tension in [0, 1]. */
+    tension: number;
+};
+/**
+ * Sample the harmonic tension of an arrangement at regular beats.
+ *
+ * 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};
+ *  - 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};
+ *  - the registral span of the sounding notes, saturating at
+ *    {@link SPAN_SATURATION} semitones, weighted {@link 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.
+ *
+ * @param tracks The tracks to sample.
+ * @param opts Analysis options plus an optional `step` (default one beat).
+ * @returns One {@link TensionPoint} per sampled beat, in beat order.
+ * @throws If `step` is not positive.
+ * @example
+ * ```ts
+ * import { tensionCurve } from '@libraz/libcantus';
+ * const notes = [{ pitch: 60, startBeat: 0, durationBeat: 4 }];
+ * const curve = tensionCurve([{ notes }], { step: 1 });
+ * curve; // one { beat, tension } sample per beat, in beat order
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function tensionCurve(tracks: ArrangementTrack[], 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 };

package/dist/analyze/index.d.ts

@@ -0,0 +1,341 @@
+import { T as TimeSignature } from '../index-Cl7mhOFM.js';
+import { K as KeyScale, N as NoteEvent } from '../types-MGP29r3t.js';
+import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-Jc0Ryi79.js';
+import { b as ChordTimeline, C as CadenceHit } from '../index-DxvARIP2.js';
+export { a as ChordSegment, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from '../index-DxvARIP2.js';
+import { C as Chord } from '../index-Bt4tOUD9.js';
+export { C as ChordMatch, D as DetectChordOptions, K as KeyMatch, d as detectChord, a as detectChordBest, b as detectKey } from '../index-JnF4v9bx.js';
+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-DVH4Eusr.js';
+
+/**
+ * Roman-numeral parsing and formatting.
+ *
+ * The {@link ROMAN_STYLE} table is the single source of truth for both
+ * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
+ * inverses by construction.
+ */
+
+/**
+ * Build the chord denoted by a Roman numeral in a key.
+ *
+ * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
+ * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
+ * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
+ * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
+ * whose root becomes a local major tonic for the applied chord. Inverted chords
+ * carry a `bassPc`.
+ *
+ * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
+ * `m7b5`), since no half-diminished triad exists. Extension and added-tone
+ * suffixes are the canonical case-sensitive forms emitted by
+ * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
+ * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
+ * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
+ * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
+ * A figure string that is neither a recognized inversion nor a supported
+ * quality suffix throws rather than silently degrading to a triad.
+ *
+ * @param text The Roman numeral.
+ * @param key The prevailing key.
+ * @returns The chord.
+ * @example
+ * ```ts
+ * import { romanToChord, majorKey } from '@libraz/libcantus';
+ * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
+ * ```
+ * @category Functional Harmony
+ */
+declare function romanToChord(text: string, key: KeyScale): Chord;
+/**
+ * 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).
+ *
+ * @param chord The chord to name.
+ * @param key The prevailing key.
+ * @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)
+ * ```
+ * @category Functional Harmony
+ */
+declare function chordToRoman(chord: Chord, key: KeyScale): string;
+
+/**
+ * A theory annotation attached to a note.
+ *
+ * @category Arrangement & Analysis
+ */
+type TheoryLabel = {
+    kind: 'chordTone';
+    role: 'root' | 'third' | 'fifth' | 'sixth' | 'seventh';
+} | {
+    kind: 'tension';
+    degree: 9 | 11 | 13;
+} | {
+    kind: 'avoid';
+} | {
+    kind: 'passing';
+} | {
+    kind: 'neighbor';
+} | {
+    kind: 'suspension';
+    type: 'sus4-3' | 'sus7-6' | 'sus9-8' | 'sus2-3';
+    resolveTo: number;
+} | {
+    kind: 'anticipation';
+} | {
+    kind: 'escape';
+} | {
+    kind: 'needsResolution';
+    resolveTo: number;
+} | {
+    kind: 'leadingTone';
+    resolveTo: number;
+};
+/**
+ * A note with its theory labels and a short rationale.
+ *
+ * @category Arrangement & Analysis
+ */
+type AnalyzedNote = {
+    noteId: number;
+    labels: TheoryLabel[];
+    rationale?: string;
+};
+/**
+ * A single note in a monophonic voice: a {@link NoteEvent} with a stable id.
+ *
+ * @category Arrangement & Analysis
+ */
+type VoiceNote = NoteEvent & {
+    id: number;
+};
+/**
+ * Label every note of a voice with its theory roles.
+ *
+ * Each note is classified against the chord sounding at its beat. Chord tones
+ * get a role label; non-chord tones are matched, in order, as suspensions
+ * (prepared by an identical consonant pitch and resolving by step), passing
+ * tones, neighbors, anticipations, and escape tones, then fall back to tension,
+ * avoid, or an unresolved-dissonance label. Leading-tone resolutions are noted
+ * additionally.
+ *
+ * The voice is expected to be monophonic (one note at a time). Notes sharing an
+ * onset are treated as simultaneous cluster members, not melodic neighbors, so
+ * they receive no melodic labels (suspension, passing, neighbor, anticipation,
+ * escape) — only harmonic ones. Callers with truly polyphonic material should
+ * split it into monophonic sub-voices first, as `analyzeArrangement` does.
+ *
+ * @param voice The monophonic voice, in time order.
+ * @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.
+ * @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 },
+ * ];
+ * const cMajor = makeChord(0, 'maj');
+ * 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[];
+
+/**
+ * Arrangement track-role analysis: a single harmony is inferred from every
+ * track's notes pooled together, each track is then analysed against that shared
+ * harmony, and notes that clash with the sounding chord are collected as
+ * conflicts.
+ */
+
+/**
+ * The musical role a track plays in the arrangement.
+ *
+ * @category Arrangement & Analysis
+ */
+type TrackRole = 'melody' | 'harmony' | 'bass' | 'other';
+/**
+ * One input track: its notes plus optional name and role.
+ *
+ * @category Arrangement & Analysis
+ */
+type ArrangementTrack = {
+    name?: string;
+    role?: TrackRole;
+    notes: NoteEvent[];
+};
+/**
+ * A track after analysis: its resolved name, role, and per-note annotations.
+ *
+ * @category Arrangement & Analysis
+ */
+type TrackAnalysis = {
+    name: string;
+    role: TrackRole;
+    /** One {@link AnalyzedNote} per note, labelled against the inferred chords. */
+    notes: AnalyzedNote[];
+};
+/**
+ * A note that clashes with the harmony sounding beneath it.
+ *
+ * @category Arrangement & Analysis
+ */
+type Conflict = {
+    beat: number;
+    trackName: string;
+    pitch: number;
+    /** The clash severity: {@link NoteSafety.Warning} or {@link NoteSafety.Dissonant}. */
+    safety: NoteSafety;
+    /** {@link import('../safety/index.js').SafetyResult.reasons} bitmask. */
+    reasons: number;
+    /** Preferred stepwise resolution, when the safety evaluator provides one. */
+    resolveTo?: number;
+    /** Nearby fully safe replacement pitches, nearest first. */
+    suggestions?: number[];
+    rationale?: string;
+};
+/**
+ * The full result of {@link analyzeArrangement}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ArrangementAnalysis = {
+    key: KeyScale;
+    timeline: ChordTimeline;
+    segmentConfidence: number[];
+    cadences: CadenceHit[];
+    tracks: TrackAnalysis[];
+    /** Notes clashing with the sounding harmony, worst severity first. */
+    conflicts: Conflict[];
+};
+/**
+ * Options controlling {@link analyzeArrangement} and {@link tensionCurve}.
+ *
+ * @category Arrangement & Analysis
+ */
+type ArrangementOptions = {
+    /** Key context; inferred from the pooled notes when omitted. */
+    key?: KeyScale;
+    /**
+     * Time signature; defaults to 4/4.
+     *
+     * @defaultValue `4/4`
+     */
+    ts?: TimeSignature;
+    /**
+     * Chord-slot length in beats; defaults to one bar of `ts`.
+     *
+     * @defaultValue one bar of `ts`
+     */
+    harmonicRhythm?: number;
+    /**
+     * Safety profile used for conflict detection; defaults to `pop`.
+     *
+     * @defaultValue `'pop'`
+     */
+    profile?: SafetyProfile;
+};
+/**
+ * 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.
+ *
+ * Voice analysis assumes one monophonic voice at a time, so each track is
+ * first partitioned into monophonic sub-voices (a polyphonic block-chord track
+ * fans out into one sub-voice per simultaneous note; a monophonic track is
+ * unaffected). Each sub-voice is labelled note-by-note against the harmony
+ * with {@link analyzeVoice}, seeing every other sub-voice — including siblings
+ * within the same track — as its accompaniment. Every note is then re-checked
+ * with {@link evaluateSafety} at its onset and again at each chord change it
+ * sustains across, so a held note that clashes with a later chord is caught:
+ * evaluations that are not {@link NoteSafety.Safe} become conflicts, one per
+ * clashing beat, sorted worst severity first and then by beat.
+ *
+ * @param tracks The tracks to analyse.
+ * @param opts Analysis options; see {@link ArrangementOptions}.
+ * @returns The inferred harmony, per-track annotations, cadences, and conflicts.
+ * @example
+ * ```ts
+ * import { analyzeArrangement } from '@libraz/libcantus';
+ * const melody = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 2 },
+ *   { pitch: 67, startBeat: 2, durationBeat: 2 },
+ * ];
+ * const { key, conflicts } = analyzeArrangement([{ role: 'melody', notes: melody }]);
+ * conflicts; // notes clashing with the inferred harmony, worst severity first
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function analyzeArrangement(tracks: ArrangementTrack[], opts?: ArrangementOptions): ArrangementAnalysis;
+
+/**
+ * Arrangement tension analysis: a coarse harmonic-tension curve sampled at
+ * regular beats across a whole multi-track piece, combining the sounding
+ * chord's harmonic function, the dissonance of the sounding notes, and their
+ * registral span into a single normalized reading.
+ */
+
+/**
+ * A tension reading sampled at a beat.
+ *
+ * @category Arrangement & Analysis
+ */
+type TensionPoint = {
+    beat: number;
+    /** Combined tension in [0, 1]. */
+    tension: number;
+};
+/**
+ * Sample the harmonic tension of an arrangement at regular beats.
+ *
+ * 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};
+ *  - 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};
+ *  - the registral span of the sounding notes, saturating at
+ *    {@link SPAN_SATURATION} semitones, weighted {@link 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.
+ *
+ * @param tracks The tracks to sample.
+ * @param opts Analysis options plus an optional `step` (default one beat).
+ * @returns One {@link TensionPoint} per sampled beat, in beat order.
+ * @throws If `step` is not positive.
+ * @example
+ * ```ts
+ * import { tensionCurve } from '@libraz/libcantus';
+ * const notes = [{ pitch: 60, startBeat: 0, durationBeat: 4 }];
+ * const curve = tensionCurve([{ notes }], { step: 1 });
+ * curve; // one { beat, tension } sample per beat, in beat order
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function tensionCurve(tracks: ArrangementTrack[], 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 };