@libraz/libcantus 0.9.2 → 0.9.4

package/src/analyze/detect/index.ts

@@ -1,235 +0,0 @@
-/**
- * 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.
- */
-
-import type { KeyScale } from '../../core/types.js';
-import type { Chord, ChordQuality } from '../../theory/chord/index.js';
-import { chordPitchClasses, chordQualities, makeChord } from '../../theory/chord/index.js';
-import {
-  HARMONIC_MINOR_MASK,
-  MAJOR_MASK,
-  MELODIC_MINOR_MASK,
-  majorKey,
-  minorKey,
-  NATURAL_MINOR_MASK,
-} from '../../theory/scale/index.js';
-
-/**
- * A candidate chord interpretation of a pitch set.
- *
- * @category Recognition
- */
-export 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 the lowest note: 0 root position, 1 first, ... */
-  inversion: number;
-  /** Bass pitch class when inverted (the lowest note is not the root). */
-  bassPc?: number;
-};
-
-/**
- * A candidate key interpretation of a pitch-class set.
- *
- * @category Recognition
- */
-export type KeyMatch = {
-  key: KeyScale;
-  mode: 'major' | 'minor';
-  /** Fraction of input pitch classes that are in the scale, in [0, 1]. */
-  fit: number;
-};
-
-/** Reduce any integer to a pitch class in [0, 11]. */
-function pitchClass(value: number): number {
-  return ((Math.trunc(value) % 12) + 12) % 12;
-}
-
-/** Unique pitch classes of the input, sorted ascending. */
-function uniquePitchClasses(pitches: number[]): number[] {
-  return [...new Set(pitches.map(pitchClass))].sort((a, b) => a - b);
-}
-
-/**
- * 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
- */
-export function detectChord(pitches: number[]): ChordMatch[] {
-  const input = uniquePitchClasses(pitches);
-  if (input.length === 0) {
-    return [];
-  }
-  const bassPc = pitchClass(Math.min(...pitches));
-  const inputSet = new Set(input);
-  const matches: ChordMatch[] = [];
-  const qualities = chordQualities();
-  for (const rootPc of input) {
-    for (const quality of qualities) {
-      const chord = makeChord(rootPc, quality);
-      const tones = chordPitchClasses(chord);
-      const toneSet = new Set(tones);
-      const missingPcs = tones.filter((pc) => !inputSet.has(pc));
-      // Accept an exact-tone match, or one whose only absent tone is the perfect
-      // fifth; any other missing tone (third, sus tone, seventh, ...) rejects.
-      const fifthPc = pitchClass(rootPc + 7);
-      if (missingPcs.length > 1 || (missingPcs.length === 1 && missingPcs[0] !== fifthPc)) {
-        continue;
-      }
-      const extraPcs = input.filter((pc) => !toneSet.has(pc));
-      const bassIndex = chord.intervals.findIndex((iv) => pitchClass(rootPc + iv) === bassPc);
-      const inversion = bassIndex > 0 ? bassIndex : 0;
-      const match: ChordMatch = {
-        rootPc,
-        quality,
-        missingPcs,
-        extraPcs,
-        exact: extraPcs.length === 0 && missingPcs.length === 0,
-        inversion,
-      };
-      if (inversion > 0) {
-        match.bassPc = bassPc;
-      }
-      matches.push(match);
-    }
-  }
-  matches.sort((a, b) => {
-    if (a.extraPcs.length !== b.extraPcs.length) {
-      return a.extraPcs.length - b.extraPcs.length;
-    }
-    if (a.missingPcs.length !== b.missingPcs.length) {
-      return a.missingPcs.length - b.missingPcs.length;
-    }
-    // Prefer root position (the bass is the chord root) on a tie.
-    if ((a.inversion === 0) !== (b.inversion === 0)) {
-      return a.inversion === 0 ? -1 : 1;
-    }
-    const aSize = chordPitchClasses(makeChord(a.rootPc, a.quality)).length;
-    const bSize = chordPitchClasses(makeChord(b.rootPc, b.quality)).length;
-    return bSize - aSize;
-  });
-  return matches;
-}
-
-/**
- * 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
- */
-export function detectChordBest(pitches: number[]): Chord | null {
-  const best = detectChord(pitches)[0];
-  if (!best) {
-    return null;
-  }
-  return makeChord(best.rootPc, best.quality, best.bassPc);
-}
-
-/**
- * Minor-scale variants scored for each minor-key candidate. Scoring against all
- * three lets the raised sixth and seventh (e.g. the leading tone G# in A minor)
- * count toward their own tonic instead of only penalizing it.
- */
-const MINOR_MASK_VARIANTS = [NATURAL_MINOR_MASK, HARMONIC_MINOR_MASK, MELODIC_MINOR_MASK];
-
-/**
- * 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
- */
-export function detectKey(pitches: number[]): KeyMatch[] {
-  const input = uniquePitchClasses(pitches);
-  if (input.length === 0) {
-    return [];
-  }
-  const counts = new Map<number, number>();
-  for (const pc of pitches.map(pitchClass)) {
-    counts.set(pc, (counts.get(pc) ?? 0) + 1);
-  }
-  const total = pitches.length;
-  const results: (KeyMatch & { score: number })[] = [];
-  for (let tonic = 0; tonic < 12; tonic += 1) {
-    for (const mode of ['major', 'minor'] as const) {
-      const key = mode === 'major' ? majorKey(tonic) : minorKey(tonic);
-      const masks = mode === 'major' ? [MAJOR_MASK] : MINOR_MASK_VARIANTS;
-      // Score each scale variant and keep the best; ties keep the earlier
-      // (more diatonic) variant.
-      let inScale = 0;
-      let weighted = Number.NEGATIVE_INFINITY;
-      for (const mask of masks) {
-        let variantInScale = 0;
-        let variantWeighted = 0;
-        for (const pc of input) {
-          const offset = (pc - tonic + 12) % 12;
-          if ((mask >> offset) & 1) {
-            variantInScale += 1;
-          }
-        }
-        for (const [pc, count] of counts) {
-          const offset = (pc - tonic + 12) % 12;
-          if ((mask >> offset) & 1) {
-            variantWeighted += count;
-          }
-        }
-        if (variantWeighted > weighted) {
-          weighted = variantWeighted;
-          inScale = variantInScale;
-        }
-      }
-      weighted += (counts.get(tonic) ?? 0) * 0.5;
-      results.push({
-        key,
-        mode,
-        fit: inScale / input.length,
-        score: weighted / total,
-      });
-    }
-  }
-  results.sort((a, b) => b.score - a.score);
-  return results.map(({ key, mode, fit }) => ({ key, mode, fit }));
-}

