@libraz/libcantus 0.9.2 → 0.9.4

package/dist/{index-CM5W4rcm.d.ts → index-y_ak9_Hi.d.cts}

@@ -1,11 +1,20 @@
-import { K as KeyScale } from './types-MGP29r3t.js';
+import { K as KeyScale } from './types-BN6_Q9Kl.cjs';
 
 /**
  * Chord quality identifiers understood by the chord builder.
  *
  * @category Chords
  */
-type ChordQuality = 'maj' | 'min' | 'dim' | 'aug' | 'maj7' | 'min7' | 'dom7' | 'dim7' | 'm7b5' | 'minMaj7' | 'aug7' | 'augMaj7' | 'majb5' | '6' | 'min6' | '6/9' | 'sus2' | 'sus4' | 'add9' | 'add11' | 'maj9' | 'min9' | 'dom9' | '7b9' | '7#9' | '7#11' | '7b13' | '11' | '13' | '5';
+type ChordQuality = 'maj' | 'min' | 'dim' | 'aug' | 'maj7' | 'min7' | 'dom7' | 'dim7' | 'm7b5' | 'minMaj7' | '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 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).
@@ -54,7 +63,26 @@ type ChordSpan = {
     secondaryDominant?: boolean;
 };
 /**
- * All chord qualities the builder understands, longest templates last.
+ * 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
  */
@@ -92,21 +120,73 @@ declare function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScal
  * @category Chords
  */
 declare function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord;
+/**
+ * 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): number[];
+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.
  *
@@ -121,18 +201,21 @@ declare function chordPitchClasses(chord: Chord): number[];
  *
  * @category Chords
  */
-declare function chordToneRole(pitch: number, chord: Chord): 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | null;
+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). Intended for heptatonic
- * scales; other scales stack by scale step regardless.
+ * diminished triad on the leading tone of a major key).
  *
  * @param degree 0-based scale degree of the chord root.
  * @param key Key/scale context.
  * @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
@@ -149,9 +232,11 @@ declare function diatonicTriad(degree: number, key: KeyScale): Chord;
  * @param degree 0-based scale degree of the chord root.
  * @param key Key/scale context.
  * @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: KeyScale): Chord;
 
-export { type Chord as C, type ChordQuality as a, type ChordSpan as b, chordFromDegree as c, chordPitchClasses as d, chordQualities as e, chordToneRole as f, diatonicSeventh as g, diatonicTriad as h, makeChord as m };
+export { type Chord as C, type PitchSpelling as P, type ChordQuality as a, type ChordSegment as b, type ChordSpan as c, type ChordToneRole as d, chordFromDegree as e, chordPitchClasses as f, chordQualities as g, chordToneRole as h, diatonicSeventh as i, diatonicTriad as j, intervalAboveRoot as k, isChordMember as l, makeChord as m, transposeChord as t };