@libraz/libcantus 0.9.4 → 1.0.0

package/dist/analyze/index.d.cts

@@ -1,501 +1,258 @@
-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';
+import { h as NoteLike, f as Note, g as NoteEvent } from '../index-B9MNZboQ.cjs';
+export { a as Articulation, b as IntervalQualityLabel, d as KeyScale, S as SpelledInterval } from '../index-B9MNZboQ.cjs';
+export { M as MeterChange, b as MeterLike, c as MeterMap, T as TimeSignature } from '../index-BkGmlyI3.cjs';
+import { K as KeyLike, b as Chord, c as ChordLike } from '../index-C_8o--VE.cjs';
+export { d as ChordQuality, e as ChordSegment, g as ChordSpan, j as ChordToneRole, k as KeyRelation, N as NoteSafety, l as PitchSpelling, S as SafetyProfile, V as VoiceSnapshot } from '../index-C_8o--VE.cjs';
+export { r as ScaleName } from '../masks-DYbE485J.cjs';
+export { A as ArrangementAnalysis, a as ArrangementOptions, b as ArrangementSession, c as ArrangementTrack, C as ChordMatch, d as Conflict, e as ContourDirection, D as DetectChordOptions, f as DetectKeyOptions, E as ExtractMotifsOptions, F as FormSection, g as FormSectionOptions, H as Hypermeter, h as HypermeterOptions, K as KeyMatch, i as KeyVariant, M as MODAL_SCALE_NAMES, j as MelodicComparison, k as MelodicContour, l as MelodicContourShape, m as MelodicPhrase, n as ModalCandidate, o as ModalScaleName, p as MotifData, q as MotifOccurrence, r as MotifRelation, s as MotifRelationKind, P as Phrase, t as PhraseOptions, u as PhraseSignal, R as ReduceProgressionOptions, v as ReducedChord, w as ReductionBasis, x as ReductionLevel, S as StructuralCadence, T as TensionPoint, y as TrackAnalysis, z as TrackEdit, B as TrackRole, G as analyzeArrangement, I as compareMelodies, J as createArrangementSession, L as detectChord, N as detectChordBest, O as detectKey, Q as detectKeyBest, U as detectKeyFromNotes, V as extractMotifs, W as hypermeter, X as melodicContour, Y as melodicSimilarity, Z as motifFromNotes, _ as phrasesFromTimeline, $ as reduceProgression, a0 as relateMotifs, a1 as sectionsFromNotes, a2 as structuralCadences, a3 as tensionCurve, a4 as tensionCurveFrom } from '../index-BO6xE9YU.cjs';
+import { e as ChordTimeline } from '../index-Dzr13q3d.cjs';
+export { A as AnalyzeChordOptions, a as AnalyzedNote, B as BorrowedSource, C as CadenceHit, b as CadenceResult, c as ChordAnalysis, d as ChordSegmentation, f as ChordTimelineOptions, g as ChordTimelineResult, h as ChordToRomanOptions, D as DetectCadenceOptions, E as ExplainRomanOptions, H as HarmonicFunction, I as IdentifiedVoiceNote, K as KeyContext, i as KeyProfileName, j as KeyProfilePair, k as KeyRegion, l as KeyTimelineOptions, P as PivotChord, R as RejectedCandidate, m as RomanExplanation, S as SuspensionFigure, T as TheoryLabel, V as VoiceNote, n as analyzeChord, o as analyzeVoice, p as borrowedSource, q as chordTimelineFromChords, r as chordTimelineFromNotes, s as chordToRoman, t as detectCadence, u as detectCadences, v as detectModulations, w as explainRoman, x as functionOf, y as isBorrowedChord, z as isDiatonic, F as isMinorKey, G as keyTimelineFromNotes, J as pivotChords, L as prevailingKeyOf, M as romanToChord, N as secondaryDominant, O as secondaryDominantOf, Q as toVoiceNotes } from '../index-Dzr13q3d.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.
+ * Augmented-sixth chords: the Italian, French, and German sixths.
+ *
+ * All three stand on the lowered submediant (b6) in the bass and carry an
+ * augmented sixth above it, and all three are predominants whose two outer
+ * voices resolve outward onto the dominant. The family is defined by that bass
+ * and that interval rather than by a stack of thirds, so a chord is recognized
+ * here from the tones sounding over that bass rather than through the
+ * Roman-numeral degree tables.
+ *
+ * The interval is spelled, so recognition reads letters and not only pitch
+ * classes: over an Ab bass the augmented sixth is F# and the minor seventh of
+ * the bVI7 it otherwise sounds exactly like is Gb. A caller holding pitch
+ * classes alone — an analysis of a MIDI track, which names no accidentals —
+ * makes that reading with {@link augmentedSixthFromPitchClasses}, and the chord
+ * it hands back carries the spelling that decided it.
  */
 
 /**
- * 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 three augmented-sixth chords, under the nationalities convention gives
+ * them.
  *
- * 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.
+ * Over an Ab bass in C: the Italian sixth is Ab C F#, the French sixth adds the
+ * supertonic (Ab C D F#), and the German sixth adds the lowered mediant
+ * (Ab C Eb F#).
  *
- * @param text The Roman numeral.
- * @param key The prevailing key.
- * @returns The chord.
+ * @category Functional Harmony
+ */
+type AugmentedSixthKind = 'italian' | 'french' | 'german';
+/**
+ * Build an augmented-sixth chord in a key.
+ *
+ * The chord always carries an explicit `bassPc` on the lowered submediant,
+ * which is what makes it an augmented sixth rather than the dominant seventh or
+ * the altered supertonic seventh it shares pitch classes with, and an explicit
+ * interval template naming exactly the tones that sound.
+ *
+ * It also carries its spelling: the tones as `toneSpellings`, and the root and
+ * bass as the usual hints. Those are what let the ordinary chord speller and
+ * the symbol formatter name the chord — `Ab C Eb F#` and `Ab7` for the German
+ * sixth of C major — since a stack of thirds over that root would put a Gb
+ * where the augmented sixth belongs. The spelling is the one the key is written
+ * on, so a flat-side key takes the double flats it genuinely needs.
+ *
+ * The lowered submediant is taken as eight semitones above the tonic in every
+ * mode, since the chord is a chromatic alteration rather than a degree of the
+ * prevailing scale.
+ *
+ * @param kind Which of the three augmented sixths to build.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns The chord, with its bass on the lowered submediant.
+ * @throws If `kind` is not one of the three, or the key's root is not finite.
+ * @see {@link spellAugmentedSixth} to spell the family from a tonic without
+ *   building a chord at all.
  * @example
  * ```ts
- * import { romanToChord, majorKey } from '@libraz/libcantus';
- * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
+ * import { augmentedSixthChord, majorKey } from '@libraz/libcantus';
+ * augmentedSixthChord('german', majorKey(0));
+ * // Ab C Eb F# in C: { rootPc: 8, quality: 'dom7', intervals: [0, 4, 7, 10], bassPc: 8, ... }
  * ```
  * @category Functional Harmony
  */
