@libraz/libcantus 0.9.1 → 0.9.3

package/dist/index-JnF4v9bx.d.ts

@@ -0,0 +1,108 @@
+import { K as KeyScale } from './types-MGP29r3t.js';
+import { a as ChordQuality, C as Chord } from './index-Bt4tOUD9.js';
+
+/**
+ * Recognition: infer a chord name from a set of pitches, or a key from a set of
+ * pitch classes. This is the inverse direction of the chord/scale builders,
+ * which only go name -> notes.
+ */
+
+/**
+ * A candidate chord interpretation of a pitch set.
+ *
+ * @category Recognition
+ */
+type ChordMatch = {
+    rootPc: number;
+    quality: ChordQuality;
+    /** Chord tones absent from the input (an incomplete voicing). */
+    missingPcs: number[];
+    /** Input pitch classes not belonging to the chord. */
+    extraPcs: number[];
+    /** True when the input pitch-class set equals the chord exactly. */
+    exact: boolean;
+    /** Inversion implied by a known bass, or null for an unordered pitch-class set. */
+    inversion: number | null;
+    /** Bass pitch class when inverted (the lowest note is not the root). */
+    bassPc?: number;
+};
+/** Input interpretation for {@link detectChord} and {@link detectChordBest}. */
+type DetectChordOptions = {
+    /**
+     * `midi` uses the numerically lowest pitch as bass; `pitchClass` treats the
+     * input as unordered. `auto` (default) selects pitch-class mode only when all
+     * values lie in 0..11.
+     */
+    input?: 'auto' | 'midi' | 'pitchClass';
+    /** Explicit bass pitch class, including for an unordered pitch-class set. */
+    bassPc?: number;
+};
+/**
+ * A candidate key interpretation of a pitch-class set.
+ *
+ * @category Recognition
+ */
+type KeyMatch = {
+    key: KeyScale;
+    mode: 'major' | 'minor';
+    /** Fraction of input pitch classes that are in the scale, in [0, 1]. */
+    fit: number;
+};
+/**
+ * Identify chords matching a set of pitches.
+ *
+ * Every input pitch class is tried as a root against every known chord quality.
+ * A match is reported when all of the chord's tones are present in the input, or
+ * when the only absent tone is the perfect fifth (a common omission in shell
+ * voicings); matches are ranked best-first by fewest extra notes, then fewest
+ * missing notes, then most specific (largest) chord. An exact match (no extras,
+ * no missing) is flagged and ranked first.
+ *
+ * @param pitches MIDI pitches or bare pitch classes (octave-agnostic).
+ * @returns Ranked chord interpretations (may be empty).
+ * @example
+ * ```ts
+ * import { detectChord } from '@libraz/libcantus';
+ * const matches = detectChord([60, 64, 67]); // C E G
+ * matches[0]; // { rootPc: 0, quality: 'maj', exact: true, ... }
+ * ```
+ * @category Recognition
+ */
+declare function detectChord(pitches: number[], opts?: DetectChordOptions): ChordMatch[];
+/**
+ * The single best chord interpretation of a pitch set, or null if none.
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @returns The top-ranked chord, or null when nothing matches.
+ * @example
+ * ```ts
+ * import { detectChordBest } from '@libraz/libcantus';
+ * detectChordBest([60, 64, 67]); // C major triad: { rootPc: 0, quality: 'maj', ... }
+ * ```
+ * @category Recognition
+ */
+declare function detectChordBest(pitches: number[], opts?: DetectChordOptions): Chord | null;
+/**
+ * Rank major and minor keys by how well they contain a set of pitch classes.
+ *
+ * The tonic is weighted so that, among equally-fitting keys, the one whose root
+ * appears in the input is preferred. Minor candidates are scored against the
+ * natural, harmonic, and melodic minor variants and keep the best of the three,
+ * so a minor cadence containing the leading tone still resolves to its own
+ * tonic; the returned key is always the natural-minor scale. Returns all 24
+ * keys ranked best-first, or an empty array for an empty input (mirroring
+ * {@link detectChord}).
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @returns Ranked key interpretations (empty for an empty input).
+ * @example
+ * ```ts
+ * import { detectKey } from '@libraz/libcantus';
+ * const keys = detectKey([60, 62, 64, 65, 67, 69, 71]); // C major scale
+ * keys[0].mode; // 'major', with keys[0].key.rootPc === 0
+ * ```
+ * @category Recognition
+ */
+declare function detectKey(pitches: number[]): KeyMatch[];
+
+export { type ChordMatch as C, type DetectChordOptions as D, type KeyMatch as K, detectChordBest as a, detectKey as b, detectChord as d };