@libraz/libcantus 0.9.2 → 0.9.3

package/dist/generate/index.d.cts

@@ -1,9 +1,9 @@
 import { T as TimeSignature } from '../index-Cl7mhOFM.cjs';
 import { K as KeyScale, N as NoteEvent } from '../types-MGP29r3t.cjs';
-import { C as Chord, a as ChordQuality, b as ChordSpan } from '../index-BOBXBNwP.cjs';
-import { H as HarmonyRole } from '../index-BdeQ1r_p.cjs';
-import { b as ChordTimeline } from '../index-D_ZTUNKp.cjs';
-import { B as BorrowedSource, H as HarmonicFunction } from '../function-r2sh-jOO.cjs';
+import { C as Chord, a as ChordQuality, b as ChordSpan } from '../index-BNlGP86A.cjs';
+import { H as HarmonyRole } from '../index-Dikst44v.cjs';
+import { b as ChordTimeline } from '../index-CpOsP1y9.cjs';
+import { B as BorrowedSource, H as HarmonicFunction } from '../function-DYt4iKsn.cjs';
 
 /**
  * Deterministic bass-line generation over a chord placement.
@@ -105,6 +105,12 @@ type CounterMelodyOptions = {
     melody: NoteEvent[];
     /** Chord sounding at an absolute beat position, or null when none applies. */
     chordAt: (beat: number) => Chord | null;
+    /**
+     * Exact chord-change beats exposed by the caller's timeline. The generator
+     * also probes its half-beat grid, but callback discontinuities between grid
+     * points are not introspectable and should be listed here.
+     */
+    chordChangeBeats?: number[];
     /** Key/scale context for scale-tone decisions. */
     key: KeyScale;
     /**
@@ -977,4 +983,4 @@ declare function generateRhythm(ts: TimeSignature, opts?: RhythmOptions): Rhythm
  */
 declare function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number;
 
-export { type BassLineOptions, type BassSegment, type BassStyle, type BorrowedChord, ChordSpan, type CounterMelodyOptions, type DrumHit, type DrumRole, type DrumsOptions, type EuclideanKick, type GrooveFeel, type GrooveSlot, type GrooveStyle, type GrooveTemplate, type HarmonizeOptions, type HarmonizeResult, type HumanizeOptions, type MelodyNote, type MotifCell, type MotifContour, type MotifNote, type MotifOptions, type MotifTransform, type ProgFunction, type ProgStyle, type ProgressionOptions, type ProgressionPreset, type RhythmEvent, type RhythmOptions, type Section, type SubstituteOptions, type Substitution, type SubstitutionType, applyGrooveTemplate, developMotif, extractGrooveTemplate, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, modalInterchangePalette, negativeHarmonyMirror, onsetWeightCurve, progressions, progressionsByStyle, rhythmDensity, substituteChord, transformMotif };
+export { type BassLineOptions, type BassSegment, type BassStyle, type BorrowedChord, type CounterMelodyOptions, type DrumHit, type DrumRole, type DrumsOptions, type EuclideanKick, type GrooveFeel, type GrooveSlot, type GrooveStyle, type GrooveTemplate, type HarmonizeOptions, type HarmonizeResult, type HumanizeOptions, type MelodyNote, type MotifCell, type MotifContour, type MotifNote, type MotifOptions, type MotifTransform, type ProgFunction, type ProgStyle, type ProgressionOptions, type ProgressionPreset, type RhythmEvent, type RhythmOptions, type Section, type SubstituteOptions, type Substitution, type SubstitutionType, applyGrooveTemplate, developMotif, extractGrooveTemplate, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, modalInterchangePalette, negativeHarmonyMirror, onsetWeightCurve, progressions, progressionsByStyle, rhythmDensity, substituteChord, transformMotif };

package/dist/generate/index.d.ts

@@ -1,9 +1,9 @@
 import { T as TimeSignature } from '../index-Cl7mhOFM.js';
 import { K as KeyScale, N as NoteEvent } from '../types-MGP29r3t.js';