-declare function romanToChord(text: string, key: KeyScale): Chord;
+declare function augmentedSixthChord(kind: AugmentedSixthKind, key: KeyLike): Chord;
 /**
- * Options for {@link chordToRoman}.
- *
+ * Identify a chord as one of the augmented sixths, or null when it is none.
+ *
+ * A chord qualifies when it sounds the lowered submediant of `key` in the bass,
+ * its pitch classes are exactly one of the three sets built over that bass, and
+ * its own letters spell the augmented sixth above it. All three are needed: the
+ * same pitch classes over the same bass are an ordinary bVI7 when the tone ten
+ * semitones above the bass is written as a minor seventh, and the letters are
+ * the only place that distinction lives.
+ *
+ * A chord naming no `bassPc` sounds its root lowest, which is how the two
+ * conventions for that field — the sounding bass always, or only a bass that
+ * differs from the root — are read alike here.
+ *
+ * The root the chord is measured from is not consulted, so a chord voiced or
+ * rebuilt around any of its own tones still identifies as long as it keeps its
+ * spelling.
+ *
+ * @param chord The chord to test, as a chord symbol, chord data, or a `Chord`.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns The kind of augmented sixth, or null.
+ * @see {@link augmentedSixthFromPitchClasses} to make the reading from pitch
+ *   classes that carry no spelling at all.
+ * @example
+ * ```ts
+ * import { augmentedSixthKind, majorKey, romanToChord } from '@libraz/libcantus';
+ * augmentedSixthKind(romanToChord('Fr6', majorKey(0)), majorKey(0)); // 'french'
+ * ```
  * @category Functional Harmony
  */
