@libraz/libcantus 0.9.4 → 1.0.0

package/dist/index-C_8o--VE.d.cts

@@ -0,0 +1,1242 @@
+import { d as KeyScale, f as Note, h as NoteLike, i as NoteNameOptions, P as ParseResult } from './index-B9MNZboQ.cjs';
+
+/**
+ * Anything that names a key: a key name, a plain {@link KeyScale}, or a value
+ * that serializes to one such as the `Key` class.
+ *
+ * @category Scales
+ */
+type KeyLike = string | KeyScale | {
+    /** The key data this value stands for, carrying the scale it denotes. */
+    toJSON(): {
+        scale: KeyScale;
+    };
+};
+/**
+ * Resolve any key-shaped value to a plain {@link KeyScale}.
+ *
+ * The counterpart of {@link toSpelledInterval} for keys: an entry point takes
+ * whatever form the caller has — the name a key field holds, the scale the
+ * theory module returns, or a `Key` instance — and gets one shape back. An
+ * instance is accepted through its `toJSON` method rather than by its type, so
+ * the layers below the model can read a class without importing it.
+ *
+ * A name is read by {@link parseKeyName} and nothing else, so every entry point
+ * that takes a key accepts exactly the names a key field already accepts, in
+ * every notation system it already reads. The mode word decides the scale: a
+ * major name gives the major scale, a minor name the natural minor. The
+ * harmonic and melodic forms have no name of their own, so a caller who needs
+ * one builds it with {@link scaleByName} and passes the scale.
+ *
+ * @param value A key name, a plain key/scale, or a value whose `toJSON`
+ *   returns data carrying one.
+ * @returns The validated key/scale, with its root reduced to a pitch class.
+ * @throws If the value names no key, or its mode mask is out of range or
+ *   excludes its own root.
+ * @example
+ * ```ts
+ * import { toKeyScale } from '@libraz/libcantus';
+ * toKeyScale('C major').rootPc; // 0
+ * toKeyScale('A minor').rootPc; // 9
+ * ```
+ * @category Scales
+ */
+declare function toKeyScale(value: KeyLike): KeyScale;
+
+/**
+ * How keys stand to one another: the relative, parallel, dominant and
+ * subdominant keys, the enharmonic respelling of a key, and the relation that
+ * holds between two given keys.
+ *
+ * Every relation but {@link parallelKeyOf} is computed in fifths space, on top
+ * of {@link keySignatureFifths} and {@link keyFromFifths}. Stepping around the
+ * circle of fifths and reading the tonic back off it is what keeps the spelling
+ * right: the relative of Db major comes out as Bb minor, not A# minor.
+ *
+ * A relation always returns a plain major or minor key, because those are the
+ * only keys these relations name; {@link enharmonicKeyOf} is the exception that
+ * proves it, since a respelling is the same key rather than another one and so
+ * keeps the mask it was handed. A key that is not a plain major or minor —
+ * a church mode, harmonic minor, a pentatonic, an octatonic — is read through
+ * the mode its third names, and the fifths are counted from where its tonic
+ * stands on the circle rather than from the key's own signature: a mode's
+ * signature carries its own offset (D dorian is two fifths flatter than D
+ * major), which {@link keyFromFifths} does not know how to give back.
+ * {@link parallelKeyOf} travels no fifths at all, so it keeps the tonic
+ * spelling it was given.
+ */
+
+/**
+ * A key paired with the spelled tonic that anchors its letter names.
+ *
+ * The tonic carries no octave: a key is rooted on a pitch class, and its
+ * spelling is what decides whether the key is written Db major or C# major.
+ *
+ * @example
+ * ```ts
+ * import type { SpelledKey } from '@libraz/libcantus';
+ * import { majorKey, parseNote } from '@libraz/libcantus';
+ * const dbMajor: SpelledKey = { tonic: parseNote('Db'), key: majorKey(1) };
+ * ```
+ * @category Scales
+ */
+type SpelledKey = {
+    tonic: Note;
+    key: KeyScale;
+};
+/**
+ * How one key stands to another, as reported by {@link keyRelationBetween} and
+ * tagged onto every entry of {@link relatedKeysOf}.
+ *
+ * @example
+ * ```ts
+ * import type { KeyRelation } from '@libraz/libcantus';
+ * const relation: KeyRelation = 'relative'; // C major -> A minor
+ * ```
+ * @category Scales
+ */
+type KeyRelation = 'same' | 'enharmonic' | 'relative' | 'parallel' | 'dominant' | 'subdominant' | 'relativeOfDominant' | 'relativeOfSubdominant';
+/**
+ * Spell a key's tonic the conventional way: the letter and accidental the key
+ * is written with, paired with the key exactly as given.
+ *
+ * The candidates are the tonics keys are actually written on — everything from
+ * Cb to A#, which names each pitch class once or twice (C, but Db and C#) — and
+ * which of them names the key depends on whether the key has a signature of its
+ * own. A major or minor key, a church mode, and the harmonic and melodic minor
+ * are spelled on the tonic their signature is written on: pitch class 1 in
+ * major is Db, five flats, rather than C#, seven sharps; pitch class 8 in minor
+ * is G#, five sharps, rather than Ab, seven flats; and G# harmonic minor writes
+ * its raised seventh F## as an accidental over that signature rather than
+ * respelling the key. Where two signatures are equally long — pitch class 6 in
+ * major is F# at +6 and Gb at -6 — the flat side is taken.
+ *
+ * Every other scale only borrows the signature of its parallel major or minor,
+ * so nothing follows from it and the scale is spelled on the tonic it reads
+ * best from: the fewest double accidentals first, then the fewest accidentals
+ * altogether, and only then the shorter signature. That is why pitch class 1
+ * altered is C# — C# D E F G A B — rather than Db, which would have to write
+ * four double flats to say the same thing, and why pitch class 8 minor
+ * pentatonic is G# B C# D# F# rather than Ab B Db Eb Gb, which reads its third
+ * as an augmented second.
+ *
+ * The mask's third picks the mode the signature is measured in — a minor third
+ * and no major third reads as minor, anything else as major — and the key is
+ * returned unchanged, so a scale keeps its own mask and only borrows a tonic
+ * spelling. A caller that has a tonic spelling of its own always keeps it: this
+ * only answers for a key that arrives as a bare pitch class.
+ *
+ * Every 12-bit mask and every integer root is answered — a root outside [0, 11]
+ * is reduced first, and a mask with no third at all counts as major.
+ *
+ * The key is paired with the answer exactly as it was handed in, root and mask
+ * untouched, so this takes a plain key/scale rather than the wider forms the
+ * relations below accept: a coerced key could not be given back verbatim.
+ *
+ * @param key The key/scale to spell.
+ * @returns The conventional tonic spelling, paired with `key` verbatim.
+ * @example
+ * ```ts
+ * import { formatNote, majorKey, scaleByName, spelledKeyOf } from '@libraz/libcantus';
+ * formatNote(spelledKeyOf(majorKey(1)).tonic); // 'Db'
+ * formatNote(spelledKeyOf(scaleByName('harmonicMinor', 8)).tonic); // 'G#'
+ * formatNote(spelledKeyOf(scaleByName('altered', 1)).tonic); // 'C#'
+ * ```
+ * @category Scales
+ */
+declare function spelledKeyOf(key: KeyScale): SpelledKey;
+/**
+ * The relative key: the same key signature read in the other mode.
+ *
+ * C major and A minor share a signature, and so are each other's relative; the
+ * relation is its own inverse for a plain major or minor key. Because the new
+ * tonic is read off the circle of fifths rather than transposed by semitones,
+ * the relative of Db major is Bb minor and not its enharmonic A# minor.
+ *
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
+ *   `Note`.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
+ *   decides which mode the relative is in.
+ * @returns The relative key and the tonic spelling it is written with.
+ * @throws If the tonic or the mask is malformed, or if the key's signature
+ *   falls outside [-12, 12] fifths.
+ * @example
+ * ```ts
+ * import { formatNote, majorKey, parseNote, relativeKeyOf } from '@libraz/libcantus';
+ * formatNote(relativeKeyOf(parseNote('C'), majorKey(0)).tonic); // 'A'
+ * formatNote(relativeKeyOf('Db', majorKey(1)).tonic); // 'Bb'
+ * ```
+ * @category Scales
+ */
+declare function relativeKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
+/**
+ * The parallel key: the other mode on the same tonic.
+ *
+ * The tonic keeps the spelling it was given — the parallel minor of C major is
+ * C minor, never B# minor — which is why this is the one relation here that
+ * does not travel the circle of fifths.
+ *
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
+ *   `Note`; its letter and alteration are kept.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
+ *   decides which mode the parallel is in.
+ * @returns The parallel key on the same tonic.
+ * @throws If the tonic or the mask is malformed.
+ * @example
+ * ```ts
+ * import { formatNote, majorKey, parallelKeyOf, parseNote } from '@libraz/libcantus';
+ * const parallel = parallelKeyOf(parseNote('C'), majorKey(0));
+ * formatNote(parallel.tonic); // 'C'
+ * ```
+ * @category Scales
+ */
+declare function parallelKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
+/**
+ * The dominant key: the key a fifth above, in the mode this key's third names.
+ *
+ * The fifth is measured from the tonic, so a key that is not a plain major or
+ * minor answers with the same move: the dominant of G mixolydian is D major and
+ * the dominant of D dorian is A minor.
+ *
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
+ *   `Note`.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
+ *   decides the mode of the result.
+ * @returns The key a fifth above, in the mode this key's third names.
+ * @throws If the tonic or the mask is malformed, or if the resulting signature
+ *   falls outside [-12, 12] fifths — the dominant of a key already at +12.
+ * @example
+ * ```ts
+ * import { dominantKeyOf, formatNote, majorKey, parseNote } from '@libraz/libcantus';
+ * formatNote(dominantKeyOf(parseNote('C'), majorKey(0)).tonic); // 'G'
+ * ```
+ * @category Scales
+ */
+declare function dominantKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
+/**
+ * The subdominant key: the key a fifth below, in the mode this key's third
+ * names, and the exact inverse of {@link dominantKeyOf} on the tonic spelling.
+ *
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
+ *   `Note`.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
+ *   decides the mode of the result.
+ * @returns The key a fifth below, in the mode this key's third names.
+ * @throws If the tonic or the mask is malformed, or if the resulting signature
+ *   falls outside [-12, 12] fifths — the subdominant of a key already at -12.
+ * @example
+ * ```ts
+ * import { formatNote, majorKey, parseNote, subdominantKeyOf } from '@libraz/libcantus';
+ * formatNote(subdominantKeyOf(parseNote('C'), majorKey(0)).tonic); // 'F'
+ * ```
+ * @category Scales
+ */
+declare function subdominantKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey;
+/**
+ * The same sounding key written the other way round the circle of fifths, or
+ * null when it has no second spelling.
+ *
+ * Twelve fifths is one enharmonic turn of the circle, so a tonic's alternative
+ * spelling sits at its own position ±12: Db (-5) is also C# (+7). It is offered
+ * only when the key is actually written there, by the same test
+ * {@link spelledKeyOf} spells with. That is why C major is alone while Db major
+ * and F# major each answer with their twin: Eb major's twin would be D# major
+ * and its nine sharps, and pitch class 3 altered is written D# but never Eb,
+ * which would need two double flats to say the same thing.
+ *
+ * The answer is therefore always a spelling the key is written on, which makes
+ * the relation its own inverse for such a key. A key spelled some other way —
+ * a tonic a transposition drove out to Ebb, say — still names its written twin,
+ * so this is also the way back from a spelling no one writes.
+ *
+ * The relation respells rather than moves, so the mask is kept: the other
+ * spelling of C# lydian is Db lydian, and its root pitch class is the one it
+ * was handed.
+ *
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
+ *   `Note`.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`; its mask
+ *   decides the mode the tonic is read in, and is carried into the result.
+ * @returns The other spelling of the key, or null when it is not written.
+ * @throws If the tonic or the mask is malformed.
+ * @example
+ * ```ts
+ * import { enharmonicKeyOf, formatNote, majorKey, parseNote } from '@libraz/libcantus';
+ * const other = enharmonicKeyOf(parseNote('Db'), majorKey(1));
+ * other === null ? 'none' : formatNote(other.tonic); // 'C#'
+ * enharmonicKeyOf('C', majorKey(0)); // null
+ * ```
+ * @category Scales
+ */
+declare function enharmonicKeyOf(tonic: NoteLike, key: KeyLike): SpelledKey | null;
+/**
+ * The six closely related keys of a key, each tagged with its relation.
+ *
+ * These are the keys the German and Japanese teaching tradition counts as a
+ * key's near relations: the relative and parallel keys, the dominant and the
+ * subdominant, and the relatives of those two. For C major they are A minor,
+ * C minor, G major, F major, E minor and D minor, in that order. Five of them
+ * are written within one accidental of the key's own signature — the relative
+ * shares it exactly and the other four stand one away; the parallel key does
+ * not — C minor is three flats away from C major — and belongs to the set for
+ * the tonic it shares rather than for the signature it carries.
+ *
+ * @param tonic The spelled tonic of the key, as a note name, note data, or a
+ *   `Note`.
+ * @param key The key/scale, as a key name, a key/scale, or a `Key`.
+ * @returns The six related keys, in relation order, each with its tonic
+ *   spelling and its `relation` tag.
+ * @throws If the tonic or the mask is malformed, or if a neighbouring signature
+ *   falls outside [-12, 12] fifths.
+ * @example
+ * ```ts
+ * import { majorKey, parseNote, relatedKeysOf } from '@libraz/libcantus';
+ * relatedKeysOf(parseNote('C'), majorKey(0)).map((related) => related.relation);
+ * // ['relative', 'parallel', 'dominant', 'subdominant', 'relativeOfDominant', 'relativeOfSubdominant']
+ * ```
+ * @category Scales
+ */
+declare function relatedKeysOf(tonic: NoteLike, key: KeyLike): (SpelledKey & {
+    relation: KeyRelation;
+})[];
+/**
+ * How the second key stands to the first, or null when they are not related.
+ *
+ * The relations are tested in a fixed order — identity, enharmonic spelling,
+ * then the six closely related keys in the order {@link relatedKeysOf} lists
+ * them — and the first match is reported. Only the identity test looks at the
+ * tonic spelling; every other test compares root pitch class and mode, so
+ * C# minor and Db minor both read as the relative of E major.
+ *
+ * Both keys are read through the mode their third names, exactly as
+ * {@link relatedKeysOf} reads the key it is given, so A harmonic minor stands
+ * to C major as A minor does whichever of the two is asked about. That is what
+ * makes the answer symmetric: if one key's related keys name the other, the
+ * relation between them is reported from either side.
+ *
+ * @param a The key the relation is measured from.
+ * @param b The key the relation is measured to.
+ * @returns The relation, or null when `b` is none of `a`'s related keys.
+ * @throws If either key is malformed, or if a neighbouring signature of `a`
+ *   falls outside [-12, 12] fifths.
+ * @example
+ * ```ts
+ * import { keyRelationBetween, majorKey, minorKey, parseNote } from '@libraz/libcantus';
+ * const cMajor = { tonic: parseNote('C'), key: majorKey(0) };
+ * keyRelationBetween(cMajor, { tonic: parseNote('A'), key: minorKey(9) }); // 'relative'
+ * keyRelationBetween(cMajor, { tonic: parseNote('Eb'), key: minorKey(3) }); // null
+ * ```
+ * @category Scales
+ */
+declare function keyRelationBetween(a: SpelledKey, b: SpelledKey): KeyRelation | null;
+
+/**
+ * The structured reading of a chord: what it is built from, not what it is
+ * called.
+ *
+ * A quality name is a closed vocabulary and a lead sheet's harmony is not. A
+ * chart writes a *set* of alterations over a base — `maj7#11`, `7b9#11`,
+ * `sus4(add9)` — so an enumeration of names can never be complete, and every
+ * name added to one is a name missing from its neighbours. A {@link ChordSpec}
+ * names the parts instead: a base triad, an optional seventh, altered, added
+ * and omitted degrees. A combination nothing names still has exact intervals,
+ * an exact pitch-class set, and a symbol that reads back as itself.
+ *
+ * Each {@link ChordQuality} is an alias for one spec, so the two directions
+ * cannot drift: a named chord's interval template is derived from its spec
+ * rather than listed beside it.
+ */
+/**
+ * Chord quality identifiers understood by the chord builder.
+ *
+ * Each name is an alias for one {@link ChordSpec}. The union is closed, so it
+ * names the chords a chart writes most often rather than every chord that can
+ * be written; build the rest from a spec.
+ *
+ * @category Chords
+ */
+type ChordQuality = 'maj' | 'min' | 'dim' | 'aug' | 'maj7' | 'min7' | 'dom7' | 'dim7' | 'm7b5' | 'minMaj7' | 'minMaj9' | 'minMaj11' | 'minMaj13' | 'aug7' | 'augMaj7' | 'majb5' | '6' | 'min6' | '6/9' | 'sus2' | 'sus4' | 'add9' | 'add11' | 'maj9' | 'min9' | 'dom9' | '7b9' | '7#9' | '7#11' | '7b13' | '11' | '13' | '5' | '7sus4' | '7b5' | '7alt' | '13b9' | 'maj13' | 'maj7#11' | 'min11' | 'min13' | 'minAdd9' | 'min6/9';
+/**
+ * The triad (or dyad) a chord is built on, before any seventh or tension.
+ *
+ * `sus2` and `sus4` replace the third rather than sitting beside it, and
+ * `power` is the bare root and fifth, so the base says which tones the chord
+ * has before anything is added to them.
+ *
+ * @category Chords
+ */
+type ChordBase = 'maj' | 'min' | 'dim' | 'aug' | 'sus2' | 'sus4' | 'power';
+/**
+ * The seventh stacked over a base: major, minor, or diminished.
+ *
+ * @category Chords
+ */
+type ChordSeventh = 'maj7' | 'min7' | 'dim7';
+/**
+ * A chord degree that can be raised or lowered: the fifth and the tensions.
+ *
+ * @category Chords
+ */
+type AlteredDegree = 5 | 9 | 11 | 13;
+/**
+ * One altered degree: which one, and by how much.
+ *
+ * `alter: 0` is not redundant — it says the degree is *present* and unaltered,
+ * which is what the natural ninth of a thirteenth chord is.
+ *
+ * @category Chords
+ */
+type Alteration = {
+    degree: AlteredDegree;
+    alter: -1 | 0 | 1;
+};
+/**
+ * A chord as its parts: base, seventh, alterations, additions and omissions.
+ *
+ * The library's structural chord model. `alterations` are tensions over a
+ * seventh chord; `additions` are degrees added without one (`add9`, and the
+ * sixth of a sixth chord); `omissions` are degrees the chord leaves out (the
+ * third of an eleventh chord, the fifth of a shell voicing) named by chord
+ * degree, so `omissions: [5]` is a fifth-less chord.
+ *
+ * @category Chords
+ */
+type ChordSpec = {
+    rootPc: number;
+    base: ChordBase;
+    seventh?: ChordSeventh;
+    alterations: Alteration[];
+    additions: number[];
+    omissions: number[];
+    bassPc?: number;
+};
+/**
+ * The semitone offsets above the root a spec sounds, ascending.
+ *
+ * The library's single derivation of chord tones: a name contributes nothing
+ * here, so a combination of alterations no name covers yields its intervals the
+ * same way a `maj7` does.
+ *
+ * @param spec The chord spec.
+ * @returns Semitone offsets above the root, ascending and deduplicated.
+ * @throws If any part of the spec is not one the model defines
+ *   ({@link InvalidInputError}), exactly as {@link chordFromSpec} rejects it.
+ *
+ * @example
+ * ```ts
+ * import { chordSpecIntervals } from '@libraz/libcantus';
+ * chordSpecIntervals({
+ *   rootPc: 0,
+ *   base: 'maj',
+ *   seventh: 'min7',
+ *   alterations: [{ degree: 9, alter: -1 }, { degree: 11, alter: 1 }],
+ *   additions: [],
+ *   omissions: [],
+ * });
+ * // [0, 4, 7, 10, 13, 18] — the C7(b9,#11) no quality name covers
+ * ```
+ *
+ * @category Chords
+ */
+declare function chordSpecIntervals(spec: ChordSpec): number[];
+/**
+ * The quality name a spec is reported under.
+ *
+ * A spec no name covers still has to answer, because `quality` is a required
+ * field of every {@link Chord} and of the records that travel with one. The
+ * answer is the *nearest* name: the largest named chord whose every tone this
+ * spec also sounds, and failing that the name of its base. Nothing is lost by
+ * it — the spec and the interval template still carry the alterations, and a
+ * symbol is written from those rather than from this name.
+ *
+ * @param spec The chord spec.
+ * @returns The name that fits the spec exactly, or the nearest one that fits
+ *   inside it.
+ * @throws If any part of the spec is not one the model defines
+ *   ({@link InvalidInputError}), exactly as {@link chordFromSpec} rejects it.
+ *
+ * @example
+ * ```ts
+ * import { chordSpecQuality, parseChordSymbol } from '@libraz/libcantus';
+ * parseChordSymbol('C7(b9,#11)').quality; // '7b9' — the nearest name
+ * chordSpecQuality({ rootPc: 0, base: 'maj', seventh: 'min7', alterations: [],
+ *   additions: [], omissions: [] }); // 'dom7'
+ * ```
+ *
+ * @category Chords
+ */
+declare function chordSpecQuality(spec: ChordSpec): ChordQuality;
+
+/**
+ * The basic role a chord tone plays: the degrees a chord's own template names.
+ *
+ * The shared vocabulary behind {@link chordToneRole}, the harmony layer's
+ * `HarmonyRole`, and the voice analyser's labels, so the three cannot drift.
+ *
+ * @category Chords
+ */
+type ChordToneRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh';
+/**
+ * A bare spelled pitch used as an enharmonic hint: a diatonic letter
+ * (0..6 = C..B) plus a chromatic alteration (-2 double-flat .. +2 double-sharp).
+ * Mirrors the letter/alter half of the pitch module's `Note` without an octave.
+ *
+ * @category Chords
+ */
+type PitchSpelling = {
+    letter: number;
+    alter: number;
+};
+/**
+ * A chord expressed as a root pitch class plus semitone offsets.
+ *
+ * `intervals` is what the chord sounds and `quality` is what it is called. The
+ * two are not equally expressive: a chart writes any set of alterations over a
+ * base, while {@link ChordQuality} is a closed list of names, so `quality` is a
+ * *derived* label — the name that fits the chord exactly, or else the nearest
+ * name inside it (see {@link chordSpecQuality}). Read the structure with
+ * {@link chordSpecOf} rather than the name when the alterations matter; that is
+ * also what {@link formatChordSymbol} does, so a chord no name covers still
+ * writes itself out in full.
+ *
+ * `rootSpelling`/`bassSpelling` are optional enharmonic hints recorded by
+ * parsers (e.g. `parseChordSymbol('Bb7')`) so formatters can reproduce the
+ * original spelling instead of defaulting to sharps. Consumers may ignore
+ * them; a hint is only trusted when its pitch class still matches the
+ * corresponding `rootPc`/`bassPc`.
+ *
+ * `toneSpellings` is the same kind of hint for the tones themselves, one
+ * spelling per entry in `intervals`. It exists for the chords whose letters do
+ * not follow from stacking thirds: an augmented sixth is ten semitones like a
+ * minor seventh but is five letters above its root rather than six, and no
+ * {@link ChordQuality} can say so. Builders that know better attach it, and
+ * {@link spellChordFromRoot} reads the letter distances back out of it; a hint
+ * is trusted as a whole or not at all, and only while every spelling still
+ * names the pitch class its interval names.
+ *
+ * @category Chords
+ */
+type Chord = {
+    rootPc: number;
+    quality: ChordQuality;
+    intervals: number[];
+    bassPc?: number;
+    rootSpelling?: PitchSpelling;
+    bassSpelling?: PitchSpelling;
+    toneSpellings?: PitchSpelling[];
+};
+/**
+ * A chord positioned in time: a root pitch class and quality placed at a beat,
+ * with optional harmonic-analysis hints. Serves as the neutral exchange record
+ * between progression generators and timeline analysers.
+ *
+ * @category Composition
+ */
+type ChordSpan = {
+    rootPc: number;
+    quality: ChordQuality;
+    startBeat: number;
+    bassPc?: number;
+    /**
+     * Semitone offsets from the root, for a chord the {@link ChordQuality} union
+     * cannot name exactly. Omitted for a standard chord: the template is then
+     * derived from `quality`, which is what every producer and consumer did
+     * before the field existed. Read a span with {@link chordFromSpan} so either
+     * case yields the same chord.
+     */
+    intervals?: number[];
+    /** 1-based scale degree of the chord root, when known. */
+    degree?: number;
+    /** True when the chord is a secondary dominant tonicizing another degree. */
+    secondaryDominant?: boolean;
+};
+/**
+ * A chord occupying a half-open beat span `[startBeat, endBeat)`.
+ *
+ * The exchange record between anything that lays chords out in time — a
+ * timeline analysis, a bass-line plan, an accompaniment generator — so those
+ * surfaces share one definition instead of agreeing by coincidence.
+ *
+ * @category Composition
+ */
+type ChordSegment = {
+    startBeat: number;
+    endBeat: number;
+    chord: Chord;
+};
+/**
+ * All chord qualities the builder understands, in declaration order.
+ *
+ * The order is stable but carries no meaning: it is neither alphabetical nor
+ * sorted by template size. {@link detectChord} uses it as its final tie-break,
+ * so it is part of the observable behaviour and does not get reshuffled
+ * casually — but do not read it as a ranking.
+ *
+ * @category Chords
+ */
+declare function chordQualities(): ChordQuality[];
+/**
+ * Build a chord rooted on a diatonic scale degree.
+ *
+ * The root pitch class is the degree's diatonic pitch class in `key`; the
+ * quality's interval template is attached unchanged. Degrees beyond the scale
+ * length wrap around, so degree 8 of a heptatonic scale is its degree 1.
+ *
+ * @param degree 1-based scale degree of the chord root: 1 is the tonic.
+ * @param ext Chord quality to apply.
+ * @param key Key context supplying the diatonic root, as a key name, a
+ *   key/scale, or a `Key`.
+ * @returns The constructed chord.
+ * @throws If `degree` is not a positive integer, or `ext` is not a known
+ *   quality.
+ *
+ * @category Chords
+ */
+declare function chordFromDegree(degree: number, ext: ChordQuality, key: KeyLike): Chord;
+/**
+ * Build a chord from an explicit root pitch class and quality.
+ *
+ * @param rootPc Root pitch class (0..11).
+ * @param quality Chord quality supplying the interval template.
+ * @param bassPc Optional slash-chord bass pitch class.
+ * @returns The constructed chord.
+ *
+ * @example
+ * ```ts
+ * import { makeChord } from '@libraz/libcantus';
+ * const cmaj7 = makeChord(0, 'maj7');
+ * // { rootPc: 0, quality: 'maj7', intervals: [0, 4, 7, 11] }
+ * ```
+ *
+ * @category Chords
+ */
+declare function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord;
+/**
+ * Build a chord from a {@link ChordSpec}.
+ *
+ * The structural way in, for the chords a quality name cannot reach: the tones
+ * come from the spec, and `quality` is the name that fits it, or the nearest
+ * name when none does. A chord built this way is an ordinary {@link Chord} —
+ * every consumer reads its `intervals` as before, and
+ * {@link formatChordSymbol} writes the alterations back out.
+ *
+ * @param spec The chord spec; its `rootPc`/`bassPc` become the chord's.
+ * @returns The constructed chord.
+ * @throws If any part of the spec is not one the model defines.
+ *
+ * @example
+ * ```ts
+ * import { chordFromSpec } from '@libraz/libcantus';
+ * chordFromSpec({
+ *   rootPc: 0,
+ *   base: 'maj',
+ *   seventh: 'maj7',
+ *   alterations: [{ degree: 11, alter: 1 }],
+ *   additions: [],
+ *   omissions: [],
+ * });
+ * // { rootPc: 0, quality: 'maj7#11', intervals: [0, 4, 7, 11, 18] }
+ * ```
+ *
+ * @category Chords
+ */
+declare function chordFromSpec(spec: ChordSpec): Chord;
+/**
+ * Read a chord structurally: which base, seventh, alterations and omissions it
+ * is made of.
+ *
+ * The reading comes from the tones themselves, so it describes a chord whatever
+ * built it — a parsed symbol, a detected pitch set, a span carrying a template
+ * no name covers. Only a template with no structural reading at all falls back
+ * to the one its `quality` names.
+ *
+ * @param chord The chord to read.
+ * @returns The spec, carrying the chord's own root and slash bass.
+ * @throws If the chord's template has no reading and its quality is unknown.
+ *
+ * @example
+ * ```ts
+ * import { chordSpecOf, parseChordSymbol } from '@libraz/libcantus';
+ * chordSpecOf(parseChordSymbol('C7(b9,#11)')).alterations;
+ * // [{ degree: 9, alter: -1 }, { degree: 11, alter: 1 }]
+ * ```
+ *
+ * @category Chords
+ */
+declare function chordSpecOf(chord: Chord): ChordSpec;
+/**
+ * Read a {@link ChordSpan} as a chord.
+ *
+ * The canonical way to cross from a span to a chord. A span carrying no
+ * `intervals` yields exactly the chord {@link makeChord} builds from its root,
+ * quality and bass; a span carrying an explicit template keeps it, so a color
+ * tone the {@link ChordQuality} union cannot name survives the trip through a
+ * progression, a timeline, or a generator. The template is copied, so the
+ * chord and the span never share an array.
+ *
+ * @param span The span to read.
+ * @returns The chord the span describes.
+ * @throws If the span's root, bass or quality is invalid, or its `intervals`
+ *   are not a non-empty array of integer semitone offsets.
+ *
+ * @example
+ * ```ts
+ * import { chordFromSpan } from '@libraz/libcantus';
+ * chordFromSpan({ rootPc: 0, quality: 'maj7', startBeat: 0 });
+ * // { rootPc: 0, quality: 'maj7', intervals: [0, 4, 7, 11] }
+ * chordFromSpan({ rootPc: 0, quality: 'maj7', startBeat: 0, intervals: [0, 4, 11, 18] });
+ * // the same span with a fifth-less, #11 voicing the quality cannot name
+ * ```
+ *
+ * @category Composition
+ */
+declare function chordFromSpan(span: ChordSpan): Chord;
+/**
+ * Place a chord at a beat as a {@link ChordSpan}.
+ *
+ * The interval template is recorded only when it departs from the one the
+ * chord's quality names, so a span built from a standard chord carries the
+ * same fields it always did while a custom template is not lost.
+ *
+ * @param chord The chord to place.
+ * @param startBeat Beat the chord starts on.
+ * @returns The span describing that chord at that beat.
+ * @throws If `startBeat` is not finite, or the chord's quality is unknown.
+ *
+ * @example
+ * ```ts
+ * import { makeChord, spanFromChord } from '@libraz/libcantus';
+ * spanFromChord(makeChord(0, 'maj7'), 4);
+ * // { rootPc: 0, quality: 'maj7', startBeat: 4 } — no intervals for a standard chord
+ * ```
+ *
+ * @category Composition
+ */
+declare function spanFromChord(chord: Chord, startBeat: number): ChordSpan;
+/**
+ * Transpose a chord by a number of semitones.
+ *
+ * The interval template is carried over untouched, so a chord whose intervals
+ * were customised keeps them, and a slash bass moves with the root. Enharmonic
+ * spelling hints are dropped rather than shifted: the letter a transposed root
+ * should take depends on the destination key, which a semitone count does not
+ * carry. Pass the result through {@link spellChord} to respell it.
+ *
+ * @param chord The chord to transpose.
+ * @param semitones The signed semitone offset.
+ * @returns The transposed chord.
+ * @throws If `semitones` is not finite.
+ *
+ * @example
+ * ```ts
+ * import { formatChordSymbol, parseChordSymbol, transposeChord } from '@libraz/libcantus';
+ * formatChordSymbol(transposeChord(parseChordSymbol('C/G'), 2)); // 'D/A'
+ * ```
+ *
+ * @category Chords
+ */
+declare function transposeChord(chord: Chord, semitones: number): Chord;
+/**
+ * Get the sorted, deduplicated pitch classes of a chord.
+ *
+ * A slash bass is one of them: `F/G` sounds a G, the voicers put it in the
+ * bass, and a set that omitted it would not re-detect as the chord it came
+ * from. Pass `includeBass: false` to enumerate the interval template alone.
+ *
+ * @param chord The chord to enumerate.
+ * @param opts Set `includeBass: false` to omit a slash bass.
+ * @returns The chord's pitch classes, sorted ascending in [0, 11].
+ *
+ * @example
+ * ```ts
+ * import { makeChord, chordPitchClasses } from '@libraz/libcantus';
+ * chordPitchClasses(makeChord(0, 'maj7')); // [0, 4, 7, 11]
+ * chordPitchClasses(makeChord(5, 'maj', 7)); // [0, 5, 7, 9] — F/G, G included
+ * ```
+ *
+ * @category Chords
+ */
+declare function chordPitchClasses(chord: Chord, opts?: {
+    includeBass?: boolean;
+}): number[];
+/**
+ * A pitch's interval class above the chord root, in [0, 11].
+ *
+ * The shared reading of "where does this pitch sit in the chord", used by the
+ * safety evaluator and the voice analyser alike so they cannot disagree.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param chord The chord providing the root reference.
+ * @returns The interval class above the root.
+ * @category Chords
+ */
+declare function intervalAboveRoot(pitch: number, chord: Chord): number;
+/**
+ * Whether a pitch is one of a chord's tones, ignoring octave.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param chord The chord, or null for no sounding harmony.
+ * @returns True when the pitch class belongs to the chord.
+ * @category Chords
+ */
+declare function isChordMember(pitch: number, chord: Chord | null): boolean;
+/**
+ * Determine a pitch's harmonic role within a chord.
+ *
+ * The role is derived from the pitch's interval above the chord root, reduced
+ * modulo 12. A major sixth (9) reads as a `sixth` for sixth chords but as a
+ * `seventh` for a diminished-seventh chord; ninths and other tensions have no
+ * basic role and return null.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param chord The chord providing the root reference.
+ * @returns The chord-tone role, or null if the pitch has no basic role.
+ *
+ * @category Chords
+ */
+declare function chordToneRole(pitch: number, chord: Chord): ChordToneRole | null;
+/**
+ * Build the diatonic triad rooted on a scale degree by stacking scale thirds.
+ *
+ * Unlike {@link chordFromDegree}, the chord quality is derived from the scale
+ * rather than supplied, so degrees yield their scale-correct triads (e.g. a
+ * diminished triad on the leading tone of a major key).
+ *
+ * @param degree 1-based scale degree of the chord root: 1 is the tonic.
+ * @param key Key/scale context, as a key name, a key/scale, or a `Key`.
+ * @returns The diatonic triad.
+ * @throws If the scale is not heptatonic. Stacking thirds means skipping every
+ *   other degree, which only lands on a triad when there are seven of them, so
+ *   the pentatonic, blues, whole-tone, octatonic and chromatic scales have no
+ *   diatonic triad; use {@link chordFromDegree} with an explicit quality there.
+ *
+ * @example
+ * ```ts
+ * import { majorKey, diatonicTriad } from '@libraz/libcantus';
+ * const tonic = diatonicTriad(1, majorKey(0)); // C major triad (degree 1 of C major)
+ * ```
+ *
+ * @category Chords
+ */
+declare function diatonicTriad(degree: number, key: KeyLike): Chord;
+/**
+ * Build the diatonic seventh chord rooted on a scale degree.
+ *
+ * @param degree 1-based scale degree of the chord root: 1 is the tonic.
+ * @param key Key/scale context, as a key name, a key/scale, or a `Key`.
+ * @returns The diatonic seventh chord.
+ * @throws If the scale is not heptatonic, for the reason given on
+ *   {@link diatonicTriad}.
+ *
+ * @category Chords
+ */
+declare function diatonicSeventh(degree: number, key: KeyLike): Chord;
+
+/**
+ * Style policy: `strict` counterpoint vs. `pop` voice leading.
+ *
+ * A profile says two things. It sets the severity of each reason
+ * {@link evaluateSafety} finds, which decides what is rejected outright, and it
+ * carries the {@link ProfileWeights} that rank whatever survives — because most
+ * of what separates the two styles is preference rather than prohibition.
+ *
+ * @category Arrangement & Analysis
+ */
+type SafetyProfile = 'strict' | 'pop';
+/**
+ * How a profile ranks the candidates its severity table has let through.
+ *
+ * Each field is a score contribution, added when the situation it names occurs;
+ * a negative value is a penalty. The scale is arbitrary but shared, so only the
+ * relative sizes matter. Nothing here can make an unsafe pitch usable: rejection
+ * is the severity table's business, and these weights only order what is left.
+ *
+ * @category Arrangement & Analysis
+ */
+type ProfileWeights = {
+    /** A third or a sixth against the other voice. */
+    imperfectConsonance: number;
+    /** A unison, fifth or octave against the other voice. */
+    perfectConsonance: number;
+    /** A second, seventh or tritone against the other voice. */
+    dissonance: number;
+    /** The candidate belongs to the sounding chord. */
+    chordTone: number;
+    /** The two voices move in opposite directions. */
+    contraryMotion: number;
+    /** One voice holds while the other moves. */
+    obliqueMotion: number;
+    /** Both voices move the same way into a different interval. */
+    similarMotion: number;
+    /** Both voices move the same way, keeping the same imperfect consonance. */
+    parallelImperfect: number;
+    /** The candidate is a step from the previous note of its own line. */
+    stepwise: number;
+    /** Per semitone of melodic movement, so a leap costs more than a step. */
+    melodicDistance: number;
+    /** The move is a leap strict counterpoint forbids outright. */
+    forbiddenLeap: number;
+    /** Per semitone away from the centre of the line's register. */
+    registerDrift: number;
+};
+/**
+ * The weight table each profile ranks candidates by.
+ *
+ * `strict` states the sixteenth-century preferences: contrary motion is worth
+ * seeking, similar motion is worth avoiding, imperfect consonances carry the
+ * line, and a run of parallel thirds earns nothing. `pop` inverts two of those.
+ * Parallel thirds and sixths are the harmony line an arranger writes on purpose,
+ * a pedal or a held unison under a moving lead is a texture rather than a fault,
+ * and similar motion is simply how two parts often move together — while a bass
+ * moving against the lead is still worth preferring where it is available.
+ *
+ * @category Arrangement & Analysis
+ */
+declare const PROFILE_WEIGHTS: Readonly<Record<SafetyProfile, Readonly<ProfileWeights>>>;
+/**
+ * Resolve a profile to the weights that rank its candidates, with per-field
+ * overrides applied on top.
+ *
+ * @param profile The profile whose table to start from.
+ * @param overrides Fields to replace; anything absent keeps the profile's value.
+ * @returns The complete weight table to score with.
+ * @throws If `profile` is not one of the profile names
+ *   ({@link InvalidInputError}). A misspelled profile scored under a default
+ *   table would rank candidates by a style the caller did not ask for.
+ * @example
+ * ```ts
+ * import { profileWeights } from '@libraz/libcantus';
+ * profileWeights('pop', { parallelImperfect: 4 }).contraryMotion; // 1.5 — the rest is untouched
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function profileWeights(profile: SafetyProfile, overrides?: Partial<ProfileWeights>): ProfileWeights;
+/**
+ * Overall placeability verdict for a candidate pitch.
+ *
+ * @category Arrangement & Analysis
+ */
+declare enum NoteSafety {
+    Safe = 0,
+    Warning = 1,
+    Dissonant = 2
+}
+/**
+ * Bit flags describing why a pitch received its verdict.
+ *
+ * @category Arrangement & Analysis
+ */
+declare enum ReasonFlag {
+    ChordTone = 1,
+    Tension = 2,
+    AvoidNote = 4,
+    ScaleTone = 8,
+    NonScale = 16,
+    OutOfRange = 32,
+    Tritone = 64,
+    LargeLeap = 128,
+    MinorSecond = 256,
+    MajorSeventh = 512,
+    VerticalDissonance = 1024,
+    ParallelPerfect = 2048,
+    HiddenParallel = 4096,
+    VoiceCrossing = 8192,
+    Suspension = 16384,
+    NeedsResolution = 32768,
+    MelodicTritone = 65536
+}
+/**
+ * A neighbouring voice's current and previous pitch.
+ *
+ * @category Arrangement & Analysis
+ */
+type VoiceSnapshot = {
+    pitch: number;
+    prevPitch?: number;
+};
+/**
+ * Everything needed to evaluate one candidate pitch.
+ *
+ * @category Arrangement & Analysis
+ */
+type SafetyQuery = {
+    profile: SafetyProfile;
+    candidatePitch: number;
+    prevPitch?: number;
+    chord: Chord | null;
+    key: KeyScale;
+    otherVoices: VoiceSnapshot[];
+    strongBeat: boolean;
+    vocalLow?: number;
+    vocalHigh?: number;
+};
+/**
+ * The verdict, reason flags, and optional resolution guidance.
+ *
+ * @category Arrangement & Analysis
+ */
+type SafetyResult = {
+    safety: NoteSafety;
+    reasons: number;
+    resolveTo?: number;
+    suggestions?: number[];
+    rationale?: string;
+};
+/**
+ * Evaluate the safety of placing a candidate pitch in a voice.
+ *
+ * Reasons are merged from harmonic context (chord tone / tension / avoid / scale)
+ * and counterpoint (vertical dissonance, parallels, voice crossing). The `strict`
+ * profile treats avoid notes and parallels as dissonant; `pop` treats them as
+ * warnings. The final verdict is the worst severity among the reasons.
+ *
+ * @param q The candidate and its harmonic/voice-leading context.
+ * @returns The verdict, reason bitmask, and optional resolution guidance.
+ * @throws If the profile is not one of the profile names, or if any pitch in
+ *   the query is not a MIDI pitch in 0..127 ({@link InvalidInputError}).
+ * @example
+ * ```ts
+ * import { evaluateSafety, makeChord, majorKey, NoteSafety } from '@libraz/libcantus';
+ * const result = evaluateSafety({
+ *   profile: 'pop',
+ *   candidatePitch: 60, // C over a C major chord
+ *   chord: makeChord(0, 'maj'),
+ *   key: majorKey(0),
+ *   otherVoices: [],
+ *   strongBeat: true,
+ * });
+ * result.safety === NoteSafety.Safe; // true — C is a chord tone
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function evaluateSafety(q: SafetyQuery, opts?: EvaluateSafetyOptions): SafetyResult;
+/**
+ * Options for {@link evaluateSafety}.
+ *
+ * @category Arrangement & Analysis
+ */
+type EvaluateSafetyOptions = {
+    /**
+     * Whether to search for safe replacement pitches when the verdict is not
+     * safe. Turning it off skips up to two dozen extra evaluations per rejected
+     * pitch, which is worth doing when only the verdict is wanted.
+     *
+     * @defaultValue true
+     */
+    suggestions?: boolean;
+};
+/**
+ * Enumerate placeable pitches in a range, chord tones first, descending.
+ *
+ * @param q The safety context minus the candidate pitch.
+ * @param pitchLow Lowest MIDI pitch to consider (inclusive).
+ * @param pitchHigh Highest MIDI pitch to consider (inclusive).
+ * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
+ * @throws If either bound is not a MIDI pitch in 0..127, reversed, or exceeds
+ *   the generation budget, or if the context names an unknown profile.
+ * @example
+ * ```ts
+ * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';
+ * const pitches = enumerateSafePitches(
+ *   { profile: 'pop', chord: makeChord(0, 'maj'), key: majorKey(0), otherVoices: [], strongBeat: true },
+ *   60,
+ *   72,
+ * );
+ * pitches; // placeable pitches in [60, 72], chord tones first, each group descending
+ * ```
+ * @category Arrangement & Analysis
+ */
+declare function enumerateSafePitches(q: Omit<SafetyQuery, 'candidatePitch'>, pitchLow: number, pitchHigh: number): number[];
+
+/**
+ * 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.
+ *
+ * The root and the slash bass are note names, so they are read and written in
+ * whichever notation system the caller names — a German chart's `H7`, `As7` and
+ * `Ges/B` included. Unlike a note name, a chord symbol is never attributed to a
+ * system on its own: German `B` is a B flat and English `B` a B natural, and a
+ * symbol carries no `dur`/`moll` word to break the tie, so the most common
+ * symbol in the vocabulary would otherwise change chord with the source it came
+ * from. With no system given a symbol is English.
+ */
+
+/**
+ * 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 root and bass are read in `system`, so a German chart's `H7`, `As7` and
+ * `Ges/B` are read by asking for `'german'`. The system is never inferred: with
+ * none given the symbol is English, where `B` is the B natural and `H` no note
+ * at all. Case carries nothing in a chord symbol — unlike a German key name,
+ * where the case of the tonic is the mode — so the quality suffix alone says
+ * major or minor. Where a German root's flat suffix could equally open the
+ * quality, the longest root that leaves a known quality behind wins: `Asus4` is
+ * an A suspended chord and `Assus4` the A flat one.
+ *
+ * The quality suffix is read structurally when no name covers it, so a chart's
+ * bracketed tensions parse as readily as the names do: `Cmaj7(#11)`,
+ * `C7(b9,#11)`, `C7(13)`, `Csus4(add9)`, `C-Δ9`, `C6/9(#11)`. A `/` between two
+ * figures separates them as it does inside brackets, which is what the sixth
+ * and ninth of a `6/9` are. Such a chord carries the tones it names and reports
+ * the nearest quality name (see {@link chordSpecQuality}); read
+ * {@link chordSpecOf} for its structure.
+ *
+ * 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.
+ * @param opts `system` reads the root and bass in that notation system instead
+ *   of English.
+ * @returns The parsed chord.
+ * @throws If the root or quality is not recognized in that system. Use
+ *   {@link tryParseChordSymbol} where failure is ordinary, such as a chord
+ *   field read on every keystroke.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, formatChordSymbol } from '@libraz/libcantus';
+ * const c = parseChordSymbol('Bbmaj7');
+ * formatChordSymbol(c); // 'Bbmaj7' — flat spelling is preserved on round-trip
+ * parseChordSymbol('H7', { system: 'german' }).rootPc; // 11 — the B natural
+ * parseChordSymbol('B', { system: 'german' }).rootPc; // 10 — the German B flat
+ * ```
+ * @category Chords
+ */
+declare function parseChordSymbol(text: string, opts?: NoteNameOptions): Chord;
+/**
+ * Parse a lead-sheet chord symbol, reporting failure instead of throwing it.
+ *
+ * The same reading as {@link parseChordSymbol} — that function is this one with
+ * its error thrown — for the callers where a symbol that does not parse yet is
+ * the normal state of the input rather than a fault: a chord field says what is
+ * wrong with what has been typed so far, and does not need a `try` around every
+ * keystroke to do it.
+ *
+ * @param text The chord symbol text.
+ * @param opts `system` reads the root and bass in that notation system instead
+ *   of English.
+ * @returns The chord, or the error explaining why the text is not one.
+ * @example
+ * ```ts
+ * import { tryParseChordSymbol } from '@libraz/libcantus';
+ * const result = tryParseChordSymbol('Cmaj7(#11)');
+ * result.ok ? result.value.intervals : result.error.message;
+ * ```
+ * @category Chords
+ */
+declare function tryParseChordSymbol(text: string, opts?: NoteNameOptions): ParseResult<Chord>;
+/**
+ * Anything that names a chord: a chord symbol, plain chord data, or a value
+ * that serializes to chord data such as the `Chord` class.
+ *
+ * @category Chords
+ */
+type ChordLike = string | Chord | {
+    /** The chord data this value stands for. */
+    toJSON(): Chord;
+};
+/**
+ * Resolve any chord-shaped value to plain {@link Chord} data.
+ *
+ * The counterpart of {@link toSpelledInterval} for chords: an entry point takes
+ * whatever form the caller has — the symbol a chart holds, the data the chord
+ * module returns, or a `Chord` instance — and gets one shape back. An instance
+ * is accepted through its `toJSON` method rather than by its type, so the
+ * layers below the model can read a class without importing it.
+ *
+ * @param value A chord symbol, plain chord data, or a value whose `toJSON`
+ *   returns chord data.
+ * @returns The validated chord data, with root and bass reduced to pitch
+ *   classes and any spelling hint carried through.
+ * @throws If the value names no chord, or an interval, root, or bass is not a
+ *   finite number.
+ * @example
+ * ```ts
+ * import { toChordData } from '@libraz/libcantus';
+ * toChordData('Cmaj7').intervals; // [0, 4, 7, 11]
+ * toChordData({ rootPc: 0, quality: 'maj', intervals: [0, 4, 7] }).rootPc; // 0
+ * ```
+ * @category Chords
+ */
+declare function toChordData(value: ChordLike): Chord;
+/**
+ * How a chord symbol is written: in which notation system, and on which side of
+ * the enharmonic fence.
+ *
+ * @category Chords
+ */
+type ChordSymbolOptions = NoteNameOptions & {
+    /**
+     * Prefer flat spellings over sharps for an altered root or bass; passing
+     * either `true` or `false` overrides any spelling hint the chord carries.
+     */
+    flats?: boolean;
+};
+/**
+ * Format a {@link Chord} as a lead-sheet chord symbol.
+ *
+ * The inverse of {@link parseChordSymbol} in every notation system: each
+ * quality maps to one canonical suffix spelling, the root and bass are written
+ * in `system`, and a slash bass is appended only when it differs from the root.
+ * Every symbol written here reads back through {@link parseChordSymbol} as the
+ * same root, sounding bass and tones — whatever combination of tensions the
+ * chord carries, and whether or not a quality name covers it.
+ * 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.
+ *
+ * The suffix is written from the chord's own tones (see {@link chordSpecOf}),
+ * not from its quality name, so a chord carrying alterations no name covers is
+ * written out in full — `C7(b9,#11)` — rather than under the nearest name. A
+ * tone the chord leaves out is not written: the symbol names the harmony, so a
+ * fifth-less dominant is still `C7`.
+ *
+ * @param chord The chord to format, as a chord symbol, chord data, or a
+ *   `Chord`.
+ * @param opts `system` writes the root and bass in that notation system instead
+ *   of English; `flats` overrides the spelling hints, as
+ *   {@link ChordSymbolOptions} describes.
+ * @returns The chord symbol text.
+ * @example
+ * ```ts
+ * import { makeChord, formatChordSymbol, parseChordSymbol } from '@libraz/libcantus';
+ * formatChordSymbol(makeChord(0, 'min7')); // 'Cm7'
+ * formatChordSymbol(parseChordSymbol('Bb7'), { system: 'german' }); // 'B7'
+ * formatChordSymbol(parseChordSymbol('B7'), { system: 'german' }); // 'H7'
+ * ```
+ * @category Chords
+ */
+declare function formatChordSymbol(chord: ChordLike, opts?: ChordSymbolOptions): string;
+/**
+ * Transpose a chord symbol by a number of semitones.
+ *
+ * The symbol is read in the same system it is written back in, so a German
+ * chart stays German across the transposition.
+ *
+ * @param text The chord symbol text.
+ * @param semitones Signed semitone offset to apply to the root and bass.
+ * @param opts Options for reading and writing the symbol; see
+ *   {@link ChordSymbolOptions}.
+ * @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'
+ * transposeChordSymbol('H7', 1, { system: 'german' }); // 'C7'
+ * ```
+ * @category Chords
+ */
+declare function transposeChordSymbol(text: string, semitones: number, opts?: ChordSymbolOptions): string;
+
+export { toChordData as $, type Alteration as A, diatonicTriad as B, type ChordBase as C, dominantKeyOf as D, type EvaluateSafetyOptions as E, enharmonicKeyOf as F, enumerateSafePitches as G, evaluateSafety as H, formatChordSymbol as I, intervalAboveRoot as J, type KeyLike as K, isChordMember as L, keyRelationBetween as M, NoteSafety as N, makeChord as O, PROFILE_WEIGHTS as P, parallelKeyOf as Q, ReasonFlag as R, type SafetyProfile as S, parseChordSymbol as T, profileWeights as U, type VoiceSnapshot as V, relatedKeysOf as W, relativeKeyOf as X, spanFromChord as Y, spelledKeyOf as Z, subdominantKeyOf as _, type AlteredDegree as a, toKeyScale as a0, transposeChord as a1, transposeChordSymbol as a2, tryParseChordSymbol as a3, type Chord as b, type ChordLike as c, type ChordQuality as d, type ChordSegment as e, type ChordSeventh as f, type ChordSpan as g, type ChordSpec as h, type ChordSymbolOptions as i, type ChordToneRole as j, type KeyRelation as k, type PitchSpelling as l, type ProfileWeights as m, type SafetyQuery as n, type SafetyResult as o, type SpelledKey as p, chordFromDegree as q, chordFromSpan as r, chordFromSpec as s, chordPitchClasses as t, chordQualities as u, chordSpecIntervals as v, chordSpecOf as w, chordSpecQuality as x, chordToneRole as y, diatonicSeventh as z };