@libraz/libcantus 0.9.4 → 1.0.0

package/dist/theory/index.d.ts

@@ -1,17 +1,21 @@
-import { N as Note } from '../index-OG65ocOr.js';
-import { K as KeyScale } from '../types-BN6_Q9Kl.js';
-import { C as Chord } from '../index-C83mZI1P.js';
-export { a as ChordQuality, b as ChordSegment, c as ChordSpan, d as ChordToneRole, P as PitchSpelling, e as chordFromDegree, f as chordPitchClasses, g as chordQualities, h as chordToneRole, i as diatonicSeventh, j as diatonicTriad, k as intervalAboveRoot, l as isChordMember, m as makeChord, t as transposeChord } from '../index-C83mZI1P.js';
-import { p as ScaleNameInput, r as VoicingOptions } from '../styled-DIRkk9Uz.js';
-export { A as ALTERED_MASK, B as BLUES_MASK, C as CHROMATIC_MASK, a as ChordScaleMatch, b as ChordScaleReportEntry, D as DORIAN_MASK, H as HARMONIC_MINOR_MASK, L as LOCRIAN_MASK, c as LOCRIAN_NATURAL2_MASK, d as LYDIAN_DOMINANT_MASK, e as LYDIAN_MASK, M as MAJOR_MASK, f as MAJOR_PENTATONIC_MASK, g as MELODIC_MINOR_MASK, h as MINOR_PENTATONIC_MASK, i as MIXOLYDIAN_B13_MASK, j as MIXOLYDIAN_MASK, N as NAMED_SCALES, k as NATURAL_MINOR_MASK, O as OCTATONIC_HALF_WHOLE_MASK, l as OCTATONIC_WHOLE_HALF_MASK, P as PHRYGIAN_DOMINANT_MASK, m as PHRYGIAN_MASK, S as SATB_RANGES, n as ScaleChoice, o as ScaleName, q as StyledVoicingOptions, V as VoiceRange, s as VoicingStyle, W as WHOLE_TONE_MASK, t as availableTensions, u as avoidNotes, v as chordScaleReport, w as chordScales, x as maskFromOffsets, y as namedScaleMask, z as requireScaleMask, E as scaleMatchesChord, F as scalesForChanges, G as voiceChord, I as voiceChordStyled, J as voiceProgression } from '../styled-DIRkk9Uz.js';
-export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from '../index-tSQh-xwY.js';
-export { E as EvaluateSafetyOptions, N as NoteSafety, R as ReasonFlag, S as SafetyProfile, a as SafetyQuery, b as SafetyResult, V as VoiceSnapshot, e as enumerateSafePitches, c as evaluateSafety } from '../index-6VR8-kit.js';
+import { d as KeyScale, S as SpelledInterval, f as Note, h as NoteLike } from '../index-B9MNZboQ.js';
+export { B as BudgetExceededError, I as IntervalLike, b as IntervalQualityLabel, c as InvalidInputError, L as LibcantusError, N as NoSolutionError, i as NoteNameOptions, j as NoteNameSystem, P as ParseResult } from '../index-B9MNZboQ.js';
+import { C as ConsonanceClass } from '../index-DInQqT8Q.js';
+import { K as KeyLike, c as ChordLike, b as Chord } from '../index-szBv3496.js';
+export { A as Alteration, a as AlteredDegree, C as ChordBase, d as ChordQuality, e as ChordSegment, f as ChordSeventh, g as ChordSpan, h as ChordSpec, i as ChordSymbolOptions, j as ChordToneRole, E as EvaluateSafetyOptions, k as KeyRelation, N as NoteSafety, P as PROFILE_WEIGHTS, l as PitchSpelling, m as ProfileWeights, R as ReasonFlag, S as SafetyProfile, n as SafetyQuery, o as SafetyResult, p as SpelledKey, V as VoiceSnapshot, q as chordFromDegree, r as chordFromSpan, s as chordFromSpec, t as chordPitchClasses, u as chordQualities, v as chordSpecIntervals, w as chordSpecOf, x as chordSpecQuality, y as chordToneRole, z as diatonicSeventh, B as diatonicTriad, D as dominantKeyOf, F as enharmonicKeyOf, G as enumerateSafePitches, H as evaluateSafety, I as formatChordSymbol, J as intervalAboveRoot, L as isChordMember, M as keyRelationBetween, O as makeChord, Q as parallelKeyOf, T as parseChordSymbol, U as profileWeights, W as relatedKeysOf, X as relativeKeyOf, Y as spanFromChord, Z as spelledKeyOf, _ as subdominantKeyOf, $ as toChordData, a0 as toKeyScale, a1 as transposeChord, a2 as transposeChordSymbol, a3 as tryParseChordSymbol } from '../index-szBv3496.js';
+import { q as VoicingOptions } from '../index-9wcMhG73.js';
+export { A as AvailableTensionsOptions, a as AvoidNoteUse, b as AvoidNotesOptions, C as ChordScaleMatch, c as ChordScaleReportEntry, K as KeyMode, P as PartWritingOptions, d as PartWritingViolation, e as PartWritingViolationKind, S as SATB_RANGES, f as SCALE_SYSTEMS, g as ScaleChoice, h as ScaleSystem, i as Species, j as SpeciesOptions, k as SpelledVoicing, l as StyledVoicingOptions, T as TRANSPOSING_INSTRUMENTS, m as TransposingInstrument, n as TransposingInstrumentName, V as VoiceIndependenceOptions, o as VoiceIndependenceReport, p as VoiceRange, r as VoicingStyle, s as availableTensions, t as avoidNotes, u as checkPartWriting, v as checkSpecies, w as chordScaleReport, x as chordScales, y as instrumentTransposition, z as keyFromFifths, B as keySignatureFifths, D as scaleMatchesChord, E as scaleSystemOf, F as scalesForChanges, G as spellVoicing, H as supportsFunctionalHarmony, I as toSoundingPitch, J as toWrittenPitch, L as voiceChord, M as voiceChordStyled, N as voiceIndependence, O as voiceProgression } from '../index-9wcMhG73.js';
+export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from '../index-CunYKLiu.js';
+import { s as ScaleNameInput } from '../masks-DYbE485J.js';
+export { A as ALTERED_MASK, B as BLUES_MASK, C as CHROMATIC_MASK, D as DORIAN_MASK, a as DOUBLE_HARMONIC_MASK, H as HARMONIC_MINOR_MASK, L as LOCRIAN_MASK, b as LOCRIAN_NATURAL2_MASK, c as LYDIAN_DOMINANT_MASK, d as LYDIAN_MASK, M as MAJOR_MASK, e as MAJOR_PENTATONIC_MASK, f as MARWA_MASK, g as MELODIC_MINOR_MASK, h as MINOR_PENTATONIC_MASK, i as MIXOLYDIAN_B13_MASK, j as MIXOLYDIAN_MASK, k as MIYAKO_BUSHI_MASK, N as NAMED_SCALES, l as NATURAL_MINOR_MASK, O as OCTATONIC_HALF_WHOLE_MASK, m as OCTATONIC_WHOLE_HALF_MASK, P as PHRYGIAN_DOMINANT_MASK, n as PHRYGIAN_MASK, o as PURVI_MASK, R as RITSU_MASK, p as RYUKYU_MASK, S as SCALE_ALIASES, q as ScaleAliasName, r as ScaleName, T as TODI_MASK, W as WHOLE_TONE_MASK, t as WORLD_SCALES, u as WorldScaleName, v as maskFromOffsets, w as namedScaleMask, x as requireScaleMask, y as resolveScaleName } from '../masks-DYbE485J.js';
 
 /**
  * Test whether a pitch belongs to the scale.
  *
  * @param pitch MIDI pitch or bare pitch class.
- * @param key The key/scale to test against.
+ * @param key The key/scale to test against. This predicate reads the mask as
+ *   given rather than taking a key name: the spelling search runs it over
+ *   masks that name no key, which resolving a name would refuse.
  * @returns True if the pitch class is a member of the scale.
  *
  * @example
@@ -32,26 +36,34 @@ declare function isScaleTone(pitch: number, key: KeyScale): boolean;
  * distance above and below) the lower pitch is returned.
  *
  * @param pitch MIDI pitch to snap.
- * @param key The key/scale to snap to.
+ * @param key The key/scale to snap to, as a key name, a key/scale, or a `Key`.
  * @returns The nearest in-scale MIDI pitch.
  *
  * @category Scales
  */
