@libraz/libcantus 0.9.0 → 0.9.2

package/dist/analyze/index.d.cts

@@ -0,0 +1,429 @@
+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-DZ1M21do.cjs';
+import { b as ChordTimeline, C as CadenceHit } from '../index-D_ZTUNKp.cjs';
+export { a as ChordSegment, c as ChordTimelineOptions, d as ChordTimelineResult, e as chordTimelineFromChords, f as chordTimelineFromNotes, g as detectCadences } from '../index-D_ZTUNKp.cjs';
+import { C as Chord, a as ChordQuality } from '../index-BOBXBNwP.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-r2sh-jOO.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;
+    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[];
+
+/**
+ * Recognition: infer a chord name from a set of pitches, or a key from a set of
+ * pitch classes. This is the inverse direction of the chord/scale builders,
+ * which only go name -> notes.
+ */
+
+/**
+ * A candidate chord interpretation of a pitch set.
+ *
+ * @category Recognition
+ */
+type ChordMatch = {
+    rootPc: number;
+    quality: ChordQuality;
+    /** Chord tones absent from the input (an incomplete voicing). */
+    missingPcs: number[];
+    /** Input pitch classes not belonging to the chord. */
+    extraPcs: number[];
+    /** True when the input pitch-class set equals the chord exactly. */
+    exact: boolean;
+    /** Inversion implied by the lowest note: 0 root position, 1 first, ... */
+    inversion: number;
+    /** Bass pitch class when inverted (the lowest note is not the root). */
+    bassPc?: number;
+};
+/**
+ * A candidate key interpretation of a pitch-class set.
+ *
+ * @category Recognition
+ */
+type KeyMatch = {
+    key: KeyScale;
+    mode: 'major' | 'minor';
+    /** Fraction of input pitch classes that are in the scale, in [0, 1]. */
+    fit: number;
+};
+/**
+ * Identify chords matching a set of pitches.
+ *
+ * Every input pitch class is tried as a root against every known chord quality.
+ * 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.
+ *
+ * @param pitches MIDI pitches or bare pitch classes (octave-agnostic).
+ * @returns Ranked chord interpretations (may be empty).
+ * @example
+ * ```ts
+ * import { detectChord } from '@libraz/libcantus';
+ * const matches = detectChord([60, 64, 67]); // C E G
+ * matches[0]; // { rootPc: 0, quality: 'maj', exact: true, ... }
+ * ```
+ * @category Recognition
+ */
+declare function detectChord(pitches: number[]): ChordMatch[];
+/**
+ * The single best chord interpretation of a pitch set, or null if none.
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @returns The top-ranked chord, or null when nothing matches.
+ * @example
+ * ```ts
+ * import { detectChordBest } from '@libraz/libcantus';
+ * detectChordBest([60, 64, 67]); // C major triad: { rootPc: 0, quality: 'maj', ... }
+ * ```
+ * @category Recognition
+ */
+declare function detectChordBest(pitches: number[]): Chord | null;
+/**
+ * Rank major and minor keys by how well they contain a set of pitch classes.
+ *
+ * The tonic is weighted so that, among equally-fitting keys, the one whose root
+ * appears in the input is preferred. Minor candidates are scored against the
+ * natural, harmonic, and melodic minor variants and keep the best of the three,
+ * so a minor cadence containing the leading tone still resolves to its own
+ * tonic; the returned key is always the natural-minor scale. Returns all 24
+ * keys ranked best-first, or an empty array for an empty input (mirroring
+ * {@link detectChord}).
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @returns Ranked key interpretations (empty for an empty input).
+ * @example
+ * ```ts
+ * 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
+ * ```
+ * @category Recognition
+ */
+declare function detectKey(pitches: number[]): KeyMatch[];
+
+export { type AnalyzedNote, type ArrangementAnalysis, type ArrangementOptions, type ArrangementTrack, CadenceHit, type ChordMatch, ChordTimeline, type Conflict, type KeyMatch, type TensionPoint, type TheoryLabel, type TrackAnalysis, type TrackRole, type VoiceNote, analyzeArrangement, analyzeVoice, chordToRoman, detectChord, detectChordBest, detectKey, romanToChord, tensionCurve };