-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;
-};
+declare function augmentedSixthKind(chord: ChordLike, key: KeyLike): AugmentedSixthKind | null;
 /**
- * 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. 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.
+ * Read a set of sounding pitch classes over a sounding bass as an augmented
+ * sixth, or null when they are none.
+ *
+ * The reading a caller holding no spelling has to make for itself: pitch
+ * classes name no accidentals, so nothing downstream can tell the German sixth
+ * from the bVI7 it sounds like once the letters are gone. The chord returned is
+ * the one {@link augmentedSixthChord} builds, spelling and all, so it keeps
+ * identifying as an augmented sixth everywhere it travels.
+ *
+ * Not every b6-1-b3-#4 over a b6 bass is an augmented sixth, and this cannot
+ * know which one is: it answers what the tones would spell, and the caller
+ * decides whether that reading is the one the music supports.
+ *
+ * @param pcs The sounding pitch classes; duplicates and unreduced values are
+ *   fine.
+ * @param bassPc The pitch class sounding in the bass.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns The augmented-sixth chord, or null.
+ * @see {@link augmentedSixthKind} to read a chord that already carries its
+ *   spelling.
  * @example
  * ```ts
- * import { 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'
+ * import { augmentedSixthFromPitchClasses, majorKey } from '@libraz/libcantus';
+ * // Ab C Eb Gb sounding over Ab in C: the German sixth, spelled with its F#.
+ * augmentedSixthFromPitchClasses([8, 0, 3, 6], 8, majorKey(0))?.quality; // 'dom7'
  * ```
  * @category Functional Harmony
  */
