@libraz/libcantus 0.9.0

package/src/chord/index.ts

@@ -0,0 +1,292 @@
+import { scaleTonesInDegreeOrder } from '../scale/index.js';
+import type { KeyScale } from '../types.js';
+
+/** Chord quality identifiers understood by the chord builder. */
+export 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';
+
+/** A chord expressed as a root pitch class plus semitone offsets. */
+export type Chord = {
+  rootPc: number;
+  quality: ChordQuality;
+  intervals: number[];
+  bassPc?: number;
+};
+
+/** Semitone offsets from the root for each supported chord quality. */
+const QUALITY_INTERVALS: Record<ChordQuality, number[]> = {
+  maj: [0, 4, 7],
+  min: [0, 3, 7],
+  dim: [0, 3, 6],
+  aug: [0, 4, 8],
+  majb5: [0, 4, 6],
+  maj7: [0, 4, 7, 11],
+  min7: [0, 3, 7, 10],
+  dom7: [0, 4, 7, 10],
+  dim7: [0, 3, 6, 9],
+  m7b5: [0, 3, 6, 10],
+  minMaj7: [0, 3, 7, 11],
+  aug7: [0, 4, 8, 10],
+  augMaj7: [0, 4, 8, 11],
+  '6': [0, 4, 7, 9],
+  min6: [0, 3, 7, 9],
+  '6/9': [0, 4, 7, 9, 14],
+  sus2: [0, 2, 7],
+  sus4: [0, 5, 7],
+  add9: [0, 4, 7, 14],
+  add11: [0, 4, 7, 17],
+  maj9: [0, 4, 7, 11, 14],
+  min9: [0, 3, 7, 10, 14],
+  dom9: [0, 4, 7, 10, 14],
+  '7b9': [0, 4, 7, 10, 13],
+  '7#9': [0, 4, 7, 10, 15],
+  '7#11': [0, 4, 7, 10, 18],
+  '7b13': [0, 4, 7, 10, 20],
+  '11': [0, 7, 10, 14, 17],
+  '13': [0, 4, 7, 10, 14, 21],
+  '5': [0, 7],
+};
+
+/** Reduce a value to a pitch class in [0, 11]. */
+function pitchClass(value: number): number {
+  return ((Math.trunc(value) % 12) + 12) % 12;
+}
+
+/** All chord qualities the builder understands, longest templates last. */
+export function chordQualities(): ChordQuality[] {
+  return Object.keys(QUALITY_INTERVALS) as ChordQuality[];
+}
+
+/**
+ * Build a chord rooted on a diatonic scale degree.
+ *
+ * The root pitch class is the degree's diatonic pitch class in `key`; the
+ * quality's interval template is attached unchanged. Degrees beyond the scale
+ * length wrap around.
+ *
+ * @param degree 0-based scale degree of the chord root.
+ * @param ext Chord quality to apply.
+ * @param key Key context supplying the diatonic root.
+ * @returns The constructed chord.
+ */
+export function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScale): Chord {
+  const tones = scaleTonesInDegreeOrder(key);
+  const length = tones.length;
+  const index = length > 0 ? ((degree % length) + length) % length : 0;
+  const rootPc = tones[index] ?? pitchClass(key.rootPc);
+  return { rootPc, quality: ext, intervals: [...QUALITY_INTERVALS[ext]] };
+}
+
+/**
+ * Build a chord from an explicit root pitch class and quality.
+ *
+ * @param rootPc Root pitch class (0..11).
+ * @param quality Chord quality supplying the interval template.
+ * @param bassPc Optional slash-chord bass pitch class.
+ * @returns The constructed chord.
+ */
+export function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord {
+  const chord: Chord = {
+    rootPc: pitchClass(rootPc),
+    quality,
+    intervals: [...QUALITY_INTERVALS[quality]],
+  };
+  if (bassPc !== undefined) {
+    chord.bassPc = pitchClass(bassPc);
+  }
+  return chord;
+}
+
+/**
+ * Get the sorted, deduplicated pitch classes of a chord.
+ *
+ * @param chord The chord to enumerate.
+ * @returns The chord's pitch classes, sorted ascending in [0, 11].
+ */
+export function chordPitchClasses(chord: Chord): number[] {
+  const set = new Set<number>();
+  for (const interval of chord.intervals) {
+    set.add(pitchClass(chord.rootPc + interval));
+  }
+  return [...set].sort((a, b) => a - b);
+}
+
+/** The chord-tone offsets present in a chord, reduced to pitch-class space. */
+function chordToneOffsets(chord: Chord): Set<number> {
+  return new Set(chord.intervals.map((i) => ((i % 12) + 12) % 12));
+}
+
+/**
+ * Determine a pitch's harmonic role within a chord.
+ *
+ * The role is derived from the pitch's interval above the chord root, reduced
+ * modulo 12. A major sixth (9) reads as a `sixth` for sixth chords but as a
+ * `seventh` for a diminished-seventh chord; ninths and other tensions have no
+ * basic role and return null.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param chord The chord providing the root reference.
+ * @returns The chord-tone role, or null if the pitch has no basic role.
+ */
+export function chordToneRole(
+  pitch: number,
+  chord: Chord,
+): 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | null {
+  const interval = (pitchClass(pitch) - pitchClass(chord.rootPc) + 12) % 12;
+  const tones = chordToneOffsets(chord);
+  if (interval === 0) {
+    return 'root';
+  }
+  if (interval === 3 || interval === 4) {
+    return tones.has(interval) ? 'third' : null;
+  }
+  if (interval === 7) {
+    return tones.has(7) ? 'fifth' : null;
+  }
+  if (interval === 6) {
+    // A diminished fifth is the chord's fifth only when no perfect fifth is
+    // present; alongside a perfect fifth it is a #11 tension, not a fifth.
+    return tones.has(6) && !tones.has(7) ? 'fifth' : null;
+  }
+  if (interval === 8) {
+    // An augmented fifth is the chord's fifth only without a perfect fifth;
+    // alongside a perfect fifth it is a b13 tension, not a fifth.
+    return tones.has(8) && !tones.has(7) ? 'fifth' : null;
+  }
+  if (interval === 9) {
+    const hasHigherSeventh = tones.has(10) || tones.has(11);
+    const isDiminishedSeventh = tones.has(3) && tones.has(6) && !hasHigherSeventh;
+    if (isDiminishedSeventh) {
+      return 'seventh';
+    }
+    if (tones.has(9) && !hasHigherSeventh) {
+      return 'sixth';
+    }
+    return null;
+  }
+  if (interval === 10 || interval === 11) {
+    return tones.has(interval) ? 'seventh' : null;
+  }
+  return null;
+}
+
+/** Classify a stacked-thirds triad into a chord quality from its interval set. */
+function classifyTriad(thirdIc: number, fifthIc: number): ChordQuality {
+  if (thirdIc === 4 && fifthIc === 8) {
+    return 'aug';
+  }
+  if (thirdIc === 4 && fifthIc === 6) {
+    return 'majb5';
+  }
+  if (thirdIc === 3 && fifthIc === 6) {
+    return 'dim';
+  }
+  if (thirdIc === 3) {
+    return 'min';
+  }
+  return 'maj';
+}
+
+/** Classify a stacked-thirds seventh chord into a chord quality. */
+function classifySeventh(thirdIc: number, fifthIc: number, seventhIc: number): ChordQuality {
+  if (thirdIc === 3 && fifthIc === 6 && seventhIc === 9) {
+    return 'dim7';
+  }
+  if (thirdIc === 3 && fifthIc === 6 && seventhIc === 10) {
+    return 'm7b5';
+  }
+  if (thirdIc === 3 && seventhIc === 11) {
+    return 'minMaj7';
+  }
+  if (thirdIc === 3) {
+    return 'min7';
+  }
+  if (fifthIc === 8 && seventhIc === 10) {
+    return 'aug7';
+  }
+  if (fifthIc === 8 && seventhIc === 11) {
+    return 'augMaj7';
+  }
+  if (seventhIc === 11) {
+    return 'maj7';
+  }
+  return 'dom7';
+}
+
+/** Stack scale thirds from a scale degree into a chord of `size` notes. */
+function stackThirds(degree: number, key: KeyScale, size: 3 | 4): Chord {
+  const tones = scaleTonesInDegreeOrder(key);
+  const length = tones.length;
+  if (length === 0) {
+    return { rootPc: pitchClass(key.rootPc), quality: 'maj', intervals: [0, 4, 7] };
+  }
+  const idx = (step: number) => (((degree + step) % length) + length) % length;
+  const rootPc = tones[idx(0)] ?? pitchClass(key.rootPc);
+  const offsets = [0, 2, 4, 6].slice(0, size).map((step) => {
+    const pc = tones[idx(step)] ?? rootPc;
+    return (((pc - rootPc) % 12) + 12) % 12;
+  });
+  const thirdIc = offsets[1] ?? 4;
+  const fifthIc = offsets[2] ?? 7;
+  const quality =
+    size === 3
+      ? classifyTriad(thirdIc, fifthIc)
+      : classifySeventh(thirdIc, fifthIc, offsets[3] ?? 11);
+  return { rootPc, quality, intervals: offsets };
+}
+
+/**
+ * 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.
+ *
+ * @param degree 0-based scale degree of the chord root.
+ * @param key Key/scale context.
+ * @returns The diatonic triad.
+ */
+export function diatonicTriad(degree: number, key: KeyScale): Chord {
+  return stackThirds(degree, key, 3);
+}
+
+/**
+ * Build the diatonic seventh chord rooted on a scale degree.
+ *
+ * @param degree 0-based scale degree of the chord root.
+ * @param key Key/scale context.
+ * @returns The diatonic seventh chord.
+ */
+export function diatonicSeventh(degree: number, key: KeyScale): Chord {
+  return stackThirds(degree, key, 4);
+}

