@libraz/libcantus 0.9.1 → 0.9.3

package/src/theory/scale/masks.ts

@@ -0,0 +1,153 @@
+/**
+ * Build a 12-bit mode mask from a list of semitone offsets above the root.
+ *
+ * Bit 0 (the root) is always set, enforcing the `KeyScale` invariant that the
+ * root is a scale tone even when the offset list omits 0.
+ *
+ * @category Scales
+ */
+export function maskFromOffsets(offsets: readonly number[]): number {
+  let mask = 1;
+  for (const offset of offsets) {
+    mask |= 1 << (((offset % 12) + 12) % 12);
+  }
+  return mask;
+}
+
+/**
+ * Mode mask for the major (Ionian) scale: offsets {0, 2, 4, 5, 7, 9, 11}.
+ *
+ * @category Scales
+ */
+export const MAJOR_MASK = 0b101010110101;
+
+/**
+ * Mode mask for the natural minor (Aeolian) scale: offsets {0, 2, 3, 5, 7, 8, 10}.
+ *
+ * @category Scales
+ */
+export const NATURAL_MINOR_MASK = 0b010110101101;
+
+/**
+ * Harmonic minor: natural minor with a raised seventh — offsets {0,2,3,5,7,8,11}.
+ *
+ * @category Scales
+ */
+export const HARMONIC_MINOR_MASK = maskFromOffsets([0, 2, 3, 5, 7, 8, 11]);
+
+/**
+ * Ascending melodic minor: offsets {0,2,3,5,7,9,11}.
+ *
+ * @category Scales
+ */
+export const MELODIC_MINOR_MASK = maskFromOffsets([0, 2, 3, 5, 7, 9, 11]);
+
+/**
+ * Dorian mode: offsets {0,2,3,5,7,9,10}.
+ *
+ * @category Scales
+ */
+export const DORIAN_MASK = maskFromOffsets([0, 2, 3, 5, 7, 9, 10]);
+
+/**
+ * Phrygian mode: offsets {0,1,3,5,7,8,10}.
+ *
+ * @category Scales
+ */
+export const PHRYGIAN_MASK = maskFromOffsets([0, 1, 3, 5, 7, 8, 10]);
+
+/**
+ * Lydian mode: offsets {0,2,4,6,7,9,11}.
+ *
+ * @category Scales
+ */
+export const LYDIAN_MASK = maskFromOffsets([0, 2, 4, 6, 7, 9, 11]);
+
+/**
+ * Mixolydian mode: offsets {0,2,4,5,7,9,10}.
+ *
+ * @category Scales
+ */
+export const MIXOLYDIAN_MASK = maskFromOffsets([0, 2, 4, 5, 7, 9, 10]);
+
+/**
+ * Locrian mode: offsets {0,1,3,5,6,8,10}.
+ *
+ * @category Scales
+ */
+export const LOCRIAN_MASK = maskFromOffsets([0, 1, 3, 5, 6, 8, 10]);
+
+/**
+ * Major pentatonic: offsets {0,2,4,7,9}.
+ *
+ * @category Scales
+ */
+export const MAJOR_PENTATONIC_MASK = maskFromOffsets([0, 2, 4, 7, 9]);
+
+/**
+ * Minor pentatonic: offsets {0,3,5,7,10}.
+ *
+ * @category Scales
+ */
+export const MINOR_PENTATONIC_MASK = maskFromOffsets([0, 3, 5, 7, 10]);
+
+/**
+ * Hexatonic blues scale: minor pentatonic plus the flat-fifth — {0,3,5,6,7,10}.
+ *
+ * @category Scales
+ */
+export const BLUES_MASK = maskFromOffsets([0, 3, 5, 6, 7, 10]);
+
+/**
+ * Whole-tone scale: offsets {0,2,4,6,8,10}.
+ *
+ * @category Scales
+ */
+export const WHOLE_TONE_MASK = maskFromOffsets([0, 2, 4, 6, 8, 10]);
+
+/**
+ * Octatonic (half-step first): offsets {0,1,3,4,6,7,9,10}.
+ *
+ * @category Scales
+ */
+export const OCTATONIC_HALF_WHOLE_MASK = maskFromOffsets([0, 1, 3, 4, 6, 7, 9, 10]);
+
+/**
+ * Octatonic (whole-step first): offsets {0,2,3,5,6,8,9,11}.
+ *
+ * @category Scales
+ */
+export const OCTATONIC_WHOLE_HALF_MASK = maskFromOffsets([0, 2, 3, 5, 6, 8, 9, 11]);
+
+/**
+ * Chromatic scale: all twelve pitch classes.
+ *
+ * @category Scales
+ */
+export const CHROMATIC_MASK = 0b111111111111;
+
+/**
+ * Named scale masks addressable by {@link scaleByName}.
+ *
+ * @category Scales
+ */
+export const NAMED_SCALES: Record<string, number> = {
+  major: MAJOR_MASK,
+  ionian: MAJOR_MASK,
+  naturalMinor: NATURAL_MINOR_MASK,
+  aeolian: NATURAL_MINOR_MASK,
+  harmonicMinor: HARMONIC_MINOR_MASK,
+  melodicMinor: MELODIC_MINOR_MASK,
+  dorian: DORIAN_MASK,
+  phrygian: PHRYGIAN_MASK,
+  lydian: LYDIAN_MASK,
+  mixolydian: MIXOLYDIAN_MASK,
+  locrian: LOCRIAN_MASK,
+  majorPentatonic: MAJOR_PENTATONIC_MASK,
+  minorPentatonic: MINOR_PENTATONIC_MASK,
+  blues: BLUES_MASK,
+  wholeTone: WHOLE_TONE_MASK,
+  octatonicHalfWhole: OCTATONIC_HALF_WHOLE_MASK,
+  octatonicWholeHalf: OCTATONIC_WHOLE_HALF_MASK,
+  chromatic: CHROMATIC_MASK,
+};