-declare function 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';
+declare function augmentedSixthFromPitchClasses(pcs: readonly number[], bassPc: number, key: KeyLike): Chord | null;
 /**
- * A theory annotation attached to a note.
- *
- * @category Arrangement & Analysis
- */
-type TheoryLabel = {
-    kind: 'chordTone';
-    role: ChordToneRole;
-} | {
-    kind: 'tension';
-    degree: 9 | 11 | 13;
-} | {
-    kind: 'avoid';
-} | {
-    kind: 'passing';
-} | {
-    kind: 'neighbor';
-} | {
-    kind: 'suspension';
-    type: SuspensionFigure;
-    resolveTo: number;
-} | {
-    kind: 'anticipation';
-} | {
-    kind: 'escape';
-} | {
-    kind: 'needsResolution';
-    resolveTo: number;
-} | {
-    kind: 'leadingTone';
-    resolveTo: number;
-};
-/**
- * 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 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.
- *
- * 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. 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; defaults to
- *   none, which is the whole story for a solo line.
- * @returns One annotation per input note.
+ * Spell an augmented-sixth chord from a spelled tonic, lowest note first.
+ *
+ * This is the spelled counterpart of {@link augmentedSixthChord}, and the table
+ * the chord's own spelling is built from: every tone is placed by a named
+ * interval above the bass, so the outer interval is an augmented sixth in every
+ * key rather than the minor seventh its ten semitones would otherwise imply.
+ * Reach for it when a spelled tonic is all there is; spelling the chord itself
+ * with {@link spellChord} names the same notes, in the chord's own order.
+ *
+ * A tonic carrying an octave yields notes carrying octaves, ascending from the
+ * bass; an octave-less tonic yields octave-less notes.
+ *
+ * @param kind Which of the three augmented sixths to spell.
+ * @param tonic The spelled tonic of the key, as a note name, a MIDI number,
+ *   note data, or a `Note`.
+ * @returns The spelled tones, bass first and ascending.
+ * @throws If `kind` is not one of the three, or `tonic` is not a note.
  * @example
  * ```ts
- * import { analyzeVoice, makeChord, majorKey } from '@libraz/libcantus';
- * const voice = [
- *   { 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));
- * labels; // one AnalyzedNote per input note, in the same order
+ * import { noteNames, parseNote, spellAugmentedSixth } from '@libraz/libcantus';
+ * noteNames(spellAugmentedSixth('german', parseNote('C'))); // ['Ab', 'C', 'Eb', 'F#']
+ * noteNames(spellAugmentedSixth('italian', 'E')); // ['C', 'E', 'A#']
  * ```
- * @category Arrangement & Analysis
+ * @category Functional Harmony
  */