package/src/analyze/functional/borrowed.ts

@@ -1,84 +0,0 @@
-/**
- * Borrowed chords (modal interchange) and the Neapolitan.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-import type { KeyScale } from '../../core/types.js';
-import type { Chord } from '../../theory/chord/index.js';
-import { HARMONIC_MINOR_MASK } from '../../theory/scale/index.js';
-import { isDiatonic, isMinorKey, parallelKey } from './function.js';
-import { isNeapolitan, mod12 } from './internal.js';
-
-/**
- * The origin of a recognized non-diatonic chord, or null when none applies.
- *
- * @category Functional Harmony
- */
-export type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
-
-/**
- * In a minor key, whether a non-diatonic chord is explained by the harmonic
- * minor scale on the same tonic (major V, V7, the raised-leading-tone viio).
- * Such chords are in-key chromatic alterations, not modal interchange.
- */
-function isHarmonicMinorAlteration(chord: Chord, key: KeyScale): boolean {
-  return (
-    isMinorKey(key) &&
-    isDiatonic(chord, { rootPc: mod12(key.rootPc), modeMask12: HARMONIC_MINOR_MASK })
-  );
-}
-
-/**
- * Whether a chord is borrowed from the parallel mode (modal interchange).
- *
- * True when the chord is not diatonic to `key` but is diatonic to its
- * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy
- * tonic and major IV in a minor key. Two non-diatonic families are excluded:
- * chords diatonic to neither mode (they are chromatic, not borrowed), and, in
- * a minor key, chords explained by the harmonic minor scale (the major
- * dominant and raised-leading-tone chords), which are in-key alterations
- * rather than interchange even though they happen to fit the parallel major.
- *
- * @param chord The chord to test.
- * @param key The prevailing key.
- * @returns True if the chord is borrowed from the parallel mode.
- * @category Functional Harmony
- */
-export function isBorrowedChord(chord: Chord, key: KeyScale): boolean {
-  if (isDiatonic(chord, key)) {
-    return false;
-  }
-  if (isHarmonicMinorAlteration(chord, key)) {
-    return false;
-  }
-  return isDiatonic(chord, parallelKey(key));
-}
-
-/**
- * Identify where a non-diatonic chord comes from.
- *
- * The Neapolitan (major triad on b2) is recognized first, since it sits
- * outside both parallel modes; parallel-mode borrowing follows the
- * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,
- * and unrecognized chromatic chords all yield null.
- *
- * @param chord The chord to classify.
- * @param key The prevailing key.
- * @returns The borrowing source, or null.
- * @category Functional Harmony
- */
-export function borrowedSource(chord: Chord, key: KeyScale): BorrowedSource {
-  if (isDiatonic(chord, key)) {
-    return null;
-  }
-  if (isNeapolitan(chord, key)) {
-    return 'neapolitan';
-  }
-  if (isBorrowedChord(chord, key)) {
-    return isMinorKey(key) ? 'parallel-major' : 'parallel-minor';
-  }
-  return null;
-}