-declare function nearestScaleTone(pitch: number, key: KeyScale): number;
+declare function nearestScaleTone(pitch: number, key: KeyLike): number;
 /**
- * Get the 0-based scale degree of a pitch.
+ * Get the scale degree of a pitch, counted from 1: the tonic is degree 1.
+ *
+ * A pitch outside the scale answers -1 rather than 0, so a caller testing the
+ * result for a degree cannot mistake the "not in the scale" answer for the
+ * tonic.
  *
  * @param pitch MIDI pitch or bare pitch class.
- * @param key The key/scale to measure against.
- * @returns The 0-based degree, or -1 if the pitch is not in the scale.
+ * @param key The key/scale to measure against, as a key name, a key/scale, or a
+ *   `Key`.
+ * @returns The 1-based degree, or -1 if the pitch is not in the scale.
  *
  * @category Scales
  */
-declare function pitchToScaleDegree(pitch: number, key: KeyScale): number;
+declare function pitchToScaleDegree(pitch: number, key: KeyLike): number;
 /**
  * List the pitch classes of a key's scale.
  *
- * @param key The key/scale to enumerate.
+ * @param key The key/scale to enumerate. The two enumerators here take a plain
+ *   key/scale rather than a key name: they read the mask as given, including
+ *   the tonic-less masks the spelling search works through, which no key name
+ *   describes.
  * @returns The member pitch classes, sorted ascending in [0, 11].
  *
  * @category Scales
@@ -60,10 +72,11 @@ declare function diatonicPitchClasses(key: KeyScale): number[];
 /**
  * List the pitch classes of a key's scale in ascending scale-degree order.
  *
- * Degree 0 is the root; degrees follow the mask bits in offset order rather
- * than sorted pitch-class order.
+ * The first entry is the root (degree 1); degrees follow the mask bits in
+ * offset order rather than sorted pitch-class order.
  *
- * @param key The key/scale to enumerate.
+ * @param key The key/scale to enumerate, read as given for the reason
+ *   {@link diatonicPitchClasses} gives.
  * @returns The member pitch classes ordered by scale degree.
  *
  * @category Scales
@@ -113,71 +126,141 @@ declare function minorKey(rootPc: number): KeyScale;
 declare function scaleByName(name: ScaleNameInput, rootPc: number): KeyScale;
 
 /**
- * Total voice-leading cost between two voicings: the sum of absolute semitone
- * motion across voices, plus a moderate `HIDDEN_PERFECT_PENALTY` when the
- * outer-voice (bass–soprano) pair reaches a hidden/direct perfect fifth or
- * octave by similar motion. The arrays must be the same length; when they
- * differ the voicings are not comparable and the cost is `Infinity`.
+ * Shared interval reading for the counterpoint rules.
  *
- * @param from The previous voicing, one MIDI pitch per voice.
- * @param to The next voicing, one MIDI pitch per voice.
- * @returns The summed absolute motion (plus any hidden-perfect penalty), or
- *   `Infinity` when lengths differ.
- * @category Voicing & Counterpoint
+ * The predicates, the species checker and the independence metric all need the
+ * same two conversions — a pitch argument to a sounding pitch, and a spelled
+ * interval to its consonance class — and importing them from one another would
+ * make the module graph circular.
  */
-declare function voiceLeadingCost(from: number[], to: number[]): number;
+
 /**
- * Voice a single chord to follow smoothly from an arbitrary current voicing.
+ * Classify a spelled interval by consonance, the way a counterpoint exercise
+ * reads it.
  *
- * Candidate voicings of `chord` are enumerated within ranges taken from `opts`,
- * or — when neither `voices` nor `ranges` is given — from a one-octave window
- * around each pitch of `current` (so the result matches `current`'s voice
- * count). Each candidate is scored by structural quality, voice-leading motion
- * from `current`, and a large penalty per counterpoint violation; the lowest
- * scoring candidate is returned, ascending.
+ * The spelling decides, not the semitone count: a diminished fourth is a
+ * dissonance though it sounds like a major third, and an augmented fifth is a
+ * dissonance though it sounds like a minor sixth. Only the perfect unison, fifth
+ * and octave and the major and minor thirds and sixths are consonant. The
+ * perfect fourth is context-dependent exactly as in {@link classifyInterval}.
  *
- * @param current The current voicing to lead from, ascending (index 0 = lowest).
- * @param chord The next chord to voice.
- * @param opts Voicing options; when omitted, ranges follow `current`'s span.
- * @returns The chosen voicing, ascending with one MIDI pitch per voice.
- * @throws If `current` is empty or holds a non-finite pitch while the ranges
- *   are derived from it, or if no voicing fits the ranges.
+ * @param interval The spelled interval between the two voices.
+ * @param twoVoice When true, the perfect fourth counts as a dissonance.
+ * @returns The counterpoint quality of the interval.
+ * @example
+ * ```ts
+ * import { classifySpelledInterval, ConsonanceClass, parseInterval } from '@libraz/libcantus';
+ * classifySpelledInterval(parseInterval('d4')); // ConsonanceClass.Dissonance
+ * classifySpelledInterval(parseInterval('M3')); // ConsonanceClass.ImperfectConsonance
+ * ```
  * @category Voicing & Counterpoint
  */
