@libraz/libcantus 0.9.5 → 1.0.0

package/dist/analyze/index.d.ts

@@ -1,411 +1,258 @@
-import { T as TimeSignature } from '../index-DXd9JikN.js';
-import { N as NoteEvent, K as KeyScale } from '../types-BN6_Q9Kl.js';
-import { d as ChordToneRole, C as Chord } from '../index-COw1Ky9g.js';
-export { a as ChordQuality, b as ChordSegment, c as ChordSpan, P as PitchSpelling } from '../index-COw1Ky9g.js';
-import { V as VoiceSnapshot, N as NoteSafety, S as SafetyProfile } from '../index-BuaB-ypt.js';
-import { a as ChordTimeline, C as CadenceHit } from '../index-DRtIhlJj.js';
-export { b as ChordTimelineOptions, c as ChordTimelineResult, d as chordTimelineFromChords, e as chordTimelineFromNotes, f as detectCadences } from '../index-DRtIhlJj.js';
-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-CAN7v-kw.js';
-export { B as BorrowedSource, C as Cadence, a as ChordAnalysis, b as ChordToRomanOptions, H as HarmonicFunction, c as analyzeChord, d as borrowedSource, e as chordToRoman, f as detectCadence, g as functionOf, i as isBorrowedChord, h as isDiatonic, j as isMinorKey, p as parallelKey, r as romanToChord, s as secondaryDominant } from '../function-DTCt675z.js';
+import { h as NoteLike, f as Note, g as NoteEvent } from '../index-B9MNZboQ.js';
+export { a as Articulation, b as IntervalQualityLabel, d as KeyScale, S as SpelledInterval } from '../index-B9MNZboQ.js';
+export { M as MeterChange, b as MeterLike, c as MeterMap, T as TimeSignature } from '../index-Cj49F892.js';
+import { K as KeyLike, b as Chord, c as ChordLike } from '../index-szBv3496.js';
+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-szBv3496.js';
+export { r as ScaleName } from '../masks-DYbE485J.js';
+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-D57QRbVn.js';
+import { e as ChordTimeline } from '../index-Chbst3Jx.js';
+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-Chbst3Jx.js';
 
 /**
- * A suspension figure, named by the interval above the bass and the interval it
- * resolves to.
+ * Augmented-sixth chords: the Italian, French, and German sixths.
  *
- * @category Arrangement & Analysis
- */
-type SuspensionFigure = 'sus4-3' | 'sus6-5' | 'sus7-6' | 'sus9-8' | 'sus2-3';
-/**
- * A theory annotation attached to a note.
+ * 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.
  *
- * @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
+ * 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.
  */
-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.
+ * The three augmented-sixth chords, under the nationalities convention gives
+ * them.
  *
- * @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.
+ * 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#).
  *
- * @category Arrangement & Analysis
+ * @category Functional Harmony
  */
-type IdentifiedVoiceNote = VoiceNote & {
-    id: number;
-};
+type AugmentedSixthKind = 'italian' | 'french' | 'german';
 /**
- * Give plain note events the ids {@link analyzeVoice} reports back.
+ * Build an augmented-sixth chord in a key.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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 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.
+ * 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 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.
+ * @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 { 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 { 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 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 augmentedSixthChord(kind: AugmentedSixthKind, key: KeyLike): Chord;
 /**
- * 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.
+ * Identify a chord as one of the augmented sixths, or null when it is none.
  *
- * 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.
+ * 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.
  *
- * @category Arrangement & Analysis
- */
-type TrackRole = 'melody' | 'harmony' | 'bass' | 'drums' | 'other';
-/**
- * One input track: its notes plus optional name and role.
+ * 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.
  *
- * @category Arrangement & Analysis
- */
-type ArrangementTrack = {
-    name?: string;
-    role?: TrackRole;
-    notes: readonly NoteEvent[];
-};
-/**
- * A track after analysis: its resolved name, role, and per-note annotations.
+ * 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.
  *
- * @category Arrangement & Analysis
+ * @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 TrackAnalysis = {
-    name: string;
-    role: TrackRole;
-    /** One {@link AnalyzedNote} per note, labelled against the inferred chords. */
-    notes: AnalyzedNote[];
-};
+declare function augmentedSixthKind(chord: ChordLike, key: KeyLike): AugmentedSixthKind | null;
 /**
- * A note that clashes with the harmony sounding beneath it.
+ * Read a set of sounding pitch classes over a sounding bass as an augmented
+ * sixth, or null when they are none.
  *
- * @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}.
+ * 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.
  *
- * @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}.
+ * 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.
  *
- * @category Arrangement & Analysis
+ * @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 { 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
  */
-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;
-    /**
-     * 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;
-};
+declare function augmentedSixthFromPitchClasses(pcs: readonly number[], bassPc: number, key: KeyLike): Chord | null;
 /**
- * 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.
+ * Spell an augmented-sixth chord from a spelled tonic, lowest note first.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * A tonic carrying an octave yields notes carrying octaves, ascending from the
+ * bass; an octave-less tonic yields octave-less notes.
  *
- * @param tracks The tracks to analyse.
- * @param opts Analysis options; see {@link ArrangementOptions}.
- * @returns The inferred harmony, per-track annotations, cadences, and conflicts.
+ * @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 { 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
+ * 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 analyzeArrangement(tracks: ArrangementTrack[], opts?: ArrangementOptions): ArrangementAnalysis;
+declare function spellAugmentedSixth(kind: AugmentedSixthKind, tonic: NoteLike): Note[];
 
 /**
- * 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.
+ * 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.
  */
 
 /**
- * A tension reading sampled at a beat.
+ * Options for {@link spellLine}.
  *
  * @category Arrangement & Analysis
  */
-type TensionPoint = {
-    beat: number;
-    /** Combined tension in [0, 1]. */
-    tension: number;
+type SpellLineOptions = {
+    /**
+     * 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;
 };
 /**
- * Sample the harmonic tension of an arrangement at regular beats.
+ * Spell a whole melodic line at once, so its notes agree with each other.
  *
- * 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`.
+ * 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.
  *
- * 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.
+ * Four rules decide, in this order:
  *
- * @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.
+ * 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.
  *
- * `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.
+ * 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 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.
+ * @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, 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, tensionCurve, tensionCurveFrom, toVoiceNotes };
+export { type AugmentedSixthKind, Chord as ChordData, ChordLike, ChordTimeline, KeyLike, Note as NoteData, NoteEvent, NoteLike, type SpellLineOptions, augmentedSixthChord, augmentedSixthFromPitchClasses, augmentedSixthKind, spellAugmentedSixth, spellLine };