package/src/analyze/functional/cadence.ts

@@ -1,66 +0,0 @@
-/**
- * Cadence detection between two successive chords.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-import type { KeyScale } from '../../core/types.js';
-import type { Chord } from '../../theory/chord/index.js';
-import { isMinorKey } from './function.js';
-import { mod12 } from './internal.js';
-
-/**
- * A recognized cadence type, or null when a chord pair forms none.
- *
- * @category Functional Harmony
- */
-export type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
-
-/**
- * Classify the cadence formed by moving from one chord to the next.
- *
- * - authentic: V (dominant a fifth above the tonic) to I
- * - plagal: IV (a fourth above the tonic) to I
- * - deceptive: V to the submediant (diatonic vi or borrowed bVI in major, VI in
- *   minor)
- * - half: any chord other than the dominant itself to V
- *
- * A static V-to-V repeat with no root motion is not a cadence and yields null.
- *
- * @param from The penultimate chord.
- * @param to The final chord.
- * @param key The prevailing key.
- * @returns The cadence type, or null.
- * @example
- * ```ts
- * import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';
- * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0)); // => 'authentic'
- * ```
- * @category Functional Harmony
- */
-export function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence {
-  const tonic = mod12(key.rootPc);
-  const fromOffset = mod12(from.rootPc - tonic);
-  const toOffset = mod12(to.rootPc - tonic);
-  // Deceptive targets: the diatonic submediant (vi at offset 9 in major, VI at
-  // offset 8 in minor) plus, in a major key, the borrowed flat-submediant bVI
-  // at offset 8.
-  const deceptiveTargets = isMinorKey(key) ? [8] : [8, 9];
-  if (fromOffset === 7 && toOffset === 0) {
-    return 'authentic';
-  }
-  if (fromOffset === 5 && toOffset === 0) {
-    return 'plagal';
-  }
-  if (fromOffset === 7 && deceptiveTargets.includes(toOffset)) {
-    return 'deceptive';
-  }
-  // A move to the dominant is a half cadence, but a no-root-motion V-to-V repeat
-  // is not a cadence at all.
-  if (toOffset === 7 && fromOffset !== 7) {
-    return 'half';
-  }
-  return null;
-}

package/src/analyze/functional/function.ts