-declare function nextVoicing(current: number[], chord: Chord, opts?: VoicingOptions): number[];
+declare function classifySpelledInterval(interval: SpelledInterval, twoVoice?: boolean): ConsonanceClass;
+
+/**
+ * Counterpoint predicates: each judges one pair of voices at one moment.
+ *
+ * Every predicate reads spelled notes, because spelling is what decides two of
+ * these rules. An augmented second and a minor third span the same three
+ * semitones, and a diminished fourth sounds like a major third; the first is a
+ * forbidden melodic leap and the second a vertical dissonance, and neither can
+ * be seen in a MIDI integer. {@link createsVerticalDissonance} and
+ * {@link isForbiddenMelodicLeap} therefore answer the spelled question when
+ * given spelled notes, and the sounding question — all a bare pitch can support
+ * — when given integers. {@link isAugmentedMelodicInterval} asks a question that
+ * has no sounding half at all, so its integer form answers false rather than
+ * refusing the call: every predicate here takes either form, and the ones that
+ * need spelling say so by degrading.
+ *
+ * The remaining rules compare registers or perfect classes, which spelling
+ * cannot change: a parallel fifth is a parallel fifth however the two voices are
+ * written. Those keep their integer form as an equal partner.
+ */
 
 /**
  * Whether an upper voice has crossed below a lower voice.
  *
- * @param upperPitch Pitch of the nominally higher voice.
- * @param lowerPitch Pitch of the nominally lower voice.
+ * @param upper The nominally higher voice.
+ * @param lower The nominally lower voice.
  * @returns True when the upper voice sits below the lower voice.
  * @category Voicing & Counterpoint
  */
-declare function createsVoiceCrossing(upperPitch: number, lowerPitch: number): boolean;
+declare function createsVoiceCrossing(upper: Note, lower: Note): boolean;
+declare function createsVoiceCrossing(upper: number, lower: number): boolean;
 /**
- * Whether two simultaneous pitches form a dissonance.
+ * Whether two simultaneous voices form a dissonance.
  *
- * @param a First pitch.
- * @param b Second pitch.
+ * Given spelled notes the spelling decides, so a diminished fourth reads as the
+ * dissonance it is. Given MIDI integers only the sounding interval is available,
+ * which cannot tell that fourth from a major third; use the spelled form
+ * wherever the exercise is written in notes.
+ *
+ * @param a First voice.
+ * @param b Second voice.
  * @param twoVoice When true, the perfect fourth counts as dissonant.
  * @returns True when the vertical interval is dissonant.
+ * @example
+ * ```ts
+ * import { createsVerticalDissonance, parseNote } from '@libraz/libcantus';
+ * createsVerticalDissonance(parseNote('Fb4'), parseNote('C4'), true); // true — d4
+ * createsVerticalDissonance(64, 60, true); // false — the same pitches read as a major third
+ * ```
  * @category Voicing & Counterpoint
  */
+declare function createsVerticalDissonance(a: Note, b: Note, twoVoice: boolean): boolean;
 declare function createsVerticalDissonance(a: number, b: number, twoVoice: boolean): boolean;
 /**
- * Whether a melodic move is a forbidden leap: a tritone, either seventh (minor
- * or major), or any leap wider than an octave.
+ * Whether a melodic move is a forbidden leap.
  *
- * Operates on the raw absolute distance, so compound leaps are not reduced to
- * their simple class before the octave check.
+ * Forbidden are the seventh in either quality, any leap wider than an octave,
+ * and — where the spelling is known — every augmented and diminished interval,
+ * the augmented second of the harmonic minor among them. Given MIDI integers the
+ * tritone is still caught, since it is forbidden under either spelling, but an
+ * augmented second is indistinguishable from a minor third and passes.
  *
- * @param prev Starting pitch.
- * @param cur Ending pitch.
+ * The raw distance is used for the octave check, so a compound leap is not
+ * reduced to its simple class first.
+ *
+ * @param prev Starting note.
+ * @param cur Ending note.
  * @returns True when the leap is forbidden in strict counterpoint.
+ * @example
+ * ```ts
+ * import { isForbiddenMelodicLeap, parseNote } from '@libraz/libcantus';
+ * isForbiddenMelodicLeap(parseNote('Ab4'), parseNote('B4')); // true — augmented second
+ * isForbiddenMelodicLeap(68, 71); // false — the same pitches read as a minor third
+ * ```
  * @category Voicing & Counterpoint
  */
+declare function isForbiddenMelodicLeap(prev: Note, cur: Note): boolean;
 declare function isForbiddenMelodicLeap(prev: number, cur: number): boolean;
+/**
+ * Whether a voice moves by an augmented interval — the melodic step no
+ * sixteenth-century line takes, and the one a MIDI integer cannot show.
+ *
+ * The augmented unison is excluded: raising or lowering the note a voice already
+ * holds is a chromatic inflection, not a leap.
+ *
+ * Every augmented interval sounds like a plain one — the augmented second like a
+ * minor third, the augmented fourth like a diminished fifth — so MIDI integers
+ * carry nothing this rule can read, and the numeric form always answers false.
+ * It exists so a host can run the whole predicate set over a bare pitch pair;
+ * take the spelled form wherever the exercise is written in notes.
+ *
+ * @param prev Starting note.
+ * @param cur Ending note.
+ * @returns True when the move spans an augmented second or wider.
+ * @example
+ * ```ts
+ * import { isAugmentedMelodicInterval, parseNote } from '@libraz/libcantus';
+ * isAugmentedMelodicInterval(parseNote('Ab4'), parseNote('B4')); // true — A2 in C minor
+ * isAugmentedMelodicInterval(parseNote('A4'), parseNote('C5')); // false — m3
+ * isAugmentedMelodicInterval(68, 71); // false — the same pitches carry no spelling
+ * ```
+ * @category Voicing & Counterpoint
+ */
+declare function isAugmentedMelodicInterval(prev: Note, cur: Note): boolean;
+declare function isAugmentedMelodicInterval(prev: number, cur: number): boolean;
 /**
  * Whether two voices move into consecutive perfect intervals of the same kind
  * (fifth-to-fifth, octave-to-octave, unison-to-unison).
@@ -192,8 +275,12 @@ declare function isForbiddenMelodicLeap(prev: number, cur: number): boolean;
  * an octave does not (different perfect kinds — the direct/hidden case owned by
  * {@link createsHiddenParallelPerfect}).
  *
+ * The perfect classes are what they sound like under any spelling, so spelled
+ * notes and MIDI integers give the same answer here.
+ *
  * @category Voicing & Counterpoint
  */
