@libraz/libcantus 0.9.4 → 1.0.0

package/dist/index-B9MNZboQ.d.ts

@@ -0,0 +1,770 @@
+/**
+ * Every playing technique a note can carry, in declaration order.
+ *
+ * These name intent, not a rendering: how `flam` becomes a grace stroke or
+ * `slide` becomes pitch bend is the caller's decision, because it depends on the
+ * sampler, key switches, and controller layout in use. Carrying the intent
+ * instead of a baked note pair is what lets any phrase be flammed, ghosted, or
+ * muted without the generator having to know how it will be voiced.
+ *
+ * @category Core
+ */
+declare const ARTICULATIONS: readonly ["accent", "ghost", "staccato", "legato", "slide", "hammer", "mute", "flam", "drag", "roll", "choke", "open"];
+/**
+ * How a note is played, independent of its pitch and length.
+ *
+ * @category Core
+ */
+type Articulation = (typeof ARTICULATIONS)[number];
+
+/**
+ * A key/scale definition anchored on a root pitch class.
+ *
+ * `modeMask12` is a 12-bit mask where bit `n` set means the pitch class
+ * `(rootPc + n) % 12` belongs to the scale. Bit 0 (the root) is always set;
+ * {@link maskFromOffsets} enforces this so the root is always a scale tone.
+ *
+ * @category Core
+ */
+type KeyScale = {
+    rootPc: number;
+    modeMask12: number;
+};
+/**
+ * A single sounding note on a beat-indexed timeline: an absolute MIDI pitch, an
+ * onset and duration measured in quarter-note beats, and an optional MIDI
+ * velocity. This is the library-wide interchange shape for note events read
+ * from or written to a DAW/MIDI track; the harmonizer's `MelodyNote` and the
+ * analysis `VoiceNote` are specializations of it.
+ *
+ * @category Core
+ */
+type NoteEvent = {
+    /** MIDI pitch in [0, 127] (middle C = 60). */
+    pitch: number;
+    /**
+     * Onset in quarter-note beats, absolute from the start of the timeline, and
+     * unbounded below: beat 0 is the first downbeat, so a pickup sounds before it
+     * and is written at a negative onset, in the bar numbered -1. Shifting the
+     * whole timeline a bar later instead would move every strong beat with it,
+     * and the upbeat would then be analyzed as a downbeat. A caller that knows
+     * how long its pickup is narrows the bound with
+     * {@link NoteEventAssertOptions.minStartBeat}.
+     */
+    startBeat: number;
+    /** Duration in quarter-note beats. */
+    durationBeat: number;
+    /** MIDI velocity in [0, 127], when known. */
+    velocity?: number;
+    /**
+     * How the note is played, when the writer had an intent to record. The
+     * library carries the intent only: turning `slide` into pitch bend or `ghost`
+     * into a velocity floor depends on the instrument and controller layout at
+     * the far end, so it is the reader's decision. Optional, so a reader that
+     * knows nothing of articulation reads the note exactly as before.
+     */
+    articulation?: Articulation;
+};
+
+/**
+ * The library's error taxonomy.
+ *
+ * Every failure this library raises falls into one of three kinds, and the kind
+ * decides what a caller can do about it. Batch-voicing a lead sheet, for
+ * instance, has to tell "fix the input" apart from "loosen the constraints",
+ * and a message string is not a contract.
+ *
+ * The classes extend the built-in error types a caller would otherwise catch —
+ * a rejected argument is still a `RangeError` — so the `code` narrows an
+ * existing category rather than replacing it.
+ */
+/**
+ * What kind of failure an error reports.
+ *
+ * - `INVALID_INPUT`: an argument is malformed or out of range. The caller's
+ *   input must change.
+ * - `NO_SOLUTION`: the input is valid but nothing satisfies the constraints.
+ *   The constraints must change, or the failure must be accepted.
+ * - `BUDGET_EXCEEDED`: the requested work is larger than the synchronous
+ *   generation budget. The request must be smaller, or the budget larger.
+ *
+ * @category Core
+ */
+type LibcantusErrorCode = 'INVALID_INPUT' | 'NO_SOLUTION' | 'BUDGET_EXCEEDED';
+/**
+ * Any error this library raises, as a union of its three classes.
+ *
+ * The type a non-throwing entry point reports its failure as: a caller that
+ * holds one of these already knows it carries a {@link LibcantusErrorCode} and
+ * a message worth showing.
+ *
+ * @category Core
+ */
+type LibcantusError = InvalidInputError | NoSolutionError | BudgetExceededError;
+/**
+ * The outcome of a parse that reports failure instead of throwing it.
+ *
+ * A text field is parsed on every keystroke, and most of those keystrokes are
+ * halfway through a valid symbol, so failure is the normal case rather than an
+ * exceptional one. The error travels in the result — not as `null` — because an
+ * input field has to say what is wrong with what was typed.
+ *
+ * @typeParam T The value a successful parse produces.
+ * @category Core
+ * @example
+ * ```ts
+ * import { tryParseChordSymbol } from '@libraz/libcantus';
+ * const result = tryParseChordSymbol('Cmaj');
+ * const label = result.ok ? result.value.quality : result.error.message;
+ * ```
+ */
+type ParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: LibcantusError;
+};
+/**
+ * A rejected argument: malformed, out of range, or naming something unknown.
+ *
+ * @category Core
+ */
+declare class InvalidInputError extends RangeError {
+    readonly code: "INVALID_INPUT";
+    readonly name = "InvalidInputError";
+}
+/**
+ * A valid request with no answer: no voicing fits the given ranges, no chord
+ * matches the pitches, no preset claims the style.
+ *
+ * @category Core
+ */
+declare class NoSolutionError extends Error {
+    readonly code: "NO_SOLUTION";
+    readonly name = "NoSolutionError";
+    /**
+     * Where in a sequence the failure occurred, when the operation was working
+     * through one — the chord index of a progression, say.
+     */
+    readonly at: number | undefined;
+    constructor(message: string, options?: {
+        at?: number;
+    });
+}
+/**
+ * Work that would exceed the synchronous generation budget.
+ *
+ * @category Core
+ */
+declare class BudgetExceededError extends RangeError {
+    readonly code: "BUDGET_EXCEEDED";
+    readonly name = "BudgetExceededError";
+}
+/**
+ * Whether a caught value is one of this library's coded errors.
+ *
+ * @param value The caught value.
+ * @returns True when it carries a {@link LibcantusErrorCode}.
+ * @example
+ * ```ts
+ * import { isLibcantusError, voiceChord, parseChordSymbol } from '@libraz/libcantus';
+ * try {
+ *   voiceChord(parseChordSymbol('C'), { ranges: [] });
+ * } catch (error) {
+ *   if (isLibcantusError(error) && error.code === 'NO_SOLUTION') {
+ *     // loosen the constraints rather than blaming the input
+ *   }
+ * }
+ * ```
+ * @category Core
+ */
+declare function isLibcantusError(value: unknown): value is InvalidInputError | NoSolutionError | BudgetExceededError;
+
+/**
+ * Note-name notation systems.
+ *
+ * A pitch has one identity but many written names: the note an English score
+ * calls `G#` is `gis` in German, `嬰ト` in Japanese and `sol diesis` in Italian.
+ * This module holds each system's table — letters, accidental affixes and mode
+ * words — so a name can be read and written in the system a source actually
+ * uses, and so a name of unknown origin can be attributed to one.
+ *
+ * The tables live together because attribution needs them together: `B` is a B
+ * natural in English but a B flat in German, and only a table that knows both
+ * can say so.
+ */
+
+/**
+ * A system of written note names.
+ *
+ * - `english`: C D E F G A B, `#` sharp and `b` flat (`C#`, `Bb`, `F##`).
+ * - `german`: C D E F G A H, `-is` sharp and `-es` flat (`cis`, `des`), with B
+ *   for B flat and H for B natural.
+ * - `japanese`: the katakana 音名 ハ ニ ホ ヘ ト イ ロ, prefixed 嬰 sharp and
+ *   変 flat.
+ * - `italian`: the solfège syllables do re mi fa sol la si, followed by
+ *   `diesis` or `bemolle`.
+ * - `fixedDo`: the same syllables read as fixed-do note names; identical to
+ *   `italian`, and named separately because callers ask for it by that name.
+ *
+ * @category Pitch & Intervals
+ */
+type NoteNameSystem = 'english' | 'german' | 'japanese' | 'italian' | 'fixedDo';
+/**
+ * Which notation system to read or write a name in.
+ *
+ * @category Pitch & Intervals
+ */
+type NoteNameOptions = {
+    /**
+     * The system. Omitted on parsing, the system is detected from the name
+     * itself; omitted on formatting, the name is written in English.
+     */
+    system?: NoteNameSystem;
+};
+/**
+ * A key named the way a score names it: a spelled tonic and a mode.
+ *
+ * This is what a key *name* carries. It is deliberately not a key/scale: a name
+ * fixes the tonic's spelling and says major or minor, and nothing more.
+ *
+ * @category Scales
+ */
+type KeyName = {
+    /** The spelled tonic, without an octave. */
+    tonic: Note;
+    /** Which of the two modes the name gives. */
+    mode: 'major' | 'minor';
+};
+/**
+ * The notation system a note name or key name is written in.
+ *
+ * A name several systems could read is attributed to the first of English,
+ * German, Japanese, Italian that reads it — so `B` is the English B natural,
+ * and German is chosen only for a name carrying a German-only cue (`H`, an
+ * `-is`/`-es` ending, or `dur`/`moll`). Because the fixed-do syllables are the
+ * Italian ones, detection reports `'italian'` for them; `'fixedDo'` is only ever
+ * a system a caller asks for by name.
+ *
+ * @param text The note name or key name.
+ * @returns The system that reads it.
+ * @throws If no system reads the name, or the name mixes two systems — a German
+ *   tonic under an English mode word, say.
+ * @example
+ * ```ts
+ * import { detectNoteNameSystem } from '@libraz/libcantus';
+ * detectNoteNameSystem('B'); // 'english' — never the German B flat
+ * detectNoteNameSystem('gis moll'); // 'german'
+ * detectNoteNameSystem('嬰ト短調'); // 'japanese'
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function detectNoteNameSystem(text: string): NoteNameSystem;
+
+/**
+ * Pitch spelling: letter-name notes, enharmonic-aware conversion, and spelled
+ * intervals.
+ *
+ * The rest of the library works in pitch classes (0..11), which cannot tell a
+ * G# from an Ab or an augmented fourth from a diminished fifth. This module adds
+ * an explicit spelling layer — a note is a diatonic letter plus a chromatic
+ * alteration — so interval quality (P/M/m/A/d) and enharmonic identity are
+ * preserved.
+ */
+
+/**
+ * A spelled note: a diatonic letter, a chromatic alteration, and an optional
+ * octave.
+ *
+ * - `letter` is 0..6 for C..B.
+ * - `alter` is the number of semitones of alteration: -2 double-flat, -1 flat,
+ *   0 natural, +1 sharp, +2 double-sharp.
+ * - `octave` follows scientific pitch notation (middle C = C4 = MIDI 60). When
+ *   absent, the note denotes a bare pitch class.
+ *
+ * @category Pitch & Intervals
+ */
+type Note = {
+    letter: number;
+    alter: number;
+    octave?: number;
+};
+/**
+ * The quality label of a spelled interval: perfect, major, minor, or one or
+ * more augmentations or diminutions.
+ *
+ * This names how an interval is *spelled*. It is a different notion from
+ * {@link ConsonanceClass}, which classifies how an interval *sounds* against
+ * another voice.
+ *
+ * @see {@link ConsonanceClass}
+ * @category Pitch & Intervals
+ */
+type IntervalQualityLabel = 'P' | 'M' | 'm' | `A${string}` | `d${string}`;
+/**
+ * A spelled interval: a diatonic number, a quality label, and its semitone span.
+ *
+ * @category Pitch & Intervals
+ */
+type SpelledInterval = {
+    /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
+    number: number;
+    /** Quality label: 'P', 'M', 'm', or repeated 'A'/'d' for (multiply) aug/dim. */
+    quality: IntervalQualityLabel;
+    /** Signed semitone distance from the first note to the second. */
+    semitones: number;
+    /**
+     * True when the diatonic letters move down, and absent otherwise — an
+     * ascending interval leaves the key out rather than carrying `false`, so
+     * every producer of this type returns the same object for the same interval.
+     * The flag is not redundant with the sign of the span: a descending unison
+     * spans zero semitones, and a letter can rise while the pitch falls.
+     */
+    descending?: boolean;
+};
+/**
+ * Reduce a MIDI pitch, a bare pitch class, or any signed offset to a pitch
+ * class in [0, 11].
+ *
+ * This is the library's single definition of pitch-class arithmetic: every
+ * layer routes through it so a fractional pitch reduces the same way
+ * everywhere. A non-integral input is rounded to the nearest semitone first, so
+ * a microtonal 60.6 reads as C# rather than C.
+ *
+ * @param value A MIDI pitch, pitch class, or signed semitone offset.
+ * @returns The pitch class in [0, 11].
+ * @example
+ * ```ts
+ * import { pitchClassOf } from '@libraz/libcantus';
+ * pitchClassOf(61); // 1
+ * pitchClassOf(-1); // 11
+ * pitchClassOf(60.6); // 1
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function pitchClassOf(value: number): number;
+/**
+ * Reduce a letter number or letter offset to a diatonic letter in [0, 6]
+ * (0 = C .. 6 = B).
+ *
+ * @param value A letter number or signed letter offset.
+ * @returns The diatonic letter in [0, 6].
+ * @category Pitch & Intervals
+ */
+declare function diatonicLetterOf(value: number): number;
+/**
+ * The pitch class of a diatonic letter with no accidental (C = 0, D = 2, ...).
+ *
+ * @param letter A letter number or signed letter offset; reduced to [0, 6].
+ * @returns The natural pitch class of that letter.
+ * @category Pitch & Intervals
+ */
+declare function naturalPitchClassOf(letter: number): number;
+/**
+ * Parse a note name into a {@link Note}, in any supported notation system.
+ *
+ * English (the default when a name could be read in more than one system)
+ * accepts a letter (case-insensitive) followed by any number of same-direction
+ * accidentals and an optional octave, e.g. `"C"`, `"C#4"`, `"Bb"`, `"F##3"`,
+ * `"Ebb2"`. Both `#` and `x` (double-sharp) are accepted for sharps; `b` for
+ * flats. Mixing sharps and flats (e.g. `"C#b"`) is rejected.
+ *
+ * Without a `system` the name is attributed by {@link detectNoteNameSystem},
+ * which reads a name any two systems could claim as English: `"B"` is the B
+ * natural, never the German B flat. German is chosen only for a German-only
+ * name such as `"H"`, `"fis"` or `"es"`.
+ *
+ * A scientific octave may follow the name in every system (`"gis4"`,
+ * `"嬰ト4"`), which is what makes formatting and parsing exact inverses for an
+ * octave-bearing note.
+ *
+ * @param text The note name.
+ * @param opts `system` reads the name in that notation system instead of
+ *   detecting it.
+ * @returns The parsed note.
+ * @throws If the text is not a valid note in the given (or detected) system.
+ *   Use {@link tryParseNote} where failure is ordinary, such as a note field
+ *   read on every keystroke.
+ * @example
+ * ```ts
+ * import { parseNote, noteToMidi, noteToPitchClass } from '@libraz/libcantus';
+ * noteToMidi(parseNote('C#4')); // 61
+ * noteToPitchClass(parseNote('gis')); // 8 — the German G sharp
+ * noteToPitchClass(parseNote('B', { system: 'german' })); // 10 — the German B flat
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function parseNote(text: string, opts?: NoteNameOptions): Note;
+/**
+ * Parse a note name, reporting failure instead of throwing it.
+ *
+ * The same reading as {@link parseNote} — that function is this one with its
+ * error thrown — for the callers where a name that does not parse yet is the
+ * normal state of the input rather than a fault.
+ *
+ * @param text The note name.
+ * @param opts `system` reads the name in that notation system instead of
+ *   detecting it.
+ * @returns The note, or the error explaining why the text is not one.
+ * @example
+ * ```ts
+ * import { tryParseNote } from '@libraz/libcantus';
+ * const result = tryParseNote('C#4');
+ * result.ok ? result.value.letter : result.error.message;
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function tryParseNote(text: string, opts?: NoteNameOptions): ParseResult<Note>;
+/**
+ * Render a {@link Note} as a note name, in any supported notation system.
+ *
+ * The inverse of {@link parseNote} when both are given the same `system`,
+ * including double accidentals and octaves. Without one, {@link parseNote}
+ * detects the system and reads a bare `B` as the English B natural, so a German
+ * B flat written as `'b'` does not survive a round trip that names no system.
+ *
+ * @param note The note to format.
+ * @param opts `system` writes the name in that notation system instead of
+ *   English.
+ * @returns The note name, including the octave when present.
+ * @example
+ * ```ts
+ * import { formatNote, parseNote } from '@libraz/libcantus';
+ * formatNote(parseNote('C#4')); // 'C#4'
+ * formatNote(parseNote('G#'), { system: 'german' }); // 'gis'
+ * formatNote(parseNote('G#'), { system: 'japanese' }); // '嬰ト'
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function formatNote(note: Note, opts?: NoteNameOptions): string;
+/**
+ * Parse a key name such as `'C major'`, `'gis moll'` or `'嬰ト短調'`.
+ *
+ * The name is a tonic followed by a mode word, in any of the supported
+ * notation systems; German also accepts its hyphenated form (`'gis-Moll'`).
+ * Without a `system` the name is attributed by {@link detectNoteNameSystem},
+ * so a mode word is itself enough to pick one: `'B dur'` is B flat major while
+ * `'B major'` is B major.
+ *
+ * German carries the mode twice, in the word and in the case of the tonic
+ * (`C dur`, `c moll`). When the two disagree the word wins — `'C moll'` is C
+ * minor — because the word is what the writer said and the case only what they
+ * typed. A German name with no mode word is decided by its case alone
+ * (`'gis'` is G sharp minor, `'Gis'` G sharp major); a bare tonic in any other
+ * system names a major key.
+ *
+ * @param text The key name.
+ * @param opts `system` reads the name in that notation system instead of
+ *   detecting it.
+ * @returns The spelled tonic and the mode.
+ * @throws If the text is not a key name in the given (or detected) system, if
+ *   it mixes two systems, or if the tonic carries an octave. Use
+ *   {@link tryParseKeyName} where failure is ordinary, such as a key field read
+ *   on every keystroke.
+ * @example
+ * ```ts
+ * import { formatNote, parseKeyName } from '@libraz/libcantus';
+ * const key = parseKeyName('gis moll');
+ * formatNote(key.tonic); // 'G#'
+ * key.mode; // 'minor'
+ * ```
+ * @category Scales
+ */
+declare function parseKeyName(text: string, opts?: NoteNameOptions): KeyName;
+/**
+ * Parse a key name, reporting failure instead of throwing it.
+ *
+ * The same reading as {@link parseKeyName} — that function is this one with its
+ * error thrown — for the callers where a name that does not parse yet is the
+ * normal state of the input rather than a fault.
+ *
+ * @param text The key name.
+ * @param opts `system` reads the name in that notation system instead of
+ *   detecting it.
+ * @returns The key, or the error explaining why the text is not one.
+ * @example
+ * ```ts
+ * import { tryParseKeyName } from '@libraz/libcantus';
+ * const result = tryParseKeyName('gis moll');
+ * result.ok ? result.value.mode : result.error.message; // 'minor'
+ * ```
+ * @category Scales
+ */
+declare function tryParseKeyName(text: string, opts?: NoteNameOptions): ParseResult<KeyName>;
+/**
+ * Render a spelled tonic and a mode as a key name.
+ *
+ * The inverse of {@link parseKeyName}. German is written the way it is read,
+ * with the mode in the case of the tonic as well as in the word.
+ *
+ * @param key The spelled tonic and mode; any octave on the tonic is dropped,
+ *   since a key has no register.
+ * @param opts `system` writes the name in that notation system instead of
+ *   English.
+ * @returns The key name.
+ * @throws If the tonic or the mode is not valid.
+ * @example
+ * ```ts
+ * import { formatKeyName, parseNote } from '@libraz/libcantus';
+ * formatKeyName({ tonic: parseNote('G#'), mode: 'minor' }); // 'G# minor'
+ * formatKeyName({ tonic: parseNote('G#'), mode: 'minor' }, { system: 'german' }); // 'gis moll'
+ * ```
+ * @category Scales
+ */
+declare function formatKeyName(key: KeyName, opts?: NoteNameOptions): string;
+/**
+ * Pitch class (0..11) of a note, ignoring octave.
+ *
+ * @param note The note.
+ * @returns The pitch class.
+ * @example
+ * ```ts
+ * import { noteToPitchClass, parseNote } from '@libraz/libcantus';
+ * noteToPitchClass(parseNote('Db')); // 1
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function noteToPitchClass(note: Note): number;
+/**
+ * MIDI number of a note (middle C = C4 = 60).
+ *
+ * @param note The note; must carry an octave.
+ * @returns The MIDI number.
+ * @throws If the note has no octave.
+ * @example
+ * ```ts
+ * import { noteToMidi, parseNote } from '@libraz/libcantus';
+ * noteToMidi(parseNote('A4')); // 69
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function noteToMidi(note: Note): number;
+/**
+ * Name a MIDI number as a {@link Note}, choosing sharp or flat spelling.
+ *
+ * The input is rounded to the nearest integer but is not clamped to the MIDI
+ * range 0..127: out-of-range values extrapolate linearly (e.g. `-1` -> `B-2`,
+ * `128` -> `G#9`) and remain an exact inverse of {@link noteToMidi}.
+ *
+ * @param midi The MIDI number.
+ * @param spelling Whether to prefer sharps or flats for black keys.
+ * @returns The spelled note, with octave.
+ * @throws If `spelling` is neither `'sharp'` nor `'flat'`; a name the table does
+ *   not carry would otherwise be spelled as one of them without saying which.
+ * @example
+ * ```ts
+ * import { midiToNote, formatNote } from '@libraz/libcantus';
+ * formatNote(midiToNote(61)); // 'C#4'
+ * formatNote(midiToNote(61, 'flat')); // 'Db4'
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function midiToNote(midi: number, spelling?: 'sharp' | 'flat'): Note;
+/**
+ * Transpose a note by a signed number of semitones, keeping its spelling.
+ *
+ * The letter moves by the diatonic distance of the conventional interval for
+ * that many semitones and the accidental is recomputed for the new letter, so
+ * enharmonic identity survives: `Ab4` up a major second is `Bb4`, not `A#4`, and
+ * the operation is an exact inverse of itself. An octave-less note stays
+ * octave-less.
+ *
+ * A bare semitone count cannot distinguish an augmented fourth from a diminished
+ * fifth; pass `spelling` to override the letter distance when the enharmonic
+ * choice matters.
+ *
+ * @param note The note to transpose.
+ * @param semitones The signed semitone offset.
+ * @param opts `spelling` forces the result onto the sharp or flat side instead
+ *   of following the source note's letter.
+ * @returns The transposed note.
+ * @example
+ * ```ts
+ * import { transposeNote, formatNote, parseNote } from '@libraz/libcantus';
+ * formatNote(transposeNote(parseNote('Ab4'), 2)); // 'Bb4'
+ * formatNote(transposeNote(parseNote('Ab4'), 2, { spelling: 'sharp' })); // 'A#4'
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function transposeNote(note: Note, semitones: number, opts?: {
+    spelling?: 'sharp' | 'flat';
+}): Note;
+/**
+ * The semitone span of the interval named by a diatonic number and a quality.
+ *
+ * The inverse of the quality derivation in {@link spelledInterval}: it turns a
+ * name back into a distance, which is what transposing by a named interval or
+ * parsing one from text needs.
+ *
+ * @param numberValue Diatonic size: 1 = unison, 2 = second, ... 8 = octave.
+ * @param quality Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`.
+ * @returns The unsigned semitone span.
+ * @throws If the quality cannot apply to the number, such as a major fifth or a
+ *   diminished unison.
+ * @example
+ * ```ts
+ * import { intervalSemitones } from '@libraz/libcantus';
+ * intervalSemitones(5, 'P'); // 7
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function intervalSemitones(numberValue: number, quality: IntervalQualityLabel): number;
+/**
+ * Parse an interval name such as `'P5'`, `'m3'`, `'AA4'`, or `'-m3'`.
+ *
+ * A leading `'-'` names the same interval taken downward: the span is negated
+ * and `descending` is set. The flag is not redundant with the sign — a
+ * descending unison spans zero semitones, so only the flag records that the
+ * letters move down.
+ *
+ * @param name The interval name: an optional `'-'`, a quality label, and a
+ *   diatonic number. Surrounding whitespace is ignored.
+ * @returns The spelled interval. An ascending name carries a non-negative span
+ *   and no `descending` flag.
+ * @throws If the name is not a quality label followed by a number, or the two
+ *   cannot describe the same interval. Use {@link tryParseInterval} where
+ *   failure is ordinary, such as an interval field read on every keystroke.
+ * @example
+ * ```ts
+ * import { parseInterval } from '@libraz/libcantus';
+ * parseInterval('m3'); // { number: 3, quality: 'm', semitones: 3 }
+ * parseInterval('-m3'); // { number: 3, quality: 'm', semitones: -3, descending: true }
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function parseInterval(name: string): SpelledInterval;
+/**
+ * Parse an interval name, reporting failure instead of throwing it.
+ *
+ * The same reading as {@link parseInterval} — that function is this one with
+ * its error thrown — for the callers where a name that does not parse yet is
+ * the normal state of the input rather than a fault.
+ *
+ * @param name The interval name.
+ * @returns The interval, or the error explaining why the text is not one.
+ * @example
+ * ```ts
+ * import { tryParseInterval } from '@libraz/libcantus';
+ * const result = tryParseInterval('M5');
+ * result.ok ? result.value.semitones : result.error.message; // a fifth cannot be major
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function tryParseInterval(name: string): ParseResult<SpelledInterval>;
+/**
+ * Anything that names a spelled interval: an interval name, plain interval
+ * data, or a value that serializes to interval data such as the `Interval`
+ * class.
+ *
+ * @category Pitch & Intervals
+ */
+type IntervalLike = string | SpelledInterval | {
+    /** The interval data this value stands for. */
+    toJSON(): SpelledInterval;
+};
+/**
+ * Resolve any interval-shaped value to plain {@link SpelledInterval} data.
+ *
+ * This is what lets an entry point accept an interval name, the plain data the
+ * pitch module returns, or an `Interval` instance without every caller
+ * branching on the form. An instance is accepted through its `toJSON` method
+ * rather than by its type, because the core layer cannot import the model layer
+ * that defines the class.
+ *
+ * @param value An interval name, plain interval data, or a value whose `toJSON`
+ *   returns interval data.
+ * @returns The validated interval data, carrying `descending` only when the
+ *   interval descends.
+ * @throws If the value is not interval-shaped, or its number, quality, and span
+ *   do not describe the same interval.
+ * @example
+ * ```ts
+ * import { toSpelledInterval } from '@libraz/libcantus';
+ * toSpelledInterval('P5'); // { number: 5, quality: 'P', semitones: 7 }
+ * toSpelledInterval({ number: 5, quality: 'P', semitones: -7 });
+ * // { number: 5, quality: 'P', semitones: -7, descending: true }
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function toSpelledInterval(value: IntervalLike): SpelledInterval;
+/**
+ * Anything that names a spelled note: a note name, plain note data, a MIDI
+ * number, or a value that serializes to note data such as the `Note` class.
+ *
+ * @category Pitch & Intervals
+ */
+type NoteLike = string | number | Note | {
+    /** The note data this value stands for. */
+    toJSON(): Note;
+};
+/**
+ * Resolve any note-shaped value to plain {@link Note} data.
+ *
+ * The counterpart of {@link toSpelledInterval} for notes: an entry point takes
+ * whatever form the caller has — the name a text field holds, the MIDI number a
+ * device sends, the data the pitch module returns, or a `Note` instance — and
+ * gets one shape back. An instance is accepted through its `toJSON` method
+ * rather than by its type, because the core layer cannot import the model layer
+ * that defines the class.
+ *
+ * A number is read as MIDI and spelled with sharps, the same reading
+ * {@link midiToNote} takes by default. Where a key is known the caller spells
+ * it there instead — `spellPitch` reads the key — because no single default
+ * suits both a G# in E major and an Ab in Eb major.
+ *
+ * @param value A note name, a MIDI number, plain note data, or a value whose
+ *   `toJSON` returns note data.
+ * @returns The validated note data, carrying `octave` only when the value has
+ *   one.
+ * @throws If the value is not note-shaped, or its letter, alteration, or octave
+ *   fall outside the range a spelled note holds.
+ * @example
+ * ```ts
+ * import { toNoteData } from '@libraz/libcantus';
+ * toNoteData('Eb4'); // { letter: 2, alter: -1, octave: 4 }
+ * toNoteData(60); // { letter: 0, alter: 0, octave: 4 }
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function toNoteData(value: NoteLike): Note;
+/**
+ * Transpose a note by a spelled interval, keeping the spelling the interval
+ * names.
+ *
+ * Unlike {@link transposeNote}, which picks a letter from the semitone count,
+ * the diatonic number decides the letter here: transposing C by an augmented
+ * second gives D#, not Eb.
+ *
+ * @param note The note to transpose.
+ * @param interval The interval to apply; a negative span transposes downward.
+ * @returns The transposed note, octave-less if the source was.
+ * @example
+ * ```ts
+ * import { formatNote, parseInterval, parseNote, transposeByInterval } from '@libraz/libcantus';
+ * formatNote(transposeByInterval(parseNote('C4'), parseInterval('A2'))); // 'D#4'
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function transposeByInterval(note: Note, interval: SpelledInterval): Note;
+/**
+ * The spelled interval from one note to another.
+ *
+ * When both notes carry octaves, the interval reflects their full signed
+ * distance (so `C4 -> C5` is a perfect octave). When either lacks an octave the
+ * interval is measured within a single ascending octave from `a` to `b`.
+ *
+ * @param a The lower/first note.
+ * @param b The upper/second note.
+ * @returns The diatonic number, quality, and semitone span.
+ * @example
+ * ```ts
+ * import { spelledInterval, parseNote } from '@libraz/libcantus';
+ * spelledInterval(parseNote('C4'), parseNote('G4'));
+ * // { number: 5, quality: 'P', semitones: 7 }
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function spelledInterval(a: Note, b: Note): SpelledInterval;
+
+export { ARTICULATIONS as A, BudgetExceededError as B, toSpelledInterval as C, transposeByInterval as D, transposeNote as E, tryParseInterval as F, tryParseKeyName as G, tryParseNote as H, type IntervalLike as I, type KeyName as K, type LibcantusError as L, NoSolutionError as N, type ParseResult as P, type SpelledInterval as S, type Articulation as a, type IntervalQualityLabel as b, InvalidInputError as c, type KeyScale as d, type LibcantusErrorCode as e, type Note as f, type NoteEvent as g, type NoteLike as h, type NoteNameOptions as i, type NoteNameSystem as j, detectNoteNameSystem as k, diatonicLetterOf as l, formatKeyName as m, formatNote as n, intervalSemitones as o, isLibcantusError as p, midiToNote as q, naturalPitchClassOf as r, noteToMidi as s, noteToPitchClass as t, parseInterval as u, parseKeyName as v, parseNote as w, pitchClassOf as x, spelledInterval as y, toNoteData as z };