@@ -1,184 +0,0 @@
-/**
- * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
- * mirroring, and full chord analysis.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-import type { KeyScale } from '../../core/types.js';
-import type { Chord, ChordQuality } from '../../theory/chord/index.js';
-import { chordPitchClasses, makeChord } from '../../theory/chord/index.js';
-import { isScaleTone, MAJOR_MASK, NATURAL_MINOR_MASK } from '../../theory/scale/index.js';
-import { type BorrowedSource, borrowedSource } from './borrowed.js';
-import { degreeRootPc, isNeapolitan, mod12 } from './internal.js';
-import { chordToRoman } from './roman.js';
-
-/**
- * The three broad harmonic functions of tonal music.
- *
- * @category Functional Harmony
- */
-export type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
-
-/** Harmonic function of each semitone offset above the tonic (major context). */
-const FUNCTION_BY_OFFSET: readonly HarmonicFunction[] = [
-  'tonic', // 0  I
-  'subdominant', // 1  bII (Neapolitan)
-  'subdominant', // 2  ii
-  'tonic', // 3  bIII
-  'tonic', // 4  iii
-  'subdominant', // 5  IV
-  'dominant', // 6  #IV / bV
-  'dominant', // 7  V
-  'subdominant', // 8  bVI
-  'tonic', // 9  vi
-  'subdominant', // 10 bVII
-  'dominant', // 11 vii
-];
-
-/**
- * Whether a key's scale has a minor third and no major third (a minor key).
- *
- * @category Functional Harmony
- */
-export function isMinorKey(key: KeyScale): boolean {
-  const hasMinorThird = (key.modeMask12 >> 3) & 1;
-  const hasMajorThird = (key.modeMask12 >> 4) & 1;
-  return Boolean(hasMinorThird) && !hasMajorThird;
-}
-
-/**
- * The harmonic function of a chord in a key, from its root's offset above the
- * tonic. The mapping follows common-practice major-key function and is a useful
- * approximation in minor and for borrowed chords.
- *
- * @param chord The chord.
- * @param key The prevailing key.
- * @returns The harmonic function.
- * @category Functional Harmony
- */
-export function functionOf(chord: Chord, key: KeyScale): HarmonicFunction {
-  return FUNCTION_BY_OFFSET[mod12(chord.rootPc - key.rootPc)] ?? 'tonic';
-}
-
-/**
- * The result of {@link analyzeChord}: function, borrowing, and Roman numeral.
- *
- * @category Functional Harmony
- */
-export type ChordAnalysis = {
-  function: HarmonicFunction;
-  borrowed: boolean;
-  source: BorrowedSource;
-  roman: string;
-};
-
-/**
- * Whether every pitch class of a chord belongs to the key's scale.
- *
- * The test is strict against the key's own mode mask: in a natural-minor key
- * the harmonic-minor dominant (major V) is *not* diatonic, since the raised
- * leading tone lies outside the mask. Borrowing predicates treat that case as
- * an in-key alteration separately (see {@link isBorrowedChord}).
- *
- * @param chord The chord to test.
- * @param key The prevailing key.
- * @returns True if all chord pitch classes are scale tones.
- * @category Functional Harmony
- */
-export function isDiatonic(chord: Chord, key: KeyScale): boolean {
-  return chordPitchClasses(chord).every((pc) => isScaleTone(pc, key));
-}
-
-/**
- * The parallel key: same tonic, opposite mode.
- *
- * A key with a minor third (natural/harmonic/melodic minor, dorian, phrygian)
- * maps to the parallel major; any other key maps to the parallel natural minor.
- *
- * @param key The key to mirror.
- * @returns The parallel major or natural-minor key on the same tonic.
- * @category Functional Harmony
- */
-export function parallelKey(key: KeyScale): KeyScale {
-  return {
-    rootPc: mod12(key.rootPc),
-    modeMask12: isMinorKey(key) ? MAJOR_MASK : NATURAL_MINOR_MASK,
-  };
-}
-
-/** Diminished-family qualities: diminished triad, dim7, half-diminished. */
-function isDiminishedQuality(quality: ChordQuality): boolean {
-  return quality === 'dim' || quality === 'dim7' || quality === 'm7b5';
-}
-
-/** Whether the chord's interval template carries a major third above the root. */
-function hasMajorThird(chord: Chord): boolean {
-  return chord.intervals.some((interval) => mod12(interval) === 4);
-}
-
-/**
- * Quality-aware harmonic function, refining the offset table where chord
- * quality disambiguates: diminished chords on the leading tone or the raised
- * subdominant resolve by semitone and act as dominants; the Neapolitan and the
- * major-third chords on bVI/bVII borrowed from the parallel minor act as
- * subdominant (predominant) harmony. All other chords keep {@link functionOf}.
- */
-function qualityAwareFunction(chord: Chord, key: KeyScale): HarmonicFunction {
-  const offset = mod12(chord.rootPc - key.rootPc);
-  if (isDiminishedQuality(chord.quality) && (offset === 11 || offset === 6)) {
-    return 'dominant';
-  }
-  if (isNeapolitan(chord, key)) {
-    return 'subdominant';
-  }
-  if (!isMinorKey(key) && hasMajorThird(chord) && (offset === 8 || offset === 10)) {
-    return 'subdominant';
-  }
-  return functionOf(chord, key);
-}
-
-/**
- * Analyze a chord in a key: harmonic function, borrowing, and Roman numeral.
- *
- * The function is quality-aware (see the predicates behind it), the source
- * follows {@link borrowedSource}, and the numeral comes from
- * {@link chordToRoman}. `borrowed` is true whenever a source is identified —
- * including the Neapolitan, which the stricter parallel-mode predicate
- * {@link isBorrowedChord} does not count.
- *
- * @param chord The chord to analyze.
- * @param key The prevailing key.
- * @returns The chord analysis.
- * @example
- * ```ts
- * import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';
- * analyzeChord(makeChord(7, 'dom7'), majorKey(0));
- * // { function: 'dominant', borrowed: false, source: null, roman: 'V7' }
- * ```
- * @category Functional Harmony
- */
-export function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis {
-  const source = borrowedSource(chord, key);
-  return {
-    function: qualityAwareFunction(chord, key),
-    borrowed: source !== null,
-    source,
-    roman: chordToRoman(chord, key),
-  };
-}
-
-/**
- * The secondary dominant (V7) that tonicizes a scale degree.
- *
- * @param targetDegree 0-based scale degree to tonicize.
- * @param key The prevailing key.
- * @returns A dominant-seventh chord a fifth above the target's root.
- * @category Functional Harmony
- */
-export function secondaryDominant(targetDegree: number, key: KeyScale): Chord {
-  const targetRoot = degreeRootPc(targetDegree + 1, key);
-  return makeChord(mod12(targetRoot + 7), 'dom7');
-}