package/src/{spelling → theory/spelling}/index.ts

@@ -7,11 +7,11 @@
  * A harmonic minor spells its seventh as G#.
  */
 
+import type { Note } from '../../core/pitch/index.js';
+import { formatNote } from '../../core/pitch/index.js';
+import type { KeyScale } from '../../core/types.js';
 import type { Chord } from '../chord/index.js';
-import type { Note } from '../pitch/index.js';
-import { formatNote } from '../pitch/index.js';
 import { scaleTonesInDegreeOrder } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
 
 /** Semitone offset of each natural letter above C: C D E F G A B. */
 const LETTER_SEMITONES = [0, 2, 4, 5, 7, 9, 11] as const;
@@ -143,6 +143,74 @@ export function spellPitchClasses(pcs: number[], tonic: Note, key: KeyScale): No
   return pcs.map((pc) => spellPitchClass(pc, tonic, key));
 }
 
+/**
+ * Diatonic letter distance implied by a chord interval.
+ *
+ * Chord intervals are not merely pitch-class distances: 6 is a diminished
+ * fifth in the basic chord templates while 18 is an augmented eleventh, and 9
+ * is a diminished seventh in `dim7` but a sixth elsewhere. Keeping that
+ * distinction is what prevents functional chord tones from being respelled by
+ * their nearest key pitch (for example G# becoming Ab in E7).
+ */
+function chordLetterOffset(interval: number, chord: Chord): number {
+  switch (interval) {
+    case 0:
+    case 12:
+      return 0;
+    case 1:
+    case 2:
+    case 13:
+    case 14:
+      return 1;
+    case 3:
+    case 4:
+    case 15:
+    case 16:
+      return 2;
+    case 5:
+    case 17:
+    case 18:
+      return 3;
+    case 6:
+    case 7:
+    case 8:
+    case 19:
+      return 4;
+    case 9:
+      return chord.quality === 'dim7' ? 6 : 5;
+    case 20:
+    case 21:
+      return 5;
+    case 10:
+    case 11:
+    case 22:
+    case 23:
+      return 6;
+    default: {
+      // Unknown/custom interval data gets the nearest conventional diatonic
+      // distance. Public builders use the explicit cases above.
+      const octaves = Math.floor(Math.max(0, interval) / 12);
+      const simple = mod12(interval);
+      const simpleOffset = [0, 1, 1, 2, 2, 3, 4, 4, 4, 5, 6, 6][simple] ?? 0;
+      return octaves * 7 + simpleOffset;
+    }
+  }
+}
+
+/**
+ * Spell chord tones from an already chosen root spelling.
+ *
+ * This is exported for the model layer's inversion support; the package
+ * barrels intentionally expose the key-aware {@link spellChord} entry point.
+ */
+export function spellChordFromRoot(chord: Chord, root: Note): Note[] {
+  return chord.intervals.map((interval) => {
+    const letter = mod7(root.letter + chordLetterOffset(interval, chord));
+    const pc = mod12(chord.rootPc + interval);
+    return { letter, alter: alterFor(letter, pc) };
+  });
+}
+
 /**
  * Spell a chord's tones, in the chord's own (tertian) order, relative to a key.
  *
@@ -165,9 +233,8 @@ export function spellPitchClasses(pcs: number[], tonic: Note, key: KeyScale): No
  * @category Pitch & Intervals
  */
 export function spellChord(chord: Chord, tonic: Note, key: KeyScale): Note[] {
-  return chord.intervals.map((interval) =>
-    spellPitchClass(mod12(chord.rootPc + interval), tonic, key),
-  );
+  const root = spellPitchClass(chord.rootPc, tonic, key);
+  return spellChordFromRoot(chord, root);
 }
 
 /**

package/src/{symbol → theory/symbol}/index.ts

@@ -5,8 +5,15 @@
  * (`Cmaj7`, `F#m7b5`, `Bb7`, `C/G`) and the library's structured {@link Chord}
  * type, so callers can accept/emit plain text at the edges of the API.
  */
