@libraz/libcantus 0.9.3 → 0.9.4

package/src/theory/symbol/index.ts

@@ -1,268 +0,0 @@
-/**
- * Lead-sheet chord symbol parsing and formatting.
- *
- * Bridges the informal `<root><quality>[/<bass>]` notation musicians write
- * (`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';
-
-/**
- * Matches a chord root: a letter A-G (case-insensitive, like {@link parseNote})
- * with an optional single-direction accidental.
- */
-const ROOT_RE = /^[A-Ga-g](?:#{1,2}|b{1,2})?/;
-
-/** Matches a bare note usable as a slash-chord bass (no octave). */
-const BASS_RE = /^[A-Ga-g](?:#{1,2}|b{1,2})?$/;
-
-/** Recognized quality suffixes, keyed by their exact lead-sheet spelling. */
-const QUALITY_MAP: Record<string, ChordQuality> = {
-  '': 'maj',
-  m: 'min',
-  min: 'min',
-  '-': 'min',
-  dim: 'dim',
-  '°': 'dim',
-  aug: 'aug',
-  '+': 'aug',
-  maj7: 'maj7',
-  M7: 'maj7',
-  Δ: 'maj7',
-  Δ7: 'maj7',
-  m7: 'min7',
-  min7: 'min7',
-  '-7': 'min7',
-  '7': 'dom7',
-  dim7: 'dim7',
-  '°7': 'dim7',
-  m7b5: 'm7b5',
-  ø: 'm7b5',
-  ø7: 'm7b5',
-  min7b5: 'm7b5',
-  mMaj7: 'minMaj7',
-  mM7: 'minMaj7',
-  minMaj7: 'minMaj7',
-  aug7: 'aug7',
-  '+7': 'aug7',
-  '7#5': 'aug7',
-  augMaj7: 'augMaj7',
-  augM7: 'augMaj7',
-  '+maj7': 'augMaj7',
-  '+M7': 'augMaj7',
-  majb5: 'majb5',
-  'maj(b5)': 'majb5',
-  '(b5)': 'majb5',
-  '6': '6',
-  m6: 'min6',
-  min6: 'min6',
-  '6/9': '6/9',
-  '69': '6/9',
-  sus2: 'sus2',
-  sus: 'sus4',
-  sus4: 'sus4',
-  add9: 'add9',
-  add11: 'add11',
-  maj9: 'maj9',
-  M9: 'maj9',
-  m9: 'min9',
-  min9: 'min9',
-  '9': 'dom9',
-  '7b9': '7b9',
-  '7#9': '7#9',
-  '7#11': '7#11',
-  '7b13': '7b13',
-  '11': '11',
-  '13': '13',
-  '5': '5',
-};
-
-/** Canonical lead-sheet suffix emitted for each chord quality when formatting. */
-const CANONICAL_SUFFIX: Record<ChordQuality, string> = {
-  maj: '',
-  min: 'm',
-  dim: 'dim',
-  aug: 'aug',
-  maj7: 'maj7',
-  min7: 'm7',
-  dom7: '7',
-  dim7: 'dim7',
-  m7b5: 'm7b5',
-  minMaj7: 'mMaj7',
-  aug7: 'aug7',
-  augMaj7: 'augMaj7',
-  majb5: 'maj(b5)',
-  '6': '6',
-  min6: 'm6',
-  '6/9': '6/9',
-  sus2: 'sus2',
-  sus4: 'sus4',
-  add9: 'add9',
-  add11: 'add11',
-  maj9: 'maj9',
-  min9: 'm9',
-  dom9: '9',
-  '7b9': '7b9',
-  '7#9': '7#9',
-  '7#11': '7#11',
-  '7b13': '7b13',
-  '11': '11',
-  '13': '13',
-  '5': '5',
-};
-
-/** Reduce a value to a pitch class in [0, 11]. */
-function pitchClass(value: number): number {
-  return ((Math.trunc(value) % 12) + 12) % 12;
-}
-
-/** Build a chord and record the parsed spellings as enharmonic hints. */
-function makeSpelledChord(root: Note, quality: ChordQuality, bass?: Note): Chord {
-  const chord = makeChord(
-    noteToPitchClass(root),
-    quality,
-    bass === undefined ? undefined : noteToPitchClass(bass),
-  );
-  chord.rootSpelling = { letter: root.letter, alter: root.alter };
-  if (bass !== undefined) {
-    chord.bassSpelling = { letter: bass.letter, alter: bass.alter };
-  }
-  return chord;
-}
-
-/**
- * Parse a lead-sheet chord symbol into a {@link Chord}.
- *
- * Accepts `<root><quality>[/<bass>]`, e.g. `Cmaj7`, `F#m7b5`, `Bb7`, `C/G`,
- * `C6/9`, `C6/9/E`. Root and bass letters are case-insensitive, matching
- * {@link parseNote}. A `/` is ambiguous between a slash bass and the `6/9`
- * quality; the text splits at the last `/` whose right-hand side is a valid
- * bare note preceded by a recognized quality, so `6/9` (with or without a
- * further slash bass) parses as a quality.
- *
- * The parsed chord carries the root/bass spellings as enharmonic hints
- * (`rootSpelling`/`bassSpelling`) so {@link formatChordSymbol} can reproduce
- * flat spellings such as `Bbmaj7` instead of respelling them with sharps.
- *
- * @param text The chord symbol text.
- * @returns The parsed chord.
- * @throws If the root or quality is not recognized.
- * @example
- * ```ts
- * import { parseChordSymbol, formatChordSymbol } from '@libraz/libcantus';
- * const c = parseChordSymbol('Bbmaj7');
- * formatChordSymbol(c); // 'Bbmaj7' — flat spelling is preserved on round-trip
- * ```
- * @category Chords
- */
-export function parseChordSymbol(text: string): Chord {
-  const trimmed = text.trim();
-  const rootMatch = ROOT_RE.exec(trimmed);
-  if (!rootMatch) {
-    throw new Error(`Invalid chord symbol: ${text}`);
-  }
-  const rootToken = rootMatch[0];
-  const rootNote = parseNote(rootToken);
-  const rest = trimmed.slice(rootToken.length);
-
-  // Split at the last '/' so the '6/9' quality's own slash never masks a
-  // trailing slash bass (e.g. 'C6/9/E').
-  const slashIndex = rest.lastIndexOf('/');
-  if (slashIndex !== -1) {
-    const before = rest.slice(0, slashIndex);
-    const after = rest.slice(slashIndex + 1);
-    const beforeQuality = QUALITY_MAP[before];
-    if (beforeQuality !== undefined && BASS_RE.test(after)) {
-      return makeSpelledChord(rootNote, beforeQuality, parseNote(after));
-    }
-  }
-
-  const quality = QUALITY_MAP[rest];
-  if (quality === undefined) {
-    throw new Error(`Unrecognized chord quality: ${text}`);
-  }
-  return makeSpelledChord(rootNote, quality);
-}
-
-/**
- * Name a pitch class, preferring a spelling hint when it is still valid.
- *
- * A hint is used only when no explicit sharp/flat preference was given and the
- * hint still resolves to `pc` (a stale hint left over after transposition is
- * ignored). Otherwise the pitch class is respelled from the requested table.
- */
-function pitchClassName(pc: number, hint: PitchSpelling | undefined, flats?: boolean): string {
-  if (flats === undefined && hint !== undefined && noteToPitchClass(hint) === pc) {
-    return formatNote(hint);
-  }
-  const note = midiToNote(60 + pc, flats ? 'flat' : 'sharp');
-  return formatNote({ letter: note.letter, alter: note.alter });
-}
-
-/**
- * Format a {@link Chord} as a lead-sheet chord symbol.
- *
- * The inverse of {@link parseChordSymbol}: each quality maps to one canonical
- * suffix spelling, and a slash bass is appended only when it differs from the
- * root. When the chord carries `rootSpelling`/`bassSpelling` hints (as chords
- * from {@link parseChordSymbol} do) and no explicit `flats` preference is
- * given, the hints are reused so flat symbols round-trip unchanged.
- *
- * @param chord The chord to format.
- * @param opts Formatting options.
- * @param opts.flats Prefer flat spellings over sharps for altered roots/basses;
- *   passing either `true` or `false` overrides any spelling hints.
- * @returns The chord symbol text.
- * @example
- * ```ts
- * import { makeChord, formatChordSymbol } from '@libraz/libcantus';
- * formatChordSymbol(makeChord(0, 'min7')); // 'Cm7'
- * ```
- * @category Chords
- */
-export function formatChordSymbol(chord: Chord, opts?: { flats?: boolean }): string {
-  const rootPc = pitchClass(chord.rootPc);
-  const rootName = pitchClassName(rootPc, chord.rootSpelling, opts?.flats);
-  const suffix = CANONICAL_SUFFIX[chord.quality];
-  let symbol = `${rootName}${suffix}`;
-  if (chord.bassPc !== undefined && pitchClass(chord.bassPc) !== rootPc) {
-    symbol += `/${pitchClassName(pitchClass(chord.bassPc), chord.bassSpelling, opts?.flats)}`;
-  }
-  return symbol;
-}
-
-/**
- * Transpose a chord symbol by a number of semitones.
- *
- * @param text The chord symbol text.
- * @param semitones Signed semitone offset to apply to the root and bass.
- * @param opts Formatting options for the result; see {@link formatChordSymbol}.
- * @returns The transposed chord symbol text.
- * @throws If `text` does not parse as a chord symbol.
- * @example
- * ```ts
- * import { transposeChordSymbol } from '@libraz/libcantus';
- * transposeChordSymbol('C/G', 2); // 'D/A'
- * ```
- * @category Chords
- */
-export function transposeChordSymbol(
-  text: string,
-  semitones: number,
-  opts?: { flats?: boolean },
-): string {
-  const chord = parseChordSymbol(text);
-  const transposed: Chord = { ...chord, rootPc: pitchClass(chord.rootPc + semitones) };
-  if (chord.bassPc !== undefined) {
-    transposed.bassPc = pitchClass(chord.bassPc + semitones);
-  }
-  return formatChordSymbol(transposed, opts);
-}

package/src/theory/voicing/index.ts

@@ -1,5 +0,0 @@
-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

@@ -1,168 +0,0 @@
-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

@@ -1,112 +0,0 @@
-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;
-}