@libraz/libcantus 0.9.1 → 0.9.3

package/dist/index-CGMZNCx6.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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;
+};
+/**
+ * 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: string;
+    /** Signed semitone distance from the first note to the second. */
+    semitones: number;
+};
+/**
+ * Parse scientific pitch notation into a {@link Note}.
+ *
+ * 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.
+ *
+ * @param text The note text.
+ * @returns The parsed note.
+ * @throws If the text is not a valid note.
+ * @example
+ * ```ts
+ * import { parseNote, noteToMidi } from '@libraz/libcantus';
+ * const n = parseNote('C#4');
+ * noteToMidi(n); // 61
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function parseNote(text: string): Note;
+/**
+ * Render a {@link Note} as scientific pitch notation.
+ *
+ * @param note The note to format.
+ * @returns The note text, including the octave when present.
+ * @example
+ * ```ts
+ * import { formatNote, parseNote } from '@libraz/libcantus';
+ * formatNote(parseNote('C#4')); // 'C#4'
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function formatNote(note: Note): 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.
+ * @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;
+/**
+ * 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 { type Note as N, type SpelledInterval as S, noteToPitchClass as a, formatNote as f, midiToNote as m, noteToMidi as n, parseNote as p, spelledInterval as s };

package/dist/index-Cl7mhOFM.d.cts

@@ -0,0 +1,164 @@
+/**
+ * Meter and time signatures: bar/beat arithmetic, simple vs. compound meters,
+ * metric-accent hierarchy, and tuplet subdivision.
+ *
+ * Positions and durations are measured in quarter-note beats, matching the rest
+ * of the library's beat convention (four quarter-note beats per bar in 4/4).
+ */
+/**
+ * A time signature as a numerator over a note-value denominator.
+ *
+ * @category Rhythm & Meter
+ */
+type TimeSignature = {
+    numerator: number;
+    denominator: number;
+    /**
+     * Optional additive grouping of the bar's main pulses, as the felt-beat
+     * lengths in pulses — e.g. `[2, 2, 3]` for a 2+2+3 reading of 7/8, or
+     * `[3, 2]` for 5/8. The entries must be positive integers summing to
+     * {@link pulsesPerBar}. When present, the head pulse of each group (other
+     * than the downbeat) is treated as a secondary strong pulse by
+     * {@link metricWeight}/{@link isStrongBeat}; when absent, all main pulses
+     * are weighted equally as flat, evenly divided pulses.
+     */
+    grouping?: number[];
+};
+/**
+ * A position expressed as a bar index and a quarter-note offset within the bar.
+ *
+ * @category Rhythm & Meter
+ */
+type BarPosition = {
+    bar: number;
+    /** Quarter-note offset from the start of the bar. */
+    beat: number;
+};
+/**
+ * Parse a time signature such as `"4/4"` or `"6/8"`.
+ *
+ * @param text The signature text.
+ * @returns The parsed time signature.
+ * @throws If the text is not `n/d` with positive integers.
+ * @example
+ * ```ts
+ * import { parseTimeSignature } from '@libraz/libcantus';
+ * parseTimeSignature('6/8'); // { numerator: 6, denominator: 8 }
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function parseTimeSignature(text: string): TimeSignature;
+/**
+ * Render a time signature as `"n/d"`.
+ *
+ * @category Rhythm & Meter
+ */
+declare function formatTimeSignature(ts: TimeSignature): string;
+/**
+ * Whether a meter is compound: its main pulses each divide into three, as in
+ * 6/8, 9/8, 12/8, or 6/4. Compound meters are those whose numerator is a
+ * multiple of three greater than three, independent of the denominator. Meters
+ * like 3/8 and 3/4 (simple triples, numerator 3) are not compound.
+ *
+ * @param ts The time signature.
+ * @returns True for compound meters.
+ * @category Rhythm & Meter
+ */
+declare function isCompound(ts: TimeSignature): boolean;
+/**
+ * Length of a bar in quarter-note beats.
+ *
+ * @param ts The time signature.
+ * @returns The bar length in quarter notes.
+ * @category Rhythm & Meter
+ */
+declare function beatsPerBar(ts: TimeSignature): number;
+/**
+ * Number of main pulses (felt beats) per bar: the numerator for simple meters,
+ * a third of it for compound meters.
+ *
+ * For additive/irregular meters such as 7/8 or 5/8 this counts the raw pulses
+ * (7 and 5 respectively), which are otherwise felt as flat, evenly divided and
+ * equally accented pulses. To recover a 2+2+3 or 3+2 felt-beat grouping, set
+ * {@link TimeSignature.grouping}; {@link metricWeight} then accents each
+ * group's head pulse.
+ *
+ * @param ts The time signature.
+ * @returns The pulse count per bar.
+ * @category Rhythm & Meter
+ */
+declare function pulsesPerBar(ts: TimeSignature): number;
+/**
+ * Convert an absolute quarter-note position to a bar index and in-bar offset.
+ *
+ * @param beatInQuarters Absolute position in quarter-note beats.
+ * @param ts The time signature.
+ * @returns The bar and in-bar quarter-note offset.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, beatToBarPosition } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * beatToBarPosition(5, ts); // { bar: 1, beat: 1 }
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition;
+/**
+ * Convert a bar index and in-bar offset back to an absolute quarter-note
+ * position.
+ *
+ * @param pos The bar position.
+ * @param ts The time signature.
+ * @returns The absolute position in quarter-note beats.
+ * @category Rhythm & Meter
+ */
+declare function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number;
+/**
+ * Metric weight of a position within its bar, on a 0–3 scale:
+ * 3 the downbeat, 2 a secondary strong pulse, 1 any other main pulse, and 0 an
+ * off-pulse subdivision.
+ *
+ * The secondary strong pulse is the bar's midpoint in even simple/compound
+ * meters. For an additive/irregular meter with {@link TimeSignature.grouping}
+ * set (e.g. `[2, 2, 3]` for 7/8), each group's head pulse other than the
+ * downbeat is the secondary strong pulse instead; without a grouping every
+ * non-downbeat main pulse of such a meter weighs 1 (flat, evenly divided
+ * pulses).
+ *
+ * @param beatInQuarters Absolute or in-bar quarter-note position.
+ * @param ts The time signature.
+ * @returns The metric weight (0–3).
+ * @throws If `ts.grouping` is present but is not a positive-integer list
+ *   summing to {@link pulsesPerBar}.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, metricWeight } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * metricWeight(0, ts); // 3 (the downbeat)
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function metricWeight(beatInQuarters: number, ts: TimeSignature): number;
+/**
+ * Whether a position is metrically accented (weight 2 or more — a downbeat or a
+ * secondary strong pulse).
+ *
+ * @param beatInQuarters Absolute or in-bar quarter-note position.
+ * @param ts The time signature.
+ * @returns True on strong beats.
+ * @category Rhythm & Meter
+ */
+declare function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean;
+/**
+ * Subdivide a span into `count` equal tuplet durations (e.g. an eighth-note
+ * triplet is `tuplet(1, 3)`).
+ *
+ * @param totalBeats Total span in quarter-note beats.
+ * @param count Number of equal parts.
+ * @returns `count` equal durations summing to `totalBeats`.
+ * @throws If `count` is not a positive integer.
+ * @category Rhythm & Meter
+ */
+declare function tuplet(totalBeats: number, count: number): number[];
+
+export { type BarPosition as B, type TimeSignature as T, beatToBarPosition as a, barPositionToBeat as b, beatsPerBar as c, isStrongBeat as d, pulsesPerBar as e, formatTimeSignature as f, isCompound as i, metricWeight as m, parseTimeSignature as p, tuplet as t };