+declare function createsParallelPerfect(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note): boolean;
 declare function createsParallelPerfect(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
 /**
  * Whether two voices move in consecutive parallel octaves (or unisons) by
@@ -208,6 +295,7 @@ declare function createsParallelPerfect(aPrev: number, aCur: number, bPrev: numb
  *
  * @category Voicing & Counterpoint
  */
+declare function createsParallelOctave(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note): boolean;
 declare function createsParallelOctave(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
 /**
  * Whether two voices move in consecutive parallel unisons — both landing on the
@@ -215,6 +303,7 @@ declare function createsParallelOctave(aPrev: number, aCur: number, bPrev: numbe
  *
  * @category Voicing & Counterpoint
  */
+declare function createsParallelUnison(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note): boolean;
 declare function createsParallelUnison(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
 /**
  * Whether two voices reach a perfect interval by similar motion from an
@@ -226,41 +315,276 @@ declare function createsParallelUnison(aPrev: number, aCur: number, bPrev: numbe
  *
  * @category Voicing & Counterpoint
  */
+declare function createsHiddenParallelPerfect(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note): boolean;
 declare function createsHiddenParallelPerfect(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
+/**
+ * Whether two voices arrive at a perfect octave or unison by contrary motion
+ * with the upper voice leaping down — the *ottava battuta* the sixteenth-century
+ * theorists forbid.
+ *
+ * The stepwise arrival is allowed, as is the same octave reached with the upper
+ * voice rising, so only the downward leap into the perfect class is flagged.
+ *
+ * @category Voicing & Counterpoint
+ */
+declare function createsBattuta(aPrev: Note, aCur: Note, bPrev: Note, bCur: Note): boolean;
+declare function createsBattuta(aPrev: number, aCur: number, bPrev: number, bCur: number): boolean;
 /**
  * Whether two voices overlap: the upper voice descends below where the lower
  * voice just was, or the lower voice rises above where the upper voice just was.
  * Distinct from a simultaneous voice crossing.
  *
- * @param upperPrev Previous pitch of the upper voice.
- * @param upperCur Current pitch of the upper voice.
- * @param lowerPrev Previous pitch of the lower voice.
- * @param lowerCur Current pitch of the lower voice.
+ * @param upperPrev Previous note of the upper voice.
+ * @param upperCur Current note of the upper voice.
+ * @param lowerPrev Previous note of the lower voice.
+ * @param lowerCur Current note of the lower voice.
  * @category Voicing & Counterpoint
  */
+declare function createsVoiceOverlap(upperPrev: Note, upperCur: Note, lowerPrev: Note, lowerCur: Note): boolean;
 declare function createsVoiceOverlap(upperPrev: number, upperCur: number, lowerPrev: number, lowerCur: number): boolean;
 /**
  * Whether two adjacent upper voices are spaced more than a maximum apart
  * (commonly an octave). Bass-to-tenor spacing is conventionally exempt, so this
  * is meant for the upper voice pairs.
  *
- * @param upperPitch Pitch of the higher voice.
- * @param lowerPitch Pitch of the lower voice.
+ * @param upper The higher voice.
+ * @param lower The lower voice.
  * @param maxSemitones Maximum allowed spacing in semitones (default an octave).
  * @category Voicing & Counterpoint
  */
-declare function exceedsSpacing(upperPitch: number, lowerPitch: number, maxSemitones?: number): boolean;
+declare function exceedsSpacing(upper: Note, lower: Note, maxSemitones?: number): boolean;
+declare function exceedsSpacing(upper: number, lower: number, maxSemitones?: number): boolean;
 /**
  * Whether a leading tone resolves correctly upward to the tonic.
  *
- * @param prev The leading-tone pitch.
- * @param cur The following pitch.
+ * @param prev The leading-tone note.
+ * @param cur The following note.
  * @param key Key context supplying the tonic.
  * @returns True when `prev` is the leading tone and `cur` is the tonic a step above.
  * @category Voicing & Counterpoint
  */
+declare function isLeadingToneResolution(prev: Note, cur: Note, key: KeyScale): boolean;
 declare function isLeadingToneResolution(prev: number, cur: number, key: KeyScale): boolean;
 
+/**
+ * Total voice-leading cost between two voicings: the sum of absolute semitone
+ * motion across voices, plus a moderate hidden-perfect penalty when the
+ * outer-voice (bass–soprano) pair reaches a hidden/direct perfect fifth or
+ * octave by similar motion. The arrays must be the same length; when they
+ * differ the voicings are not comparable and the cost is `Infinity`.
+ *
+ * @param from The previous voicing, one MIDI pitch per voice.
+ * @param to The next voicing, one MIDI pitch per voice.
+ * @returns The summed absolute motion (plus any hidden-perfect penalty), or
+ *   `Infinity` when lengths differ.
+ * @category Voicing & Counterpoint
+ */
+declare function voiceLeadingCost(from: number[], to: number[]): number;
+/**
+ * Voice a single chord to follow smoothly from an arbitrary current voicing.
+ *
+ * Candidate voicings of `chord` are enumerated within ranges taken from `opts`,
+ * or — when neither `voices` nor `ranges` is given — from a one-octave window
+ * around each pitch of `current` (so the result matches `current`'s voice
+ * count). Each candidate is scored by structural quality, voice-leading motion
+ * from `current`, and a large penalty per counterpoint violation; the lowest
+ * scoring candidate is returned, ascending.
+ *
+ * @param current The current voicing to lead from, ascending (index 0 = lowest).
+ * @param chord The next chord to voice, as a chord symbol, chord data, or a
+ *   `Chord`.
+ * @param opts Voicing options; when omitted, ranges follow `current`'s span.
+ * @returns The chosen voicing, ascending with one MIDI pitch per voice.
+ * @throws If `current` is empty or holds a non-finite pitch while the ranges
+ *   are derived from it, if it asks for more voices than the search will take,
+ *   or if no voicing fits the ranges.
+ * @category Voicing & Counterpoint
+ */
+declare function nextVoicing(current: number[], chord: ChordLike, opts?: VoicingOptions): number[];
+
+/**
+ * Figured bass: read a bass note and its figures as the chord they name.
+ *
+ * The figures are intervals above the bass, and every interval a figure does
+ * not alter is the one the key's own scale gives. That is the whole rule of the
+ * notation, and the reason a realization needs the key: the same `6` names a
+ * major triad over one degree of C major and a diminished one over another.
+ *
+ * The bass arrives spelled, so the intervals above it are spelled too. The
+ * third above a G in C minor is the Bb the signature gives, and the bare `#`
+ * that raises it names B natural rather than an enharmonic Cb — which is what
+ * makes the figures of a real exercise readable as written.
+ */
+
+/**
+ * A figure that moves over a held bass, such as the `4-3` suspension.
+ *
+ * @category Functional Harmony
+ */
+type FiguredBassSuspension = {
+    /** The interval above the bass that sounds first: the suspended note. */
+    from: number;
+    /** The interval it moves to, which is the one the chord contains. */
+    to: number;
+    /** The suspended note, spelled. */
+    note: Note;
+    /** The note it moves to, spelled. */
+    resolution: Note;
+};
+/**
+ * Everything a figured bass states: the chord, its spelled notes, and any
+ * figure that moves.
+ *
+ * @category Functional Harmony
+ */
+type FiguredBassRealization = {
+    /**
+     * The chord the figures name, carrying the given bass as its `bassPc` and
+     * the letter spellings of its root and bass as enharmonic hints.
+     */
+    chord: Chord;
+    /**
+     * The spelled notes, bass first and then each figured interval in ascending
+     * order. They carry no octave: figures fix the intervals above the bass, not
+     * the register the upper voices take them in.
+     */
+    notes: Note[];
+    /**
+     * Every moving figure, in written order, or an empty array for a static one.
+     * The chord above is the harmony these resolve into.
+     */
+    suspensions: FiguredBassSuspension[];
+};
+/**
+ * Read a figured bass in full: the chord, its spelled notes, and its
+ * suspensions.
+ *
+ * The figure grammar, in the forms this accepts:
+ *
+ * - Nothing at all, `5`, `3` or `53` — the root-position triad.
+ * - `6` or `63` — the first-inversion triad; `64` — the second-inversion triad.
+ * - `7` — the root-position seventh chord; `65`, `43`, and `42` (also written
+ *   `2`) — its first, second, and third inversions. The full stacks `753`,
+ *   `653`, `643` and `642` name the same four chords.
+ * - Stacked figures may be written run together (`64`) or separated by a slash,
+ *   a comma or a space (`6/4`), which is the same figure either way.
+ * - An accidental in front of a figure alters that interval: `#6`, `b7`, `#43`.
+ *   A slashed or crossed figure raises its interval, and is typed `+` — `+6` is
+ *   `#6`. An accidental with no figure alters the third above the bass, so a
+ *   lone `#` over the dominant of a minor key raises its third to the leading
+ *   tone. `#` and `b` move the interval a semitone from what the key gives,
+ *   `##` and `bb` a whole tone, and `n` names the natural note whatever the key
+ *   gives. The Unicode accidentals are accepted alongside the typed ones.
+ * - A figure that moves is written with a hyphen: `4-3`, `9-8`, `7-6`, and any
+ *   other pair. Each side may carry its own accidental, as `4-#3` does in a
+ *   minor key. Moving figures may stand beside static ones (`5 4-3`).
+ *
+ * Every interval no accidental touches is the one the key's scale gives, which
+ * is why the key is required and why the same figure names different qualities
+ * over different degrees.
+ *
+ * A moving figure resolves into the chord: `4-3` over a G in C major returns
+ * the G major triad, and the suspended C is reported as a suspension rather
+ * than as a chord tone. A suspension is a melodic event over a single harmony —
+ * the sounding chord does not change when it resolves — so naming the
+ * resolution is the reading that answers "which chord is this", and the record
+ * of what was suspended is kept beside it rather than thrown away.
+ *
+ * @param bass The bass note, spelled: a note name, a MIDI number, note data, or
+ *   a `Note`; its octave, if any, is not used.
+ * @param figures The figures written under the bass; empty for an unfigured
+ *   note.
+ * @param key The prevailing key, which supplies every unaltered interval, as a
+ *   key name, a key/scale, or a `Key`.
+ * @returns The chord, its spelled notes, and any suspensions.
+ * @throws If the figures are malformed or name no chord
+ *   ({@link InvalidInputError}), if the key is not heptatonic
+ *   ({@link InvalidInputError}), or if the figures sound a chord no
+ *   {@link ChordQuality} names, such as an augmented sixth
+ *   ({@link NoSolutionError}).
+ * @example
+ * ```ts
+ * import { figuredBassRealization, majorKey, noteNames, parseNote } from '@libraz/libcantus';
+ * const realized = figuredBassRealization(parseNote('G'), '4-3', majorKey(0));
+ * noteNames(realized.notes); // ['G', 'B', 'D']
+ * realized.suspensions[0]?.from; // 4 — the suspended C above the bass
+ * ```
+ * @category Functional Harmony
+ */
+declare function figuredBassRealization(bass: NoteLike, figures: string, key: KeyLike): FiguredBassRealization;
+/**
+ * Realize a figured bass: the chord a bass note and its figures name in a key.
+ *
+ * The chord carries the given bass as its `bassPc`, so an inversion reads as
+ * one everywhere the library measures a bass against a root, and carries the
+ * letter spellings of its root and bass so the realization can be respelled
+ * without losing the accidentals the figures asked for.
+ *
+ * See {@link figuredBassRealization} for the figure grammar this accepts and
+ * for the spelled notes and suspensions it drops. A moving figure such as
+ * `4-3` returns the chord it resolves into.
+ *
+ * @param bass The bass note, spelled; its octave, if any, is not used.
+ * @param figures The figures written under the bass; empty for an unfigured
+ *   note.
+ * @param key The prevailing key, which supplies every unaltered interval.
+ * @param bass The bass note, spelled: a note name, a MIDI number, note data, or
+ *   a `Note`.
+ * @param figures The figures written under the bass.
+ * @param key The prevailing key, as a key name, a key/scale, or a `Key`.
+ * @returns The chord the figures name.
+ * @throws If the figures are malformed or name no chord
+ *   ({@link InvalidInputError}), if the key is not heptatonic
+ *   ({@link InvalidInputError}), or if the figures sound a chord no
+ *   {@link ChordQuality} names ({@link NoSolutionError}).
+ * @example
+ * ```ts
+ * import { majorKey, minorKey, parseNote, realizeFiguredBass } from '@libraz/libcantus';
+ * realizeFiguredBass(parseNote('B'), '6', majorKey(0));
+ * // G major with B in the bass: { rootPc: 7, quality: 'maj', bassPc: 11, ... }
+ * realizeFiguredBass(parseNote('G'), '#', minorKey(0));
+ * // G major in C minor: the raised third is a B natural
+ * ```
+ * @category Functional Harmony
+ */
+declare function realizeFiguredBass(bass: NoteLike, figures: string, key: KeyLike): Chord;
+/**
+ * Write a chord as the figures a bass would carry under it, in a key.
+ *
+ * The inverse of {@link realizeFiguredBass} for every chord the figure grammar
+ * reaches: the conventional abbreviation for the inversion (`6`, `64`, `7`,
+ * `65`, `43`, `42`, or nothing at all for a root-position triad), with an
+ * accidental on any interval the key does not already give. An altered
+ * interval the abbreviation would leave implied is written out, so the raised
+ * third of a dominant in a minor key emits `#3` rather than the bare `#` a
+ * score would print — the figures this returns read back as the same chord.
+ *
+ * What this returns is read back before it is returned, so the two directions
+ * cannot disagree: a chord the digits would name only approximately — an
+ * augmented sixth, whose tones do not stack in thirds over its bass — has no
+ * figures rather than figures that fail to realize.
+ *
+ * @param chord The chord to figure, as a chord symbol, chord data, or a
+ *   `Chord`; its `bassPc`, when present, is the bass the intervals are measured
+ *   above.
+ * @param key The prevailing key, which decides which intervals need no
+ *   accidental, as a key name, a key/scale, or a `Key`.
+ * @returns The figures, as {@link realizeFiguredBass} accepts them.
+ * @throws If the key is not heptatonic ({@link InvalidInputError}), or if no
+ *   figure names the chord — its bass is not one of its tones, its tones do not
+ *   stack in diatonic thirds above that bass, or it is an added-tone or
+ *   extended chord the notation has no abbreviation for
+ *   ({@link NoSolutionError}).
+ * @example
+ * ```ts
+ * import { figuredBassOf, majorKey, makeChord } from '@libraz/libcantus';
+ * figuredBassOf(makeChord(7, 'maj', 11), majorKey(0)); // '6' — G major over B
+ * figuredBassOf(makeChord(7, 'dom7', 2), majorKey(0)); // '43' — G7 over D
+ * ```
+ * @category Functional Harmony
+ */
+declare function figuredBassOf(chord: ChordLike, key: KeyLike): string;
+
 /**
  * Spelling: derive letter-name notes for scales and chords from a spelled tonic.
  *
@@ -268,35 +592,100 @@ declare function isLeadingToneResolution(prev: number, cur: number, key: KeyScal
  * G# and an Ab. Given a spelled tonic, this module assigns diatonic letters to
  * scale degrees and chord tones so a C major scale spells as C D E F G A B and
  * A harmonic minor spells its seventh as G#.
+ *
+ * Every entry point takes the spelled tonic *of the key it spells*: a tonic
+ * sounding a pitch class other than `key.rootPc` is rejected rather than
+ * spelled, because the letters counted from it name no reading of the key.
  */
 
 /**
- * Spell a single pitch class relative to a spelled tonic and key.
+ * The musical evidence around a pitch, used to refine an enharmonic choice the
+ * key alone cannot make.
  *
- * The tonic always spells as itself. In a heptatonic key each scale degree takes
- * the next letter above the tonic, so the scale spells with one letter per
- * degree. Every other pitch class — a chromatic tone in a heptatonic key, or any
- * tone of a scale that is not heptatonic (pentatonic, blues, octatonic) — takes
- * the conventional interval spelling above the tonic's letter, so a flat-side
- * key keeps flat-side names.
+ * Every field is optional and every field is only ever advisory: a context that
+ * says nothing about the pitch leaves its key spelling untouched.
+ *
+ * @category Pitch & Intervals
+ */
+type SpellingContext = {
+    /** Root pitch class of the chord sounding under the pitch, when known. */
+    chordRoot?: number;
+    /** The pitch immediately before this one (MIDI pitch or bare pitch class). */
+    previous?: number;
+    /** The pitch immediately after this one (MIDI pitch or bare pitch class). */
+    next?: number;
+};
+/**
+ * Spell a single pitch class relative to a spelled tonic and key, optionally
+ * refined by the music around it.
+ *
+ * Without a context the key decides alone: the tonic spells as itself, each
+ * degree of a heptatonic key takes the next letter above the tonic, a gapped
+ * scale gives each of its own tones a letter wherever its pitch set allows one,
+ * and every other pitch class takes the conventional interval spelling above
+ * the tonic's letter, so a flat-side key keeps flat-side names.
+ *
+ * A context only ever refines a pitch class the key leaves ambiguous — one that
+ * is not a tone of `key`. Scale tones, and the tonic, keep their key spelling
+ * whatever the context says.
+ *
+ * The melodic rules read the two neighbours differently, because a chromatic
+ * note is an inflection of the note it came from but a leading tone into the
+ * note it goes to: `next` moves the letter, `previous` keeps it. For a chromatic
+ * pitch class the evidence is weighed in this order, and the first spelling
+ * within a double accidental wins:
+ *
+ * 1. The sounding chord, when `chordRoot` is given and the pitch is an
+ *    unambiguous chord tone above it (root, third, fifth or seventh) — the third
+ *    of a secondary dominant D7 in C major spells F#, not Gb.
+ * 2. Resolution: `next` a semitone above makes the pitch a leading tone into it,
+ *    one letter below — the C# rising to D in D minor.
+ * 3. Approach: `previous` a semitone below inflects that note upward, keeping
+ *    its letter, so a chromatic ascent spells with sharps — F F# G in C major.
+ * 4. Descent: `next` a semitone below puts the pitch one letter above it, so a
+ *    falling chromatic line spells with flats — A Ab G in C major. Failing that,
+ *    `previous` a semitone above inflects that note downward on its own letter,
+ *    which spells the same line from the note before instead.
+ *
+ * If no rule applies, or every candidate would need more than a double
+ * accidental, the key spelling stands.
  *
  * @param pc The pitch class to spell.
- * @param tonic The spelled tonic (its letter anchors the spelling).
- * @param key The key/scale.
+ * @param tonic The spelled tonic (its letter anchors the spelling), as a note
+ *   name, a MIDI number, note data, or a `Note`.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`.
+ * @param context Optional surrounding evidence; an absent or empty context
+ *   spells exactly as the key alone does.
  * @returns The spelled note (without octave).
+ * @throws If `tonic` does not sound the key's root pitch class.
+ * @example
+ * ```ts
+ * import { spellPitchClass, formatNote, parseNote, majorKey } from '@libraz/libcantus';
+ * const c = parseNote('C');
+ * formatNote(spellPitchClass(6, c, majorKey(0))); // 'F#'
+ * // The third of D7, the secondary dominant of G.
+ * formatNote(spellPitchClass(6, 'C', 'C major', { chordRoot: 2 })); // 'F#'
+ * // A chromatic passing tone falling from G to F.
+ * formatNote(spellPitchClass(6, c, majorKey(0), { previous: 7, next: 5 })); // 'Gb'
+ * ```
  * @category Pitch & Intervals
  */
-declare function spellPitchClass(pc: number, tonic: Note, key: KeyScale): Note;
+declare function spellPitchClass(pc: number, tonic: NoteLike, key: KeyLike, context?: SpellingContext): Note;
 /**
  * Spell every pitch class of a scale, in ascending scale-degree order.
  *
- * Correct for heptatonic scales (each degree gets the next letter). A scale that
- * is not heptatonic is spelled tone by tone, on the accidental side the scale
- * leans towards.
+ * Correct for heptatonic scales (each degree gets the next letter). A gapped
+ * scale gives each of its tones a letter of its own wherever its pitch set
+ * allows one — C miyako-bushi spells C Db F G Ab — and is spelled tone by tone,
+ * on the accidental side the scale leans towards, where it does not: the blues
+ * scale has to name one letter twice however it is read.
  *
- * @param tonic The spelled tonic.
- * @param key The key/scale.
+ * @param tonic The spelled tonic, as a note name, a MIDI number, note data, or a
+ *   `Note`.
+ * @param key The key/scale. This one stays a plain key/scale: the key-spelling
+ *   search reads scales through it that no key name describes.
  * @returns Spelled notes, one per scale degree.
+ * @throws If `tonic` does not sound the key's root pitch class.
  * @example
  * ```ts
  * import { spellScale, noteNames, parseNote, majorKey } from '@libraz/libcantus';
@@ -305,24 +694,35 @@ declare function spellPitchClass(pc: number, tonic: Note, key: KeyScale): Note;
  * ```
  * @category Pitch & Intervals
  */
-declare function spellScale(tonic: Note, key: KeyScale): Note[];
+declare function spellScale(tonic: NoteLike, key: KeyScale): Note[];
 /**
  * Spell an arbitrary list of pitch classes relative to a key.
  *
  * @param pcs The pitch classes.
- * @param tonic The spelled tonic.
- * @param key The key/scale.
+ * @param tonic The spelled tonic, as a note name, a MIDI number, note data, or a
+ *   `Note`.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`.
  * @returns Spelled notes, in input order.
+ * @throws If `tonic` does not sound the key's root pitch class.
  * @category Pitch & Intervals
  */
-declare function spellPitchClasses(pcs: number[], tonic: Note, key: KeyScale): Note[];
+declare function spellPitchClasses(pcs: number[], tonic: NoteLike, key: KeyLike): Note[];
 /**
  * Spell chord tones from an already chosen root spelling.
  *
- * This is exported for the model layer's inversion support; the package
- * barrels intentionally expose the key-aware {@link spellChord} entry point.
+ * This is public for callers that already know the desired root spelling;
+ * {@link spellChord} instead derives that spelling from the chord and key.
+ *
+ * Letters follow the chord's own tone spellings when it carries a usable set,
+ * and otherwise the diatonic distance each interval implies in a stack of
+ * thirds. Accidentals are always recomputed from the sounding pitch class, so
+ * the tones name exactly the chord's own pitch classes either way.
+ *
+ * @param chord The chord whose tones are spelled.
+ * @param root The chosen root spelling, as a note name, a MIDI number, note
+ *   data, or a `Note`.
  */
-declare function spellChordFromRoot(chord: Chord, root: Note): Note[];
+declare function spellChordFromRoot(chord: Chord, root: NoteLike): Note[];
 /**
  * Spell a chord's tones, in the chord's own (tertian) order, relative to a key.
  *
@@ -331,10 +731,18 @@ declare function spellChordFromRoot(chord: Chord, root: Note): Note[];
  * tensions may be spelled by the general convention rather than by chord
  * function.
  *
+ * A chord carrying its own tone spellings is spelled by them, since a chord
+ * whose letters do not follow from stacking thirds can say so no other way:
+ * that is what keeps the German sixth of C major on its F#, the note that
+ * resolves outward to the dominant, rather than the Gb a dominant seventh
+ * would put there.
+ *
  * @param chord The chord.
- * @param tonic The spelled tonic of the key.
- * @param key The key/scale.
+ * @param tonic The spelled tonic of the key, as a note name, a MIDI number,
+ *   note data, or a `Note`.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`.
  * @returns Spelled chord tones, root first.
+ * @throws If `tonic` does not sound the key's root pitch class.
  * @example
  * ```ts
  * import { spellChord, noteNames, parseNote, majorKey, makeChord } from '@libraz/libcantus';
@@ -344,7 +752,7 @@ declare function spellChordFromRoot(chord: Chord, root: Note): Note[];
  * ```
  * @category Pitch & Intervals
  */
-declare function spellChord(chord: Chord, tonic: Note, key: KeyScale): Note[];
+declare function spellChord(chord: Chord, tonic: NoteLike, key: KeyLike): Note[];
 /**
  * Spell a MIDI pitch relative to a key, keeping its octave.
  *
@@ -352,10 +760,18 @@ declare function spellChord(chord: Chord, tonic: Note, key: KeyScale): Note[];
  * for chord and scale spelling; this one is for naming actual sounding pitches
  * (a generated line, an imported track) without losing the register.
  *
+ * The octave is the one that reproduces `pitch` from the chosen spelling, so a
+ * context that changes the letter changes the octave with it: MIDI 60 spelled
+ * B# is B#3, not B#4.
+ *
  * @param pitch The MIDI pitch; rounded to the nearest integer.
- * @param tonic The spelled tonic of the key.
- * @param key The key/scale.
+ * @param tonic The spelled tonic of the key, as a note name, a MIDI number,
+ *   note data, or a `Note`.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`.
+ * @param context Optional surrounding evidence, weighed exactly as
+ *   {@link spellPitchClass} weighs it.
  * @returns The spelled note, carrying the octave that reproduces `pitch`.
+ * @throws If `tonic` does not sound the key's root pitch class.
  * @example
  * ```ts
  * import { spellPitch, formatNote, parseNote, majorKey } from '@libraz/libcantus';
@@ -363,91 +779,15 @@ declare function spellChord(chord: Chord, tonic: Note, key: KeyScale): Note[];
  * ```
  * @category Pitch & Intervals
  */
-declare function spellPitch(pitch: number, tonic: Note, key: KeyScale): Note;
+declare function spellPitch(pitch: number, tonic: NoteLike, key: KeyLike, context?: SpellingContext): Note;
 /**
  * Convenience: render spelled notes as letter-name strings.
  *
- * @param notes The notes.
+ * @param notes The notes, each a note name, a MIDI number, note data, or a
+ *   `Note`.
  * @returns Their formatted names.
  * @category Pitch & Intervals
  */
-declare function noteNames(notes: Note[]): string[];
-
-/**
- * Lead-sheet chord symbol parsing and formatting.
- *
- * Bridges the informal `<root><quality>[/<bass>]` notation musicians write
- * (`Cmaj7`, `F#m7b5`, `Bb7`, `C/G`) and the library's structured {@link Chord}
- * type, so callers can accept/emit plain text at the edges of the API.
- */
-
-/**
- * Parse a lead-sheet chord symbol into a {@link Chord}.
- *
- * Accepts `<root><quality>[/<bass>]`, e.g. `Cmaj7`, `F#m7b5`, `Bb7`, `C/G`,
- * `C6/9`, `C6/9/E`. Root and bass letters are case-insensitive, matching
- * {@link parseNote}. A `/` is ambiguous between a slash bass and the `6/9`
- * quality; the text splits at the last `/` whose right-hand side is a valid
- * bare note preceded by a recognized quality, so `6/9` (with or without a
- * further slash bass) parses as a quality.
- *
- * The parsed chord carries the root/bass spellings as enharmonic hints
- * (`rootSpelling`/`bassSpelling`) so {@link formatChordSymbol} can reproduce
- * flat spellings such as `Bbmaj7` instead of respelling them with sharps.
- *
- * @param text The chord symbol text.
- * @returns The parsed chord.
- * @throws If the root or quality is not recognized.
- * @example
- * ```ts
- * import { parseChordSymbol, formatChordSymbol } from '@libraz/libcantus';
- * const c = parseChordSymbol('Bbmaj7');
- * formatChordSymbol(c); // 'Bbmaj7' — flat spelling is preserved on round-trip
- * ```
- * @category Chords
- */
-declare function parseChordSymbol(text: string): Chord;
-/**
- * Format a {@link Chord} as a lead-sheet chord symbol.
- *
- * The inverse of {@link parseChordSymbol}: each quality maps to one canonical
- * suffix spelling, and a slash bass is appended only when it differs from the
- * root. When the chord carries `rootSpelling`/`bassSpelling` hints (as chords
- * from {@link parseChordSymbol} do) and no explicit `flats` preference is
- * given, the hints are reused so flat symbols round-trip unchanged.
- *
- * @param chord The chord to format.
- * @param opts Formatting options.
- * @param opts.flats Prefer flat spellings over sharps for altered roots/basses;
- *   passing either `true` or `false` overrides any spelling hints.
- * @returns The chord symbol text.
- * @example
- * ```ts
- * import { makeChord, formatChordSymbol } from '@libraz/libcantus';
- * formatChordSymbol(makeChord(0, 'min7')); // 'Cm7'
- * ```
- * @category Chords
- */
-declare function formatChordSymbol(chord: Chord, opts?: {
-    flats?: boolean;
-}): string;
-/**
- * Transpose a chord symbol by a number of semitones.
- *
- * @param text The chord symbol text.
- * @param semitones Signed semitone offset to apply to the root and bass.
- * @param opts Formatting options for the result; see {@link formatChordSymbol}.
- * @returns The transposed chord symbol text.
- * @throws If `text` does not parse as a chord symbol.
- * @example
- * ```ts
- * import { transposeChordSymbol } from '@libraz/libcantus';
- * transposeChordSymbol('C/G', 2); // 'D/A'
- * ```
- * @category Chords
- */
-declare function transposeChordSymbol(text: string, semitones: number, opts?: {
-    flats?: boolean;
-}): string;
+declare function noteNames(notes: readonly NoteLike[]): string[];
 
-export { Chord as ChordData, KeyScale, Note as NoteData, ScaleNameInput, VoicingOptions, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, diatonicPitchClasses, exceedsSpacing, formatChordSymbol, isForbiddenMelodicLeap, isLeadingToneResolution, isScaleTone, majorKey, minorKey, nearestScaleTone, nextVoicing, noteNames, parseChordSymbol, pitchToScaleDegree, scaleByName, scaleTonesInDegreeOrder, spellChord, spellChordFromRoot, spellPitch, spellPitchClass, spellPitchClasses, spellScale, transposeChordSymbol, voiceLeadingCost };
+export { Chord as ChordData, ChordLike, ConsonanceClass, type FiguredBassRealization, type FiguredBassSuspension, KeyLike, KeyScale, Note as NoteData, NoteLike, ScaleNameInput, SpelledInterval, type SpellingContext, VoicingOptions, classifySpelledInterval, createsBattuta, createsHiddenParallelPerfect, createsParallelOctave, createsParallelPerfect, createsParallelUnison, createsVerticalDissonance, createsVoiceCrossing, createsVoiceOverlap, diatonicPitchClasses, exceedsSpacing, figuredBassOf, figuredBassRealization, isAugmentedMelodicInterval, isForbiddenMelodicLeap, isLeadingToneResolution, isScaleTone, majorKey, minorKey, nearestScaleTone, nextVoicing, noteNames, pitchToScaleDegree, realizeFiguredBass, scaleByName, scaleTonesInDegreeOrder, spellChord, spellChordFromRoot, spellPitch, spellPitchClass, spellPitchClasses, spellScale, voiceLeadingCost };