package/src/chordscale/index.ts

@@ -0,0 +1,316 @@
+import type { Chord } from '../chord/index.js';
+import { chordPitchClasses } from '../chord/index.js';
+import { NAMED_SCALES } from '../scale/index.js';
+
+/** Reduce a value to a pitch class in [0, 11]. */
+function pitchClass(value: number): number {
+  return ((Math.trunc(value) % 12) + 12) % 12;
+}
+
+/** Count the set bits (scale tones) in a 12-bit mode mask. */
+function popcount12(mask: number): number {
+  let count = 0;
+  for (let n = 0; n < 12; n += 1) {
+    count += (mask >> n) & 1;
+  }
+  return count;
+}
+
+/** Test whether a pitch class belongs to a mode mask rooted on `scaleRootPc`. */
+function maskHasPitchClass(mask: number, scaleRootPc: number, pc: number): boolean {
+  const offset = pitchClass(pc - scaleRootPc);
+  return ((mask >> offset) & 1) === 1;
+}
+
+/**
+ * Test whether every chord pitch class is contained in a scale.
+ *
+ * @param chordPcs The chord's pitch classes (0..11).
+ * @param scaleMask The scale's 12-bit mode mask.
+ * @param scaleRootPc The pitch class the mask is rooted on.
+ * @returns True if the scale is a superset of the chord.
+ */
+export function scaleMatchesChord(
+  chordPcs: number[],
+  scaleMask: number,
+  scaleRootPc: number,
+): boolean {
+  for (const pc of chordPcs) {
+    if (!maskHasPitchClass(scaleMask, scaleRootPc, pc)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** A named scale rooted on a pitch class that fits over a chord. */
+export type ChordScaleMatch = {
+  name: string;
+  rootPc: number;
+};
+
+/**
+ * List the scales that fit over a chord, best fit first.
+ *
+ * Only the chord root is considered as the scale root, matching the
+ * conventional chord-scale relationship. Every entry of {@link NAMED_SCALES}
+ * whose pitch-class set is a superset of the chord's is returned, ranked by
+ * fewest extra scale tones beyond the chord, then by scale size (heptatonic
+ * before larger scales), then by scale name. The chromatic scale is only
+ * returned as a fallback when no other scale contains the chord.
+ *
+ * @param chord The chord to fit scales over.
+ * @returns The matching scales rooted on the chord root, best fit first.
+ */
+export function chordScales(chord: Chord): ChordScaleMatch[] {
+  const chordPcs = chordPitchClasses(chord);
+  const rootPc = pitchClass(chord.rootPc);
+  const ranked: { name: string; extra: number; size: number }[] = [];
+  for (const name of Object.keys(NAMED_SCALES)) {
+    if (name === 'chromatic') {
+      continue;
+    }
+    const mask = NAMED_SCALES[name];
+    if (mask === undefined) {
+      continue;
+    }
+    if (scaleMatchesChord(chordPcs, mask, rootPc)) {
+      const size = popcount12(mask);
+      ranked.push({ name, extra: size - chordPcs.length, size });
+    }
+  }
+  if (ranked.length === 0) {
+    // No diatonic-style scale contains the chord; fall back to the chromatic
+    // scale, which trivially contains every pitch class.
+    if (NAMED_SCALES.chromatic !== undefined) {
+      return [{ name: 'chromatic', rootPc }];
+    }
+    return [];
+  }
+  ranked.sort((a, b) => {
+    if (a.extra !== b.extra) {
+      return a.extra - b.extra;
+    }
+    if (a.size !== b.size) {
+      return a.size - b.size;
+    }
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  });
+  return ranked.map((entry) => ({ name: entry.name, rootPc }));
+}
+
+/**
+ * List a scale's avoid notes over a chord.
+ *
+ * An avoid note is a non-chord scale tone that lies a semitone directly above a
+ * chord tone; sounding it against the chord clashes. The scale is rooted on the
+ * chord root. If the scale does not contain the chord, no avoid notes exist.
+ *
+ * @param chord The chord providing the chord tones.
+ * @param scaleName A key of {@link NAMED_SCALES}.
+ * @returns The avoid-note pitch classes, sorted ascending in [0, 11].
+ */
+export function avoidNotes(chord: Chord, scaleName: string): number[] {
+  const mask = NAMED_SCALES[scaleName];
+  if (mask === undefined) {
+    return [];
+  }
+  const rootPc = pitchClass(chord.rootPc);
+  const chordPcs = chordPitchClasses(chord);
+  if (!scaleMatchesChord(chordPcs, mask, rootPc)) {
+    return [];
+  }
+  const chordSet = new Set(chordPcs);
+  const avoid: number[] = [];
+  for (let pc = 0; pc < 12; pc += 1) {
+    if (!maskHasPitchClass(mask, rootPc, pc) || chordSet.has(pc)) {
+      continue;
+    }
+    if (chordSet.has(pitchClass(pc - 1))) {
+      avoid.push(pc);
+    }
+  }
+  return avoid.sort((a, b) => a - b);
+}
+
+/**
+ * List a scale's available tensions over a chord.
+ *
+ * Available tensions are scale tones that are neither chord tones nor avoid
+ * notes, i.e. the usable color tones (typically the 9/11/13 region). The scale
+ * is rooted on the chord root. If the scale does not contain the chord, there
+ * are no available tensions.
+ *
+ * @param chord The chord providing the chord tones.
+ * @param scaleName A key of {@link NAMED_SCALES}.
+ * @returns The available-tension pitch classes, sorted ascending in [0, 11].
+ */
+export function availableTensions(chord: Chord, scaleName: string): number[] {
+  const mask = NAMED_SCALES[scaleName];
+  if (mask === undefined) {
+    return [];
+  }
+  const rootPc = pitchClass(chord.rootPc);
+  const chordPcs = chordPitchClasses(chord);
+  if (!scaleMatchesChord(chordPcs, mask, rootPc)) {
+    return [];
+  }
+  const chordSet = new Set(chordPcs);
+  const avoidSet = new Set(avoidNotes(chord, scaleName));
+  const tensions: number[] = [];
+  for (let pc = 0; pc < 12; pc += 1) {
+    if (!maskHasPitchClass(mask, rootPc, pc) || chordSet.has(pc) || avoidSet.has(pc)) {
+      continue;
+    }
+    tensions.push(pc);
+  }
+  return tensions.sort((a, b) => a - b);
+}
+
+/** A scale fit over a chord together with its avoid notes and tensions. */
+export type ChordScaleReportEntry = {
+  name: string;
+  rootPc: number;
+  avoid: number[];
+  tensions: number[];
+};
+
+/**
+ * Report the best-fitting scales for a chord with their avoid notes and tensions.
+ *
+ * Combines {@link chordScales}, {@link avoidNotes}, and {@link availableTensions}
+ * into a single ergonomic result, ordered best fit first.
+ *
+ * @param chord The chord to analyze.
+ * @param limit Optional maximum number of scales to report; all by default.
+ * @returns One entry per reported scale, best fit first.
+ */
+export function chordScaleReport(chord: Chord, limit?: number): ChordScaleReportEntry[] {
+  const matches = chordScales(chord);
+  const chosen = limit === undefined ? matches : matches.slice(0, Math.max(0, limit));
+  return chosen.map((match) => ({
+    name: match.name,
+    rootPc: match.rootPc,
+    avoid: avoidNotes(chord, match.name),
+    tensions: availableTensions(chord, match.name),
+  }));
+}
+
+/** A chord paired with the scale chosen for it by {@link scalesForChanges}. */
+export type ScaleChoice = {
+  chord: Chord;
+  scale: ChordScaleMatch;
+};
+
+/**
+ * Small per-candidate penalty added in {@link scalesForChanges} so that, among
+ * choices of otherwise-equal transition cost, the tighter best-fit scale wins.
+ */
+const RANK_PENALTY = 0.01;
+
+/** Build the pitch-class set of a named scale rooted on `rootPc`. */
+function scalePitchClassSet(name: string, rootPc: number): Set<number> {
+  const mask = NAMED_SCALES[name];
+  const pcs = new Set<number>();
+  if (mask === undefined) {
+    return pcs;
+  }
+  for (let n = 0; n < 12; n += 1) {
+    if (((mask >> n) & 1) === 1) {
+      pcs.add(pitchClass(rootPc + n));
+    }
+  }
+  return pcs;
+}
+
+/** Count pitch classes that belong to exactly one of two sets. */
+function symmetricDifferenceSize(a: Set<number>, b: Set<number>): number {
+  let count = 0;
+  for (const pc of a) {
+    if (!b.has(pc)) {
+      count += 1;
+    }
+  }
+  for (const pc of b) {
+    if (!a.has(pc)) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+/**
+ * Choose one scale per chord across a progression, favoring continuity.
+ *
+ * Each chord's {@link chordScales} candidates form a stage in a Viterbi-style
+ * dynamic program. The transition cost between adjacent choices is the number
+ * of pitch classes that differ between their pitch-class sets (the symmetric
+ * difference), plus a small penalty for straying from a chord's best-fit scale
+ * so that ties break toward the tighter fit. The minimum-total-cost path is
+ * returned, one {@link ScaleChoice} per input chord in the original order.
+ *
+ * @param chords The chord sequence to choose scales for.
+ * @returns One scale choice per chord, in input order.
+ */
+export function scalesForChanges(chords: Chord[]): ScaleChoice[] {
+  if (chords.length === 0) {
+    return [];
+  }
+  const candidateLists = chords.map((chord) => chordScales(chord));
+  const pcSets = candidateLists.map((candidates) =>
+    candidates.map((match) => scalePitchClassSet(match.name, match.rootPc)),
+  );
+
+  const first = candidateLists[0] ?? [];
+  const dp: number[][] = [first.map((_, j) => j * RANK_PENALTY)];
+  const back: number[][] = [first.map(() => -1)];
+
+  for (let i = 1; i < candidateLists.length; i += 1) {
+    const candidates = candidateLists[i] ?? [];
+    const prevCosts = dp[i - 1] ?? [];
+    const prevSets = pcSets[i - 1] ?? [];
+    const curSets = pcSets[i] ?? [];
+    const stageCosts: number[] = [];
+    const stageBack: number[] = [];
+    for (let j = 0; j < candidates.length; j += 1) {
+      let bestCost = Number.POSITIVE_INFINITY;
+      let bestPrev = -1;
+      for (let k = 0; k < prevCosts.length; k += 1) {
+        const transition = symmetricDifferenceSize(
+          prevSets[k] ?? new Set(),
+          curSets[j] ?? new Set(),
+        );
+        const cost = (prevCosts[k] ?? 0) + transition;
+        if (cost < bestCost) {
+          bestCost = cost;
+          bestPrev = k;
+        }
+      }
+      stageCosts.push(bestCost + j * RANK_PENALTY);
+      stageBack.push(bestPrev);
+    }
+    dp.push(stageCosts);
+    back.push(stageBack);
+  }
+
+  const lastCosts = dp[dp.length - 1] ?? [];
+  let bestFinal = 0;
+  for (let j = 1; j < lastCosts.length; j += 1) {
+    if ((lastCosts[j] ?? Number.POSITIVE_INFINITY) < (lastCosts[bestFinal] ?? 0)) {
+      bestFinal = j;
+    }
+  }
+
+  const chosenIndices: number[] = new Array(candidateLists.length);
+  let current = bestFinal;
+  for (let i = candidateLists.length - 1; i >= 0; i -= 1) {
+    chosenIndices[i] = current;
+    current = back[i]?.[current] ?? -1;
+  }
+
+  return chords.map((chord, i) => {
+    const candidates = candidateLists[i] ?? [];
+    const scale = candidates[chosenIndices[i] ?? 0] ?? { name: 'chromatic', rootPc: chord.rootPc };
+    return { chord, scale };
+  });
+}