-declare function analyzeVoice(voice: readonly VoiceNote[], chordAtBeat: (beat: number) => Chord | null, key: KeyScale, otherVoicesAtBeat?: (beat: number) => VoiceSnapshot[]): AnalyzedNote[];
+declare function spellAugmentedSixth(kind: AugmentedSixthKind, tonic: NoteLike): Note[];
 
 /**
- * Arrangement track-role analysis: a single harmony is inferred from every
- * track's notes pooled together, each track is then analysed against that shared
- * harmony, and notes that clash with the sounding chord are collected as
- * conflicts.
+ * Line spelling: name every note of a melodic line in one pass.
+ *
+ * {@link spellPitch} decides one note from the key, the root of the chord under
+ * it and its two immediate neighbours. That is enough for a single note, but a
+ * line spelled note by note can zig-zag between the two readings of one idea —
+ * a rising whole-tone figure comes out F# Ab Bb, with a diminished third in the
+ * middle of it.
+ *
+ * This module solves the whole line at once. The theory layer's own judgment
+ * becomes the cost of emitting a spelling, the melodic rules become the cost of
+ * moving from one spelling to the next, and a dynamic program takes the
+ * cheapest path across the line. Nothing here re-decides what
+ * {@link spellPitchClass} and {@link spellChord} already decide: it only weighs
+ * their answers against the shape of the line they sit in.
  */
 
 /**
- * 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' | 'drums' | 'other';
-/**
- * One input track: its notes plus optional name and role.
- *
- * @category Arrangement & Analysis
- */
-type ArrangementTrack = {
-    name?: string;
-    role?: TrackRole;
-    notes: readonly 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;
-    /** 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 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}.
+ * Options for {@link spellLine}.
  *
  * @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;
-    /**
-     * 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.
-     *
-     * @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;
+type SpellLineOptions = {
     /**
-     * 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}
+     * Tonic spelling to anchor the key, for a caller that already knows how the
+     * piece is written. It must sound the key's own root pitch class; anything
+     * else is rejected rather than spelled. Defaults to the conventional
+     * spelling `spelledKeyOf` gives the key. Accepted as a note name, a MIDI
+     * number, note data, or a `Note`.
      */
+    tonic?: NoteLike;
+    /** Upper bound on the work the line may cost; defaults to the 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
- * 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
- * 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.
- *
- * 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.
- * @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 `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 `DISSONANCE_WEIGHT`;
- *  - the registral span of the sounding notes, saturating at
- *    `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.
- *
- * @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[];
-/**
- * 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.
+ * Spell a whole melodic line at once, so its notes agree with each other.
+ *
+ * Every note is spelled together with the rest of the line rather than one at a
+ * time: each pitch offers the three spellings a double accidental allows, the
+ * chord and the key price them, the intervals between neighbours price the
+ * pairs, and the cheapest reading of the whole line wins. Ties fall to the
+ * spelling {@link spellPitchClass} would have chosen alone, so the answer never
+ * drifts from the theory layer without a reason.
+ *
+ * Four rules decide, in this order:
+ *
+ * 1. A note the sounding chord names takes that chord's spelling of it, even
+ *    when the key spells the pitch otherwise — the seventh of a Db7 reads Cb in
+ *    C major, not B.
+ * 2. Anything else the key's scale spells keeps its key spelling, exactly as
+ *    the note-by-note path keeps it.
+ * 3. A chromatic note is spelled so the written intervals around it match the
+ *    sounding ones, and then so a rising step carries a sharp and a falling
+ *    step a flat.
+ * 4. Failing all of that, the key's own chromatic spelling stands, and the
+ *    fewest accidentals win.
+ *
+ * Without a timeline — pass `null` — rules 2 to 4 still apply in full, so a
+ * diatonic line and a chromatic run come out the same. What is lost is rule 1:
+ * a chromatic chord can no longer name its own tones, so the tones of a
+ * borrowed or altered chord fall back to the key's convention (that Cb becomes
+ * B), and an enharmonically ambiguous tone under a chord that would have fixed
+ * it is decided by the line's direction instead.
+ *
+ * @param notes The line, monophonic and in time order. Notes sharing an onset
+ *   are read as consecutive, so split polyphonic material into voices first.
+ * @param timeline The chords sounding under the line, or null when only the key
+ *   is known. Each note is judged against the chord at its own onset.
+ * @param key The key the line is written in, as a key name, a key/scale, or a
+ *   `Key`.
+ * @param opts Optional tonic spelling and work budget.
+ * @returns One spelled note per input note, in input order, each carrying the
+ *   octave that reproduces its pitch.
+ * @throws If `opts.tonic` does not sound the key's root pitch class, if a note
+ *   event is malformed, or if the line is longer than the budget allows.
  * @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 });
+ * import { chordTimelineFromChords, majorKey, noteNames, spellLine } from '@libraz/libcantus';
+ * // A chromatic ascent spells with sharps, whatever the key would say alone.
+ * const rising = [60, 61, 62, 63, 64].map((pitch, index) => ({
+ *   pitch,
+ *   startBeat: index,
+ *   durationBeat: 1,
+ * }));
+ * noteNames(spellLine(rising, null, majorKey(0)));
+ * // ['C4', 'C#4', 'D4', 'D#4', 'E4']
+ * // Under a Db7 the same B sounds as the chord's seventh.
+ * const timeline = chordTimelineFromChords([{ rootPc: 1, quality: 'dom7', startBeat: 0 }], 4);
+ * noteNames(spellLine([{ pitch: 71, startBeat: 0, durationBeat: 1 }], timeline, majorKey(0)));
+ * // ['Cb5']
  * ```
  * @category Arrangement & Analysis
  */
-declare function tensionCurveFrom(tracks: ArrangementTrack[], analysis: ArrangementAnalysis, opts?: ArrangementOptions & {
-    step?: number;
-}): TensionPoint[];
+declare function spellLine(notes: readonly NoteEvent[], timeline: ChordTimeline | null, key: KeyLike, opts?: SpellLineOptions): Note[];
 
-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 };
+export { type AugmentedSixthKind, Chord as ChordData, ChordLike, ChordTimeline, KeyLike, Note as NoteData, NoteEvent, NoteLike, type SpellLineOptions, augmentedSixthChord, augmentedSixthFromPitchClasses, augmentedSixthKind, spellAugmentedSixth, spellLine };