package/dist/index-Cl7mhOFM.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Meter and time signatures: bar/beat arithmetic, simple vs. compound meters,
+ * metric-accent hierarchy, and tuplet subdivision.
+ *
+ * Positions and durations are measured in quarter-note beats, matching the rest
+ * of the library's beat convention (four quarter-note beats per bar in 4/4).
+ */
+/**
+ * A time signature as a numerator over a note-value denominator.
+ *
+ * @category Rhythm & Meter
+ */
+type TimeSignature = {
+    numerator: number;
+    denominator: number;
+    /**
+     * Optional additive grouping of the bar's main pulses, as the felt-beat
+     * lengths in pulses — e.g. `[2, 2, 3]` for a 2+2+3 reading of 7/8, or
+     * `[3, 2]` for 5/8. The entries must be positive integers summing to
+     * {@link pulsesPerBar}. When present, the head pulse of each group (other
+     * than the downbeat) is treated as a secondary strong pulse by
+     * {@link metricWeight}/{@link isStrongBeat}; when absent, all main pulses
+     * are weighted equally as flat, evenly divided pulses.
+     */
+    grouping?: number[];
+};
+/**
+ * A position expressed as a bar index and a quarter-note offset within the bar.
+ *
+ * @category Rhythm & Meter
+ */
+type BarPosition = {
+    bar: number;
+    /** Quarter-note offset from the start of the bar. */
+    beat: number;
+};
+/**
+ * Parse a time signature such as `"4/4"` or `"6/8"`.
+ *
+ * @param text The signature text.
+ * @returns The parsed time signature.
+ * @throws If the text is not `n/d` with positive integers.
+ * @example
+ * ```ts
+ * import { parseTimeSignature } from '@libraz/libcantus';
+ * parseTimeSignature('6/8'); // { numerator: 6, denominator: 8 }
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function parseTimeSignature(text: string): TimeSignature;
+/**
+ * Render a time signature as `"n/d"`.
+ *
+ * @category Rhythm & Meter
+ */
+declare function formatTimeSignature(ts: TimeSignature): string;
+/**
+ * Whether a meter is compound: its main pulses each divide into three, as in
+ * 6/8, 9/8, 12/8, or 6/4. Compound meters are those whose numerator is a
+ * multiple of three greater than three, independent of the denominator. Meters
+ * like 3/8 and 3/4 (simple triples, numerator 3) are not compound.
+ *
+ * @param ts The time signature.
+ * @returns True for compound meters.
+ * @category Rhythm & Meter
+ */
+declare function isCompound(ts: TimeSignature): boolean;
+/**
+ * Length of a bar in quarter-note beats.
+ *
+ * @param ts The time signature.
+ * @returns The bar length in quarter notes.
+ * @category Rhythm & Meter
+ */
+declare function beatsPerBar(ts: TimeSignature): number;
+/**
+ * Number of main pulses (felt beats) per bar: the numerator for simple meters,
+ * a third of it for compound meters.
+ *
+ * For additive/irregular meters such as 7/8 or 5/8 this counts the raw pulses
+ * (7 and 5 respectively), which are otherwise felt as flat, evenly divided and
+ * equally accented pulses. To recover a 2+2+3 or 3+2 felt-beat grouping, set
+ * {@link TimeSignature.grouping}; {@link metricWeight} then accents each
+ * group's head pulse.
+ *
+ * @param ts The time signature.
+ * @returns The pulse count per bar.
+ * @category Rhythm & Meter
+ */
+declare function pulsesPerBar(ts: TimeSignature): number;
+/**
+ * Convert an absolute quarter-note position to a bar index and in-bar offset.
+ *
+ * @param beatInQuarters Absolute position in quarter-note beats.
+ * @param ts The time signature.
+ * @returns The bar and in-bar quarter-note offset.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, beatToBarPosition } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * beatToBarPosition(5, ts); // { bar: 1, beat: 1 }
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition;
+/**
+ * Convert a bar index and in-bar offset back to an absolute quarter-note
+ * position.
+ *
+ * @param pos The bar position.
+ * @param ts The time signature.
+ * @returns The absolute position in quarter-note beats.
+ * @category Rhythm & Meter
+ */
+declare function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number;
+/**
+ * Metric weight of a position within its bar, on a 0–3 scale:
+ * 3 the downbeat, 2 a secondary strong pulse, 1 any other main pulse, and 0 an
+ * off-pulse subdivision.
+ *
+ * The secondary strong pulse is the bar's midpoint in even simple/compound
+ * meters. For an additive/irregular meter with {@link TimeSignature.grouping}
+ * set (e.g. `[2, 2, 3]` for 7/8), each group's head pulse other than the
+ * downbeat is the secondary strong pulse instead; without a grouping every
+ * non-downbeat main pulse of such a meter weighs 1 (flat, evenly divided
+ * pulses).
+ *
+ * @param beatInQuarters Absolute or in-bar quarter-note position.
+ * @param ts The time signature.
+ * @returns The metric weight (0–3).
+ * @throws If `ts.grouping` is present but is not a positive-integer list
+ *   summing to {@link pulsesPerBar}.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, metricWeight } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * metricWeight(0, ts); // 3 (the downbeat)
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function metricWeight(beatInQuarters: number, ts: TimeSignature): number;
+/**
+ * Whether a position is metrically accented (weight 2 or more — a downbeat or a
+ * secondary strong pulse).
+ *
+ * @param beatInQuarters Absolute or in-bar quarter-note position.
+ * @param ts The time signature.
+ * @returns True on strong beats.
+ * @category Rhythm & Meter
+ */
+declare function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean;
+/**
+ * Subdivide a span into `count` equal tuplet durations (e.g. an eighth-note
+ * triplet is `tuplet(1, 3)`).
+ *
+ * @param totalBeats Total span in quarter-note beats.
+ * @param count Number of equal parts.
+ * @returns `count` equal durations summing to `totalBeats`.
+ * @throws If `count` is not a positive integer.
+ * @category Rhythm & Meter
+ */
+declare function tuplet(totalBeats: number, count: number): number[];
+
+export { type BarPosition as B, type TimeSignature as T, beatToBarPosition as a, barPositionToBeat as b, beatsPerBar as c, isStrongBeat as d, pulsesPerBar as e, formatTimeSignature as f, isCompound as i, metricWeight as m, parseTimeSignature as p, tuplet as t };

package/dist/index-CnZCo29u.d.cts

@@ -0,0 +1,108 @@
+import { K as KeyScale } from './types-MGP29r3t.cjs';
+import { a as ChordQuality, C as Chord } from './index-BNlGP86A.cjs';
+
+/**
+ * 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 };