-import { C as Chord, a as ChordQuality, b as ChordSpan } from '../index-CM5W4rcm.js';
-import { H as HarmonyRole } from '../index-CP3wAfEH.js';
-import { b as ChordTimeline } from '../index-BMPxwjwV.js';
-import { B as BorrowedSource, H as HarmonicFunction } from '../function-2bJW1Zp_.js';
+import { C as Chord, a as ChordQuality, b as ChordSpan } from '../index-Bt4tOUD9.js';
+import { H as HarmonyRole } from '../index-Bg5dYMmZ.js';
+import { b as ChordTimeline } from '../index-DxvARIP2.js';
+import { B as BorrowedSource, H as HarmonicFunction } from '../function-DVH4Eusr.js';
 
 /**
  * Deterministic bass-line generation over a chord placement.
@@ -105,6 +105,12 @@ type CounterMelodyOptions = {
     melody: NoteEvent[];
     /** Chord sounding at an absolute beat position, or null when none applies. */
     chordAt: (beat: number) => Chord | null;
+    /**
+     * Exact chord-change beats exposed by the caller's timeline. The generator
+     * also probes its half-beat grid, but callback discontinuities between grid
+     * points are not introspectable and should be listed here.
+     */
+    chordChangeBeats?: number[];
     /** Key/scale context for scale-tone decisions. */
     key: KeyScale;
     /**
@@ -977,4 +983,4 @@ declare function generateRhythm(ts: TimeSignature, opts?: RhythmOptions): Rhythm
  */
 declare function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number;
 
-export { type BassLineOptions, type BassSegment, type BassStyle, type BorrowedChord, ChordSpan, type CounterMelodyOptions, type DrumHit, type DrumRole, type DrumsOptions, type EuclideanKick, type GrooveFeel, type GrooveSlot, type GrooveStyle, type GrooveTemplate, type HarmonizeOptions, type HarmonizeResult, type HumanizeOptions, type MelodyNote, type MotifCell, type MotifContour, type MotifNote, type MotifOptions, type MotifTransform, type ProgFunction, type ProgStyle, type ProgressionOptions, type ProgressionPreset, type RhythmEvent, type RhythmOptions, type Section, type SubstituteOptions, type Substitution, type SubstitutionType, applyGrooveTemplate, developMotif, extractGrooveTemplate, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, modalInterchangePalette, negativeHarmonyMirror, onsetWeightCurve, progressions, progressionsByStyle, rhythmDensity, substituteChord, transformMotif };
+export { type BassLineOptions, type BassSegment, type BassStyle, type BorrowedChord, type CounterMelodyOptions, type DrumHit, type DrumRole, type DrumsOptions, type EuclideanKick, type GrooveFeel, type GrooveSlot, type GrooveStyle, type GrooveTemplate, type HarmonizeOptions, type HarmonizeResult, type HumanizeOptions, type MelodyNote, type MotifCell, type MotifContour, type MotifNote, type MotifOptions, type MotifTransform, type ProgFunction, type ProgStyle, type ProgressionOptions, type ProgressionPreset, type RhythmEvent, type RhythmOptions, type Section, type SubstituteOptions, type Substitution, type SubstitutionType, applyGrooveTemplate, developMotif, extractGrooveTemplate, generateBassLine, generateCounterMelody, generateDrums, generateMotif, generateProgression, generateRhythm, harmonizeMelody, humanize, modalInterchangePalette, negativeHarmonyMirror, onsetWeightCurve, progressions, progressionsByStyle, rhythmDensity, substituteChord, transformMotif };

package/dist/generate/index.js

@@ -15,19 +15,19 @@ import {
   progressionsByStyle,
   rhythmDensity,
   transformMotif
-} from "../chunk-R3S2LUBH.js";
-import "../chunk-BHUT2S5G.js";
-import "../chunk-MSWFZF7J.js";
+} from "../chunk-4MHA432G.js";
+import "../chunk-62QZKCJQ.js";
+import "../chunk-I5R7ZBJS.js";
 import {
   modalInterchangePalette,
   negativeHarmonyMirror,
   substituteChord
-} from "../chunk-GQKN5KDT.js";
-import "../chunk-LN7ZZMD2.js";
-import "../chunk-SDM3VJJ5.js";
-import "../chunk-A4532ZFR.js";
-import "../chunk-7Y7WF64D.js";
-import "../chunk-CCBLVAPK.js";
+} from "../chunk-IT2O4XFE.js";
+import "../chunk-CHMXELDS.js";
+import "../chunk-2ZWMSJH6.js";
+import "../chunk-EH6EM37U.js";
+import "../chunk-MIWO425M.js";
+import "../chunk-FBQK3ZQN.js";
 export {
   applyGrooveTemplate,
   developMotif,

package/dist/{index-BOBXBNwP.d.cts → index-BNlGP86A.d.cts}

@@ -154,4 +154,4 @@ declare function diatonicTriad(degree: number, key: KeyScale): Chord;
  */
 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 ChordSpan as b, chordFromDegree as c, chordPitchClasses as d, chordQualities as e, chordToneRole as f, diatonicSeventh as g, diatonicTriad as h, makeChord as m };

