@libraz/libcantus 0.9.0 → 0.9.2

package/dist/model/index.d.cts

@@ -0,0 +1,630 @@
+import { H as HarmonicFunction, a as ChordAnalysis, C as Cadence, B as BorrowedSource } from '../function-r2sh-jOO.cjs';
+import { a as ChordQuality, C as Chord$1 } from '../index-BOBXBNwP.cjs';
+import { d as VoicingOptions, c as StyledVoicingOptions, C as ChordScaleMatch } from '../styled-BjXtOFNk.cjs';
+import { N as Note$1, S as SpelledInterval } from '../index-CGMZNCx6.cjs';
+import { K as KeyScale } from '../types-MGP29r3t.cjs';
+
+/**
+ * An immutable spelled note: a diatonic letter plus a chromatic alteration and
+ * an optional octave. Wraps the plain note object and delegates to the pitch
+ * module; every transformation returns a new instance.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Note } from '@libraz/libcantus';
+ * Note.of('C4').transpose(7).name; // 'G4'
+ * ```
+ */
+declare class Note {
+    #private;
+    /**
+     * Wrap a plain note object.
+     *
+     * @param data The spelled note; it is copied, never retained or mutated.
+     */
+    constructor(data: Note$1);
+    /**
+     * Parse scientific pitch notation (e.g. `'C#4'`, `'Bb'`, `'F##3'`).
+     *
+     * @param name The note text.
+     * @returns The parsed note.
+     * @throws If the text is not a valid note.
+     */
+    static of(name: string): Note;
+    /**
+     * Name a MIDI number (middle C = C4 = 60) as a note.
+     *
+     * @param midi The MIDI number.
+     * @param spelling Whether to prefer sharps or flats for black keys.
+     * @returns The spelled note, with octave.
+     */
+    static fromMidi(midi: number, spelling?: 'sharp' | 'flat'): Note;
+    /**
+     * Wrap an existing plain note object.
+     *
+     * @param data The plain note.
+     * @returns The wrapped note.
+     */
+    static fromData(data: Note$1): Note;
+    /** The note rendered as scientific pitch notation, e.g. `'G4'` or `'Bb'`. */
+    get name(): string;
+    /** The pitch class (0..11), ignoring octave. */
+    get pitchClass(): number;
+    /**
+     * The MIDI number (middle C = C4 = 60).
+     *
+     * @throws If the note has no octave and therefore no fixed pitch.
+     */
+    get midi(): number;
+    /** The diatonic letter number: 0..6 for C..B. */
+    get letter(): number;
+    /** The chromatic alteration in semitones: -1 flat, 0 natural, +1 sharp, ... */
+    get alter(): number;
+    /** The octave (scientific pitch notation), or undefined for a bare pitch class. */
+    get octave(): number | undefined;
+    /** A copy of the underlying plain note object. */
+    get data(): Note$1;
+    /**
+     * Transpose by a signed number of semitones.
+     *
+     * When the note carries an octave the transposition happens in MIDI space and
+     * the result is spelled with a sharp preference. An octave-less note stays
+     * octave-less: only its pitch class is moved. Transposing by zero is the
+     * identity: the original spelling is preserved (no enharmonic respelling).
+     *
+     * @param semitones The signed semitone offset.
+     * @returns The transposed note.
+     */
+    transpose(semitones: number): Note;
+    /**
+     * The spelled interval from this note to another.
+     *
+     * @param other The second note.
+     * @returns The diatonic number, quality, and semitone span.
+     */
+    intervalTo(other: Note): SpelledInterval;
+    /**
+     * Whether another note has the same letter, alteration, and octave.
+     *
+     * @param other The note to compare.
+     * @returns True if the spellings are identical.
+     */
+    equals(other: Note): boolean;
+    /**
+     * The plain note data, for JSON serialization.
+     *
+     * Private class fields do not serialize, so an explicit `toJSON` keeps
+     * `JSON.stringify(note)` from collapsing to `{}`.
+     *
+     * @returns A copy of the underlying plain note object.
+     */
+    toJSON(): Note$1;
+}
+
+/**
+ * An immutable key/scale: a `KeyScale` (root pitch class plus mode mask) paired
+ * with a spelled tonic that anchors letter-name spelling. Acts as the factory
+ * for key-aware chords.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Key } from '@libraz/libcantus';
+ * Key.major('C').chord(4).symbol(); // 'G' (the diatonic triad on scale degree 4)
+ * ```
+ */
+declare class Key {
+    #private;
+    /**
+     * Wrap a key/scale and its spelled tonic.
+     *
+     * @param scale The key/scale; its root is normalized to a pitch class.
+     * @param tonic The spelled tonic anchoring letter-name spelling.
+     */
+    constructor(scale: KeyScale, tonic: Note);
+    /**
+     * A major key.
+     *
+     * @param root Tonic as a note name (e.g. `'Eb'`) or a pitch class; a numeric
+     *   root is spelled with whichever accidental side yields the fewest
+     *   accidentals across the scale.
+     * @returns The major key.
+     */
+    static major(root: string | number): Key;
+    /**
+     * A natural-minor key.
+     *
+     * @param root Tonic as a note name or a pitch class; a numeric root is
+     *   spelled with whichever accidental side yields the fewest accidentals
+     *   across the scale.
+     * @returns The minor key.
+     */
+    static minor(root: string | number): Key;
+    /**
+     * A key on a named scale (e.g. `'dorian'`, `'harmonicMinor'`).
+     *
+     * @param name The scale name, a key of the scale module's named-scale table.
+     * @param root Tonic as a note name or a pitch class.
+     * @returns The key.
+     * @throws If the name is not a known scale.
+     */
+    static named(name: string, root: string | number): Key;
+    /**
+     * Wrap an existing `KeyScale`, synthesizing a spelled tonic when none is
+     * given (flat-preferred for minor-third scales, sharp-preferred otherwise).
+     *
+     * @param scale The key/scale to wrap.
+     * @param tonic Optional spelled tonic.
+     * @returns The key.
+     */
+    static of(scale: KeyScale, tonic?: Note): Key;
+    /** A copy of the underlying plain `KeyScale`. */
+    get scale(): KeyScale;
+    /** The spelled tonic. */
+    get tonic(): Note;
+    /** The tonic pitch class (0..11). */
+    get rootPc(): number;
+    /** Whether the scale has a minor third and no major third. */
+    get isMinor(): boolean;
+    /**
+     * The scale's pitch classes in ascending scale-degree order (degree 0 first).
+     *
+     * @returns One pitch class per scale degree.
+     */
+    pitchClasses(): number[];
+    /**
+     * The spelled scale, one note per degree (e.g. C D E F G A B for C major).
+     *
+     * @returns Spelled octave-less notes in scale-degree order.
+     */
+    notes(): Note[];
+    /**
+     * Alias of {@link Key.notes}.
+     *
+     * @returns Spelled octave-less notes in scale-degree order.
+     */
+    spell(): Note[];
+    /**
+     * The spelled scale as letter-name strings.
+     *
+     * @returns One name per scale degree.
+     */
+    noteNames(): string[];
+    /**
+     * Build a chord on a scale degree, carrying this key as context.
+     *
+     * With an explicit quality the quality's interval template is attached to the
+     * degree's diatonic root; without one the scale-correct diatonic triad is
+     * stacked (e.g. a diminished triad on the leading tone of a major key).
+     *
+     * @param degree 0-based scale degree of the chord root.
+     * @param quality Optional chord quality.
+     * @returns The chord, with this key attached.
+     */
+    chord(degree: number, quality?: ChordQuality): Chord;
+    /**
+     * The diatonic triad on a scale degree, carrying this key as context.
+     *
+     * @param degree 0-based scale degree of the chord root.
+     * @returns The triad, with this key attached.
+     */
+    diatonicTriad(degree: number): Chord;
+    /**
+     * The diatonic seventh chord on a scale degree, carrying this key as context.
+     *
+     * @param degree 0-based scale degree of the chord root.
+     * @returns The seventh chord, with this key attached.
+     */
+    diatonicSeventh(degree: number): Chord;
+    /**
+     * Build the chord denoted by a Roman numeral in this key (including applied
+     * chords such as `'V7/V'`), carrying this key as context.
+     *
+     * @param text The Roman numeral.
+     * @returns The chord, with this key attached.
+     * @throws If the numeral is not valid.
+     */
+    roman(text: string): Chord;
+    /**
+     * Whether a pitch belongs to the scale.
+     *
+     * @param x A MIDI pitch, bare pitch class, or note.
+     * @returns True if the pitch class is a scale tone.
+     */
+    contains(x: number | Note): boolean;
+    /**
+     * The plain key data, for JSON serialization.
+     *
+     * Private class fields do not serialize, so an explicit `toJSON` keeps
+     * `JSON.stringify(key)` from collapsing to `{}`. The result pairs the
+     * `KeyScale` with the spelled tonic, enough to reconstruct the key via
+     * {@link Key.of}.
+     *
+     * @returns The key/scale and its spelled tonic.
+     */
+    toJSON(): {
+        scale: KeyScale;
+        tonic: Note$1;
+    };
+}
+
+/**
+ * An immutable ordered sequence of chords, optionally carrying a {@link Key}
+ * context shared by its analysis methods.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Key } from '@libraz/libcantus';
+ * const key = Key.major('C');
+ * key.chord(1).progressionTo(key.chord(4), key.chord(0)).roman();
+ * // ['ii', 'V', 'I']
+ * ```
+ */
+declare class Progression {
+    #private;
+    /**
+     * Wrap a chord sequence.
+     *
+     * @param chords The chords in order; the array is copied.
+     * @param key Optional key context for analysis methods.
+     */
+    constructor(chords: readonly Chord[], key?: Key);
+    /** A copy of the chord sequence. */
+    get chords(): readonly Chord[];
+    /** The carried key context, if any. */
+    get key(): Key | undefined;
+    /** The number of chords. */
+    get length(): number;
+    /**
+     * A copy of this progression with a chord appended.
+     *
+     * @param chord The chord to append.
+     * @returns The new progression.
+     */
+    add(chord: Chord): Progression;
+    /**
+     * A copy of this progression carrying the given key context.
+     *
+     * @param key The key context to attach.
+     * @returns The new progression.
+     */
+    withKey(key: Key): Progression;
+    /**
+     * Voice the progression with smooth voice leading.
+     *
+     * @param opts Voicing options; defaults to four SATB voices.
+     * @returns One ascending voicing (MIDI pitches) per chord.
+     * @throws If any chord admits no voicing within the given ranges.
+     */
+    voice(opts?: VoicingOptions): number[][];
+    /**
+     * The Roman numeral of each chord in a key.
+     *
+     * @param key Key to analyze in; falls back to the carried context.
+     * @returns One numeral per chord.
+     * @throws If no key is given and none is carried.
+     */
+    roman(key?: Key): string[];
+    /**
+     * The harmonic function of each chord in a key.
+     *
+     * @param key Key to analyze in; falls back to the carried context.
+     * @returns One function per chord.
+     * @throws If no key is given and none is carried.
+     */
+    functions(key?: Key): HarmonicFunction[];
+    /**
+     * Analyze every chord and classify the closing cadence.
+     *
+     * The cadence is detected on the final chord pair and is null when the
+     * progression has fewer than two chords.
+     *
+     * @param key Key to analyze in; falls back to the carried context.
+     * @returns Per-chord analyses and the closing cadence.
+     * @throws If no key is given and none is carried.
+     */
+    analyze(key?: Key): {
+        chords: ChordAnalysis[];
+        cadence: Cadence;
+    };
+    /**
+     * The plain progression data, for JSON serialization.
+     *
+     * Private class fields do not serialize, so an explicit `toJSON` keeps
+     * `JSON.stringify(progression)` from collapsing to `{}`. The chords are
+     * emitted as plain data and the carried key, when present, as its own data.
+     *
+     * @returns The chord data sequence and the carried key, if any.
+     */
+    toJSON(): {
+        chords: Chord$1[];
+        key: {
+            scale: KeyScale;
+            tonic: Note$1;
+        } | undefined;
+    };
+}
+
+/**
+ * An immutable chord: a root pitch class, quality, interval template, and
+ * optional slash bass, optionally carrying a {@link Key} context. Analysis
+ * methods (`roman`, `function`, `analyze`, ...) use an explicitly passed key
+ * first and fall back to the carried context.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Chord } from '@libraz/libcantus';
+ * Chord.parse('Cmaj7').invert(1).symbol(); // 'Cmaj7/E' (third in the bass)
+ * ```
+ */
+declare class Chord {
+    #private;
+    /**
+     * Wrap a plain chord object.
+     *
+     * @param data The chord; it is copied, never retained or mutated.
+     * @param key Optional key context for analysis methods.
+     */
+    constructor(data: Chord$1, key?: Key);
+    /**
+     * Build a chord from a root and quality.
+     *
+     * @param root Root as a note name (e.g. `'Eb'`) or a pitch class.
+     * @param quality The chord quality.
+     * @param bass Optional slash-chord bass pitch class.
+     * @returns The chord (without key context).
+     */
+    static of(root: string | number, quality: ChordQuality, bass?: number): Chord;
+    /**
+     * Wrap an existing plain chord object.
+     *
+     * @param data The plain chord.
+     * @returns The wrapped chord (without key context).
+     */
+    static from(data: Chord$1): Chord;
+    /**
+     * Parse a lead-sheet chord symbol (e.g. `'Cmaj7'`, `'F#m7b5'`, `'C/G'`).
+     *
+     * @param symbol The chord symbol.
+     * @returns The chord (without key context).
+     * @throws If the root or quality is not recognized.
+     */
+    static parse(symbol: string): Chord;
+    /**
+     * Identify the chords matching a set of pitches, best interpretation first.
+     *
+     * @param pitches MIDI pitches or bare pitch classes.
+     * @returns Ranked chord interpretations (may be empty).
+     */
+    static detect(pitches: number[]): Chord[];
+    /**
+     * The single best chord interpretation of a pitch set.
+     *
+     * @param pitches MIDI pitches or bare pitch classes.
+     * @returns The top-ranked chord, or null when nothing matches.
+     */
+    static detectBest(pitches: number[]): Chord | null;
+    /** The root pitch class (0..11). */
+    get rootPc(): number;
+    /** The chord quality. */
+    get quality(): ChordQuality;
+    /** A copy of the semitone offsets above the root. */
+    get intervals(): number[];
+    /** The slash-chord bass pitch class, or undefined in root position. */
+    get bassPc(): number | undefined;
+    /** A copy of the underlying plain chord object. */
+    get data(): Chord$1;
+    /** The carried key context, if any. */
+    get key(): Key | undefined;
+    /**
+     * A copy of this chord carrying the given key context.
+     *
+     * @param key The key context to attach.
+     * @returns The new chord.
+     */
+    withKey(key: Key): Chord;
+    /**
+     * The chord's sorted, deduplicated pitch classes.
+     *
+     * @returns Pitch classes ascending in [0, 11].
+     */
+    pitchClasses(): number[];
+    /**
+     * The chord's Roman numeral in a key.
+     *
+     * @param key Key to analyze in; falls back to the carried context.
+     * @returns The Roman numeral string.
+     * @throws If no key is given and none is carried.
+     */
+    roman(key?: Key): string;
+    /**
+     * The chord's harmonic function (tonic / subdominant / dominant) in a key.
+     *
+     * @param key Key to analyze in; falls back to the carried context.
+     * @returns The harmonic function.
+     * @throws If no key is given and none is carried.
+     */
+    function(key?: Key): HarmonicFunction;
+    /**
+     * Full functional analysis: function, borrowing, and Roman numeral.
+     *
+     * @param key Key to analyze in; falls back to the carried context.
+     * @returns The chord analysis.
+     * @throws If no key is given and none is carried.
+     */
+    analyze(key?: Key): ChordAnalysis;
+    /**
+     * Whether the chord is borrowed from the parallel mode (modal interchange).
+     *
+     * @param key Key to analyze in; falls back to the carried context.
+     * @returns True if the chord is borrowed.
+     * @throws If no key is given and none is carried.
+     */
+    isBorrowed(key?: Key): boolean;
+    /**
+     * The origin of a non-diatonic chord (parallel mode or Neapolitan), or null.
+     *
+     * @param key Key to analyze in; falls back to the carried context.
+     * @returns The borrowing source, or null.
+     * @throws If no key is given and none is carried.
+     */
+    borrowedSource(key?: Key): BorrowedSource;
+    /**
+     * The chord rendered as a lead-sheet symbol (e.g. `'Cmaj7'`, `'F#m7'`, `'C/G'`).
+     *
+     * @param opts Set `flats: true` to spell the root/bass with flats.
+     * @returns The chord symbol.
+     */
+    symbol(opts?: {
+        flats?: boolean;
+    }): string;
+    /**
+     * Realize the chord as one MIDI pitch per voice, ascending.
+     *
+     * @param opts Voicing options; defaults to four SATB voices.
+     * @returns MIDI pitches, ascending, one per voice.
+     * @throws If no voicing fits the given ranges.
+     */
+    voice(opts?: VoicingOptions): number[];
+    /**
+     * Realize the chord as a single styled voicing (`close`, `drop2`, `drop3`,
+     * `shell`, or `rootless`), optionally constraining the top voice.
+     *
+     * @param opts Styled-voicing options; defaults to a close-position voicing.
+     * @returns MIDI pitches, ascending.
+     */
+    styledVoicing(opts?: StyledVoicingOptions): number[];
+    /**
+     * The negative-harmony mirror of the chord about the key's tonic–dominant
+     * axis (major becomes minor and vice versa).
+     *
+     * @param key Key providing the reflection axis; falls back to the carried
+     *   context.
+     * @returns The mirrored chord, keeping any key context.
+     * @throws If no key is given and none is carried.
+     */
+    negativeHarmony(key?: Key): Chord;
+    /**
+     * The n-th inversion: a copy whose bass is the chord tone `n` steps above the
+     * root in the interval template (`invert(1)` puts the third in the bass).
+     * `n` wraps around the template length; negative values count backwards.
+     *
+     * `invert(0)` (and any `n` that wraps to it) is root position, so it carries
+     * no slash bass and equals the original chord.
+     *
+     * @param n The inversion number.
+     * @returns The inverted chord, keeping any key context.
+     * @throws If the chord has no intervals.
+     */
+    invert(n: number): Chord;
+    /**
+     * The named scales that fit over this chord, best fit first, rooted on the
+     * chord root.
+     *
+     * @returns The matching scales.
+     */
+    scales(): ChordScaleMatch[];
+    /**
+     * The available tensions (usable non-chord, non-avoid scale tones) of a
+     * scale over this chord.
+     *
+     * @param scaleName A named scale, rooted on the chord root.
+     * @returns Tension pitch classes, ascending in [0, 11].
+     */
+    tensions(scaleName: string): number[];
+    /**
+     * The avoid notes (scale tones a semitone above a chord tone) of a scale
+     * over this chord.
+     *
+     * @param scaleName A named scale, rooted on the chord root.
+     * @returns Avoid-note pitch classes, ascending in [0, 11].
+     */
+    avoidNotes(scaleName: string): number[];
+    /**
+     * Spell the chord tones with letter names, root first, in the key's spelling.
+     *
+     * @param key Key providing the spelled tonic; falls back to the carried
+     *   context.
+     * @returns Spelled octave-less notes in the chord's own (tertian) order.
+     * @throws If no key is given and none is carried.
+     */
+    spell(key?: Key): Note[];
+    /**
+     * Start a progression with this chord followed by others, carrying this
+     * chord's key context (if any).
+     *
+     * @param others The chords following this one.
+     * @returns The progression.
+     */
+    progressionTo(...others: Chord[]): Progression;
+    /**
+     * Whether another chord has the same root, quality, intervals, and bass.
+     * Key context is not compared.
+     *
+     * @param other The chord to compare.
+     * @returns True if the chord data is identical.
+     */
+    equals(other: Chord): boolean;
+    /**
+     * The plain chord data, for JSON serialization.
+     *
+     * @returns A copy of the underlying plain chord object.
+     */
+    toJSON(): Chord$1;
+}
+
+/**
+ * An immutable spelled interval value: a diatonic number, a quality label, and
+ * a signed semitone span. A thin convenience wrapper over the pitch module's
+ * plain interval result.
+ *
+ * @category Class API
+ * @example
+ * ```ts
+ * import { Interval, Note } from '@libraz/libcantus';
+ * Interval.between(Note.of('C4'), Note.of('G4')).name; // 'P5'
+ * ```
+ */
+declare class Interval {
+    #private;
+    private constructor();
+    /**
+     * The spelled interval between two notes.
+     *
+     * @param a The first note.
+     * @param b The second note.
+     * @returns The interval from `a` to `b`.
+     */
+    static between(a: Note, b: Note): Interval;
+    /**
+     * Build an interval from explicit components.
+     *
+     * @param numberValue Diatonic size: 1 = unison, 2 = second, ... 8 = octave.
+     * @param quality Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`.
+     * @param semitones Signed semitone span.
+     * @returns The interval.
+     */
+    static of(numberValue: number, quality: string, semitones: number): Interval;
+    /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
+    get number(): number;
+    /** Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`. */
+    get quality(): string;
+    /** Signed semitone span. */
+    get semitones(): number;
+    /** A readable label composed of quality and number, e.g. `'P5'` or `'M3'`. */
+    get name(): string;
+    /**
+     * The plain interval data, for JSON serialization.
+     *
+     * Private class fields do not serialize, so an explicit `toJSON` keeps
+     * `JSON.stringify(interval)` from collapsing to `{}`.
+     *
+     * @returns The diatonic number, quality, and semitone span.
+     */
+    toJSON(): SpelledInterval;
+}
+
+export { Chord, Interval, Key, Note, Progression };