+
+import {
+  formatNote,
+  midiToNote,
+  type Note,
+  noteToPitchClass,
+  parseNote,
+} from '../../core/pitch/index.js';
 import { type Chord, type ChordQuality, makeChord, type PitchSpelling } from '../chord/index.js';
-import { formatNote, midiToNote, type Note, noteToPitchClass, parseNote } from '../pitch/index.js';
 
 /**
  * Matches a chord root: a letter A-G (case-insensitive, like {@link parseNote})

package/src/theory/voicing/index.ts

@@ -0,0 +1,5 @@
+export { nextVoicing, voiceLeadingCost } from './leading.js';
+export type { VoiceRange, VoicingOptions } from './satb.js';
+export { SATB_RANGES, voiceChord, voiceProgression } from './satb.js';
+export type { StyledVoicingOptions, VoicingStyle } from './styled.js';
+export { voiceChordStyled } from './styled.js';

package/src/theory/voicing/internal.ts

@@ -0,0 +1,168 @@
+import type { Chord } from '../chord/index.js';
+import { chordPitchClasses } from '../chord/index.js';
+import {
+  createsParallelPerfect,
+  createsVoiceCrossing,
+  createsVoiceOverlap,
+  exceedsSpacing,
+} from '../counterpoint/index.js';
+import type { VoiceRange } from './satb.js';
+
+/** Default maximum spacing between adjacent upper voices (one octave). */
+export const DEFAULT_MAX_SPACING = 12;
+
+/** Score penalty per counterpoint violation between consecutive voicings. */
+export const VIOLATION_PENALTY = 1000;
+/** Score penalty per chord tone absent from a voicing. */
+const MISSING_TONE_PENALTY = 500;
+/** Score penalty per doubled tone that is neither the root nor the fifth. */
+const POOR_DOUBLING_PENALTY = 4;
+/** Hard cap on candidate voicings evaluated per chord, keeping the search bounded. */
+const MAX_CANDIDATES = 4000;
+
+/** Reduce a value to a pitch class in [0, 11]. */
+export function pitchClass(value: number): number {
+  return ((Math.trunc(value) % 12) + 12) % 12;
+}
+
+/**
+ * All MIDI pitches of a pitch class inside an inclusive range, ordered from the
+ * centre of the range outward (ties break toward the lower pitch). Enumerating
+ * centre-outward keeps the candidate set balanced around the register when it
+ * is truncated at {@link MAX_CANDIDATES}, instead of skewing to the low octaves
+ * that a plain ascending scan would visit first.
+ */
+function pitchesForPc(pc: number, range: VoiceRange): number[] {
+  const result: number[] = [];
+  for (let midi = Math.ceil(range.min); midi <= range.max; midi += 1) {
+    if (pitchClass(midi) === pc) {
+      result.push(midi);
+    }
+  }
+  const center = (range.min + range.max) / 2;
+  return result.sort((a, b) => {
+    const da = Math.abs(a - center);
+    const db = Math.abs(b - center);
+    return da === db ? a - b : da - db;
+  });
+}
+
+/**
+ * Enumerate candidate voicings for a chord: the bass takes the chord's bass
+ * (or root) pitch class at each available octave, and each upper voice takes
+ * any chord pitch class within its range. Candidates are built in ascending
+ * voice order and pruned to exclude voice crossings and over-wide adjacent
+ * spacing (the bass–tenor pair is allowed an extra octave, per convention).
+ * Enumeration is deterministic and capped at {@link MAX_CANDIDATES}.
+ */
+export function enumerateVoicings(
+  chord: Chord,
+  ranges: VoiceRange[],
+  maxSpacing: number,
+): number[][] {
+  const chordPcs = chordPitchClasses(chord);
+  const bassPc = pitchClass(chord.bassPc ?? chord.rootPc);
+  const results: number[][] = [];
+  const current: number[] = [];
+  const build = (voice: number): void => {
+    if (results.length >= MAX_CANDIDATES) {
+      return;
+    }
+    if (voice === ranges.length) {
+      results.push([...current]);
+      return;
+    }
+    const range = ranges[voice];
+    if (range === undefined) {
+      return;
+    }
+    const pcs = voice === 0 ? [bassPc] : chordPcs;
+    const prev = current[voice - 1];
+    for (const pc of pcs) {
+      for (const pitch of pitchesForPc(pc, range)) {
+        if (prev !== undefined) {
+          if (pitch < prev) {
+            continue; // would cross below the next lower voice
+          }
+          const spacingLimit = voice === 1 ? maxSpacing + 12 : maxSpacing;
+          if (pitch - prev > spacingLimit) {
+            continue;
+          }
+        }
+        current.push(pitch);
+        build(voice + 1);
+        current.pop();
+      }
+    }
+  };
+  build(0);
+  return results;
+}
+
+/**
+ * Structural quality penalty of a single voicing: heavily penalize missing
+ * chord tones, mildly penalize doubling anything other than the root or fifth.
+ */
+export function structuralPenalty(pitches: number[], chord: Chord): number {
+  const counts = new Map<number, number>();
+  for (const pitch of pitches) {
+    const pc = pitchClass(pitch);
+    counts.set(pc, (counts.get(pc) ?? 0) + 1);
+  }
+  let penalty = 0;
+  for (const pc of chordPitchClasses(chord)) {
+    if (!counts.has(pc)) {
+      penalty += MISSING_TONE_PENALTY;
+    }
+  }
+  const rootPc = pitchClass(chord.rootPc);
+  const fifthPc = pitchClass(chord.rootPc + 7);
+  for (const [pc, count] of counts) {
+    if (count > 1 && pc !== rootPc && pc !== fifthPc) {
+      penalty += (count - 1) * POOR_DOUBLING_PENALTY;
+    }
+  }
+  return penalty;
+}
+
+/**
+ * Count counterpoint violations between two consecutive voicings of equal
+ * length: parallel perfects (fifths and octaves alike, since octaves are the
+ * perfect-class-zero case of {@link createsParallelPerfect}) on every voice
+ * pair, voice crossings in the new voicing, and — on adjacent pairs — voice
+ * overlaps and over-wide spacing between upper voices.
+ */
+export function violationCount(prev: number[], cur: number[], maxSpacing: number): number {
+  let count = 0;
+  for (let lower = 0; lower < cur.length; lower += 1) {
+    for (let upper = lower + 1; upper < cur.length; upper += 1) {
+      const prevLower = prev[lower];
+      const prevUpper = prev[upper];
+      const curLower = cur[lower];
+      const curUpper = cur[upper];
+      if (
+        prevLower === undefined ||
+        prevUpper === undefined ||
+        curLower === undefined ||
+        curUpper === undefined
+      ) {
+        continue;
+      }
+      if (createsParallelPerfect(prevUpper, curUpper, prevLower, curLower)) {
+        count += 1;
+      }
+      if (createsVoiceCrossing(curUpper, curLower)) {
+        count += 1;
+      }
+      if (upper === lower + 1) {
+        if (createsVoiceOverlap(prevUpper, curUpper, prevLower, curLower)) {
+          count += 1;
+        }
+        if (lower > 0 && exceedsSpacing(curUpper, curLower, maxSpacing)) {
+          count += 1;
+        }
+      }
+    }
+  }
+  return count;
+}