package/dist/{index-CP3wAfEH.d.ts → index-Bg5dYMmZ.d.ts}

@@ -1,4 +1,4 @@
-import { C as Chord } from './index-CM5W4rcm.js';
+import { C as Chord } from './index-Bt4tOUD9.js';
 
 /**
  * Harmonic role a pitch plays within a chord.

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

@@ -154,4 +154,4 @@ declare function diatonicTriad(degree: number, key: KeyScale): Chord;
  */
 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 ChordSpan as b, chordFromDegree as c, chordPitchClasses as d, chordQualities as e, chordToneRole as f, diatonicSeventh as g, diatonicTriad as h, makeChord as m };

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 };

package/dist/{index-D_ZTUNKp.d.cts → index-CpOsP1y9.d.cts}

@@ -1,7 +1,7 @@
 import { T as TimeSignature } from './index-Cl7mhOFM.cjs';
 import { K as KeyScale, N as NoteEvent } from './types-MGP29r3t.cjs';
-import { C as Chord, b as ChordSpan } from './index-BOBXBNwP.cjs';
-import { C as Cadence } from './function-r2sh-jOO.cjs';
+import { C as Chord, b as ChordSpan } from './index-BNlGP86A.cjs';
+import { C as Cadence } from './function-DYt4iKsn.cjs';
 
 /**
  * A chord occupying a half-open beat span.

package/dist/{index-DZ1M21do.d.cts → index-CxqBQtH1.d.cts}

@@ -1,5 +1,5 @@
 import { K as KeyScale } from './types-MGP29r3t.cjs';
-import { C as Chord } from './index-BOBXBNwP.cjs';
+import { C as Chord } from './index-BNlGP86A.cjs';
 
 /**
  * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
@@ -110,6 +110,7 @@ declare function evaluateSafety(q: SafetyQuery): SafetyResult;
  * @param pitchLow Lowest MIDI pitch to consider (inclusive).
  * @param pitchHigh Highest MIDI pitch to consider (inclusive).
  * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
+ * @throws If either bound is non-finite/non-integral, reversed, or exceeds the generation budget.
  * @example
  * ```ts
  * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';

package/dist/{index-BdeQ1r_p.d.cts → index-Dikst44v.d.cts}

@@ -1,4 +1,4 @@
-import { C as Chord } from './index-BOBXBNwP.cjs';
+import { C as Chord } from './index-BNlGP86A.cjs';
 
 /**
  * Harmonic role a pitch plays within a chord.

package/dist/{index-BMPxwjwV.d.ts → index-DxvARIP2.d.ts}

@@ -1,7 +1,7 @@
 import { T as TimeSignature } from './index-Cl7mhOFM.js';
 import { K as KeyScale, N as NoteEvent } from './types-MGP29r3t.js';
-import { C as Chord, b as ChordSpan } from './index-CM5W4rcm.js';
-import { C as Cadence } from './function-2bJW1Zp_.js';
+import { C as Chord, b as ChordSpan } from './index-Bt4tOUD9.js';
+import { C as Cadence } from './function-DVH4Eusr.js';
 
 /**
  * A chord occupying a half-open beat span.

package/dist/{index-BreoJRw0.d.ts → index-Jc0Ryi79.d.ts}

@@ -1,5 +1,5 @@
 import { K as KeyScale } from './types-MGP29r3t.js';
-import { C as Chord } from './index-CM5W4rcm.js';
+import { C as Chord } from './index-Bt4tOUD9.js';
 
 /**
  * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
@@ -110,6 +110,7 @@ declare function evaluateSafety(q: SafetyQuery): SafetyResult;
  * @param pitchLow Lowest MIDI pitch to consider (inclusive).
  * @param pitchHigh Highest MIDI pitch to consider (inclusive).
  * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
+ * @throws If either bound is non-finite/non-integral, reversed, or exceeds the generation budget.
  * @example
  * ```ts
  * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';

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 };