package/src/analyze/functional/index.ts

@@ -1,23 +0,0 @@
-/**
- * Functional harmony: Roman-numeral parsing and formatting, harmonic function
- * (tonic / subdominant / dominant), cadence detection, and borrowed chords.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-export type { BorrowedSource } from './borrowed.js';
-export { borrowedSource, isBorrowedChord } from './borrowed.js';
-export type { Cadence } from './cadence.js';
-export { detectCadence } from './cadence.js';
-export type { ChordAnalysis, HarmonicFunction } from './function.js';
-export {
-  analyzeChord,
-  functionOf,
-  isDiatonic,
-  isMinorKey,
-  parallelKey,
-  secondaryDominant,
-} from './function.js';
-export { chordToRoman, romanToChord } from './roman.js';

package/src/analyze/functional/internal.ts

@@ -1,29 +0,0 @@
-/**
- * Shared helpers for the functional-harmony modules.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-import type { KeyScale } from '../../core/types.js';
-import type { Chord } from '../../theory/chord/index.js';
-import { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';
-
-export function mod12(n: number): number {
-  return ((n % 12) + 12) % 12;
-}
-
-/** Diatonic pitch class of a 1-based scale degree in a key. */
-export function degreeRootPc(degreeNumber: number, key: KeyScale): number {
-  const tones = scaleTonesInDegreeOrder(key);
-  if (tones.length === 0) {
-    return mod12(key.rootPc);
-  }
-  return tones[(degreeNumber - 1) % tones.length] ?? mod12(key.rootPc);
-}
-
-/** Whether a chord is the Neapolitan: a major triad on the flat second degree. */
-export function isNeapolitan(chord: Chord, key: KeyScale): boolean {
-  return mod12(chord.rootPc - key.rootPc) === 1 && chord.quality === 'maj';
-}