package/src/theory/voicing/leading.ts

@@ -0,0 +1,112 @@
+import type { Chord } from '../chord/index.js';
+import { createsHiddenParallelPerfect } from '../counterpoint/index.js';
+import {
+  DEFAULT_MAX_SPACING,
+  enumerateVoicings,
+  structuralPenalty,
+  VIOLATION_PENALTY,
+  violationCount,
+} from './internal.js';
+import type { VoicingOptions } from './satb.js';
+import { resolveRanges } from './satb.js';
+
+/**
+ * Moderate penalty for a hidden/direct perfect fifth or octave reached on the
+ * outer-voice (bass–soprano) pair. Unlike a true parallel perfect it is
+ * discouraged rather than forbidden, so the weight sits alongside voice-leading
+ * motion rather than the hard {@link VIOLATION_PENALTY}.
+ */
+const HIDDEN_PERFECT_PENALTY = 6;
+
+/**
+ * Total voice-leading cost between two voicings: the sum of absolute semitone
+ * motion across voices, plus a moderate {@link HIDDEN_PERFECT_PENALTY} when the
+ * outer-voice (bass–soprano) pair reaches a hidden/direct perfect fifth or
+ * octave by similar motion. The arrays must be the same length; when they
+ * differ the voicings are not comparable and the cost is `Infinity`.
+ *
+ * @param from The previous voicing, one MIDI pitch per voice.
+ * @param to The next voicing, one MIDI pitch per voice.
+ * @returns The summed absolute motion (plus any hidden-perfect penalty), or
+ *   `Infinity` when lengths differ.
+ * @category Voicing & Counterpoint
+ */
+export function voiceLeadingCost(from: number[], to: number[]): number {
+  if (from.length !== to.length) {
+    return Number.POSITIVE_INFINITY;
+  }
+  let total = 0;
+  for (let i = 0; i < from.length; i += 1) {
+    const a = from[i];
+    const b = to[i];
+    if (a === undefined || b === undefined) {
+      continue;
+    }
+    total += Math.abs(b - a);
+  }
+  // Discourage hidden/direct perfects between the outermost voices, where they
+  // are most audible. True parallels are handled (and forbidden) elsewhere.
+  if (from.length >= 2) {
+    const bassPrev = from[0];
+    const bassCur = to[0];
+    const sopPrev = from[from.length - 1];
+    const sopCur = to[to.length - 1];
+    if (
+      bassPrev !== undefined &&
+      bassCur !== undefined &&
+      sopPrev !== undefined &&
+      sopCur !== undefined &&
+      createsHiddenParallelPerfect(bassPrev, bassCur, sopPrev, sopCur)
+    ) {
+      total += HIDDEN_PERFECT_PENALTY;
+    }
+  }
+  return total;
+}
+
+/**
+ * Voice a single chord to follow smoothly from an arbitrary current voicing.
+ *
+ * Candidate voicings of `chord` are enumerated within ranges taken from `opts`,
+ * or — when neither `voices` nor `ranges` is given — from a one-octave window
+ * around each pitch of `current` (so the result matches `current`'s voice
+ * count). Each candidate is scored by structural quality, voice-leading motion
+ * from `current`, and a large penalty per counterpoint violation; the lowest
+ * scoring candidate is returned, ascending.
+ *
+ * @param current The current voicing to lead from, ascending (index 0 = lowest).
+ * @param chord The next chord to voice.
+ * @param opts Voicing options; when omitted, ranges follow `current`'s span.
+ * @returns The chosen voicing, ascending with one MIDI pitch per voice.
+ * @throws If no voicing fits the derived ranges.
+ * @category Voicing & Counterpoint
+ */
+export function nextVoicing(current: number[], chord: Chord, opts?: VoicingOptions): number[] {
+  const ranges =
+    opts?.ranges !== undefined || opts?.voices !== undefined
+      ? resolveRanges(opts)
+      : current.map((pitch) => {
+          // Window one octave around each current pitch, clamped so extreme-low
+          // or extreme-high input can never yield MIDI outside [0, 127].
+          const centre = Math.min(127, Math.max(0, pitch));
+          return { min: Math.max(0, centre - 12), max: Math.min(127, centre + 12) };
+        });
+  const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
+  const candidates = enumerateVoicings(chord, ranges, maxSpacing);
+  let best: number[] | undefined;
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const score =
+      structuralPenalty(candidate, chord) +
+      voiceLeadingCost(current, candidate) +
+      VIOLATION_PENALTY * violationCount(current, candidate, maxSpacing);
+    if (score < bestScore) {
+      bestScore = score;
+      best = candidate;
+    }
+  }
+  if (best === undefined) {
+    throw new Error('no voicing satisfies the given ranges');
+  }
+  return best;
+}