@libraz/libcantus 0.9.0

package/src/scale/index.ts

@@ -0,0 +1,215 @@
+import type { KeyScale } from '../types.js';
+
+/**
+ * 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.
+ */
+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}. */
+export const MAJOR_MASK = 0b101010110101;
+
+/** Mode mask for the natural minor (Aeolian) scale: offsets {0, 2, 3, 5, 7, 8, 10}. */
+export const NATURAL_MINOR_MASK = 0b010110101101;
+
+/** Harmonic minor: natural minor with a raised seventh — offsets {0,2,3,5,7,8,11}. */
+export const HARMONIC_MINOR_MASK = maskFromOffsets([0, 2, 3, 5, 7, 8, 11]);
+
+/** Ascending melodic minor: offsets {0,2,3,5,7,9,11}. */
+export const MELODIC_MINOR_MASK = maskFromOffsets([0, 2, 3, 5, 7, 9, 11]);
+
+/** Dorian mode: offsets {0,2,3,5,7,9,10}. */
+export const DORIAN_MASK = maskFromOffsets([0, 2, 3, 5, 7, 9, 10]);
+
+/** Phrygian mode: offsets {0,1,3,5,7,8,10}. */
+export const PHRYGIAN_MASK = maskFromOffsets([0, 1, 3, 5, 7, 8, 10]);
+
+/** Lydian mode: offsets {0,2,4,6,7,9,11}. */
+export const LYDIAN_MASK = maskFromOffsets([0, 2, 4, 6, 7, 9, 11]);
+
+/** Mixolydian mode: offsets {0,2,4,5,7,9,10}. */
+export const MIXOLYDIAN_MASK = maskFromOffsets([0, 2, 4, 5, 7, 9, 10]);
+
+/** Locrian mode: offsets {0,1,3,5,6,8,10}. */
+export const LOCRIAN_MASK = maskFromOffsets([0, 1, 3, 5, 6, 8, 10]);
+
+/** Major pentatonic: offsets {0,2,4,7,9}. */
+export const MAJOR_PENTATONIC_MASK = maskFromOffsets([0, 2, 4, 7, 9]);
+
+/** Minor pentatonic: offsets {0,3,5,7,10}. */
+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}. */
+export const BLUES_MASK = maskFromOffsets([0, 3, 5, 6, 7, 10]);
+
+/** Whole-tone scale: offsets {0,2,4,6,8,10}. */
+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}. */
+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}. */
+export const OCTATONIC_WHOLE_HALF_MASK = maskFromOffsets([0, 2, 3, 5, 6, 8, 9, 11]);
+
+/** Chromatic scale: all twelve pitch classes. */
+export const CHROMATIC_MASK = 0b111111111111;
+
+/** Named scale masks addressable by {@link scaleByName}. */
+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,
+};
+
+/** Build a `KeyScale` for a major key on the given root pitch class. */
+export function majorKey(rootPc: number): KeyScale {
+  return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: MAJOR_MASK };
+}
+
+/** Build a `KeyScale` for a natural-minor key on the given root pitch class. */
+export function minorKey(rootPc: number): KeyScale {
+  return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: NATURAL_MINOR_MASK };
+}
+
+/**
+ * Build a `KeyScale` from a named scale (see {@link NAMED_SCALES}).
+ *
+ * @param name The scale name, e.g. `'dorian'` or `'harmonicMinor'`.
+ * @param rootPc The root pitch class.
+ * @returns The key/scale.
+ * @throws If the name is not a known scale.
+ */
+export function scaleByName(name: string, rootPc: number): KeyScale {
+  const mask = NAMED_SCALES[name];
+  if (mask === undefined) {
+    throw new Error(`Unknown scale: ${name}`);
+  }
+  return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: mask };
+}
+
+/** Reduce a pitch (or pitch class) to a pitch class in [0, 11]. */
+function pitchClass(pitch: number): number {
+  return ((Math.trunc(pitch) % 12) + 12) % 12;
+}
+
+/** Scale offset of a pitch relative to the key root, in [0, 11]. */
+function scaleOffset(pitch: number, key: KeyScale): number {
+  return (pitchClass(pitch) - pitchClass(key.rootPc) + 12) % 12;
+}
+
+/**
+ * Test whether a pitch belongs to the scale.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param key The key/scale to test against.
+ * @returns True if the pitch class is a member of the scale.
+ */
+export function isScaleTone(pitch: number, key: KeyScale): boolean {
+  return ((key.modeMask12 >> scaleOffset(pitch, key)) & 1) === 1;
+}
+
+/**
+ * Find the nearest MIDI pitch whose pitch class is in the scale.
+ *
+ * The search expands symmetrically outward from `pitch`. On a tie (equal
+ * distance above and below) the lower pitch is returned.
+ *
+ * @param pitch MIDI pitch to snap.
+ * @param key The key/scale to snap to.
+ * @returns The nearest in-scale MIDI pitch.
+ */
+export function nearestScaleTone(pitch: number, key: KeyScale): number {
+  const base = Math.round(pitch);
+  for (let distance = 0; distance < 12; distance += 1) {
+    const lower = base - distance;
+    if (isScaleTone(lower, key)) {
+      return lower;
+    }
+    const higher = base + distance;
+    if (isScaleTone(higher, key)) {
+      return higher;
+    }
+  }
+  return base;
+}
+
+/**
+ * Get the 0-based scale degree of a pitch.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param key The key/scale to measure against.
+ * @returns The 0-based degree, or -1 if the pitch is not in the scale.
+ */
+export function pitchToScaleDegree(pitch: number, key: KeyScale): number {
+  const offset = scaleOffset(pitch, key);
+  if (((key.modeMask12 >> offset) & 1) === 0) {
+    return -1;
+  }
+  let degree = 0;
+  for (let n = 0; n < offset; n += 1) {
+    if (((key.modeMask12 >> n) & 1) === 1) {
+      degree += 1;
+    }
+  }
+  return degree;
+}
+
+/**
+ * List the pitch classes of a key's scale.
+ *
+ * @param key The key/scale to enumerate.
+ * @returns The member pitch classes, sorted ascending in [0, 11].
+ */
+export function diatonicPitchClasses(key: KeyScale): number[] {
+  const root = pitchClass(key.rootPc);
+  const pcs: number[] = [];
+  for (let n = 0; n < 12; n += 1) {
+    if (((key.modeMask12 >> n) & 1) === 1) {
+      pcs.push((root + n) % 12);
+    }
+  }
+  return pcs.sort((a, b) => a - b);
+}
+
+/**
+ * List the pitch classes of a key's scale in ascending scale-degree order.
+ *
+ * Degree 0 is the root; degrees follow the mask bits in offset order rather
+ * than sorted pitch-class order.
+ *
+ * @param key The key/scale to enumerate.
+ * @returns The member pitch classes ordered by scale degree.
+ */
+export function scaleTonesInDegreeOrder(key: KeyScale): number[] {
+  const root = pitchClass(key.rootPc);
+  const pcs: number[] = [];
+  for (let n = 0; n < 12; n += 1) {
+    if (((key.modeMask12 >> n) & 1) === 1) {
+      pcs.push((root + n) % 12);
+    }
+  }
+  return pcs;
+}

package/src/spelling/index.ts

@@ -0,0 +1,164 @@
+/**
+ * Spelling: derive letter-name notes for scales and chords from a spelled tonic.
+ *
+ * The theory core works in pitch classes, which cannot choose between (say) a
+ * G# and an Ab. Given a spelled tonic, this module assigns diatonic letters to
+ * scale degrees and chord tones so a C major scale spells as C D E F G A B and
+ * A harmonic minor spells its seventh as G#.
+ */
+
+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;
+
+/**
+ * Conventional degree assignment for each chromatic offset above the tonic.
+ *
+ * The letter is derived from the tonic's letter plus `degreeOffset` (so the
+ * spelling follows the key's diatonic letters), and the accidental is recomputed
+ * for that letter. This covers the flat-side alterations (b2, b3, b6, b7), the
+ * raised fourth (#4), and the raised degrees of a minor key: the raised sixth
+ * (#6) and the raised leading tone (#7). The latter two keep sharp-side minor
+ * keys spelling their raised degrees with the key-correct letter (e.g. F# minor
+ * spells its leading tone E#, not F).
+ *
+ * The `alter` field is illustrative only; `spellPitchClass` recomputes the
+ * accidental from the chosen letter.
+ */
+const CHROMATIC_SPELLING: Record<number, { degreeOffset: number; alter: number }> = {
+  1: { degreeOffset: 1, alter: -1 }, // b2
+  3: { degreeOffset: 2, alter: -1 }, // b3
+  6: { degreeOffset: 3, alter: 1 }, // #4
+  8: { degreeOffset: 5, alter: -1 }, // b6
+  9: { degreeOffset: 5, alter: 1 }, // #6 (raised sixth of a minor key)
+  10: { degreeOffset: 6, alter: -1 }, // b7
+  11: { degreeOffset: 6, alter: 1 }, // #7 (raised leading tone of a minor key)
+};
+
+function mod12(n: number): number {
+  return ((n % 12) + 12) % 12;
+}
+
+function mod7(n: number): number {
+  return ((n % 7) + 7) % 7;
+}
+
+/** Natural pitch class of a letter (0 = C .. 6 = B). */
+function naturalPc(letter: number): number {
+  return LETTER_SEMITONES[mod7(letter)] ?? 0;
+}
+
+/** Shortest signed alteration (in [-6, 6]) taking a letter's natural pc to `pc`. */
+function alterFor(letter: number, pc: number): number {
+  let d = mod12(pc - naturalPc(letter));
+  if (d > 6) {
+    d -= 12;
+  }
+  return d;
+}
+
+/** Whether the key's scale is a seven-note (heptatonic) scale. */
+function isHeptatonic(key: KeyScale): boolean {
+  return scaleTonesInDegreeOrder(key).length === 7;
+}
+
+/**
+ * Spell a single pitch class relative to a spelled tonic and key.
+ *
+ * Diatonic pitch classes take the scale's letter for their degree; the common
+ * chromatic tones (b2, b3, #4, b6, b7) and a minor key's raised degrees (#6, #7)
+ * take their conventional, key-correct accidental spelling; anything else falls
+ * back to a sharp spelling of the nearest natural.
+ *
+ * @param pc The pitch class to spell.
+ * @param tonic The spelled tonic (its letter anchors the spelling).
+ * @param key The key/scale.
+ * @returns The spelled note (without octave).
+ */
+export function spellPitchClass(pc: number, tonic: Note, key: KeyScale): Note {
+  const tonicPc = mod12(naturalPc(tonic.letter) + tonic.alter);
+  const offset = mod12(pc - tonicPc);
+  const tones = scaleTonesInDegreeOrder(key);
+
+  if (isHeptatonic(key)) {
+    const degree = tones.indexOf(mod12(pc));
+    if (degree >= 0) {
+      const letter = mod7(tonic.letter + degree);
+      return { letter, alter: alterFor(letter, pc) };
+    }
+    const chromatic = CHROMATIC_SPELLING[offset];
+    if (chromatic) {
+      const letter = mod7(tonic.letter + chromatic.degreeOffset);
+      return { letter, alter: alterFor(letter, pc) };
+    }
+  }
+
+  // Fallback: name the pitch class from the nearest natural, preferring a sharp.
+  for (let letter = 0; letter < 7; letter += 1) {
+    if (naturalPc(letter) === mod12(pc)) {
+      return { letter, alter: 0 };
+    }
+  }
+  const belowLetter = mod7([0, 0, 1, 1, 2, 3, 3, 4, 4, 5, 5, 6][mod12(pc)] ?? 0);
+  return { letter: belowLetter, alter: alterFor(belowLetter, pc) };
+}
+
+/**
+ * Spell every pitch class of a scale, in ascending scale-degree order.
+ *
+ * Correct for heptatonic scales (each degree gets the next letter). Non-standard
+ * scales are spelled tone-by-tone with a sharp preference.
+ *
+ * @param tonic The spelled tonic.
+ * @param key The key/scale.
+ * @returns Spelled notes, one per scale degree.
+ */
+export function spellScale(tonic: Note, key: KeyScale): Note[] {
+  return scaleTonesInDegreeOrder(key).map((pc) => spellPitchClass(pc, tonic, key));
+}
+
+/**
+ * Spell an arbitrary list of pitch classes relative to a key.
+ *
+ * @param pcs The pitch classes.
+ * @param tonic The spelled tonic.
+ * @param key The key/scale.
+ * @returns Spelled notes, in input order.
+ */
+export function spellPitchClasses(pcs: number[], tonic: Note, key: KeyScale): Note[] {
+  return pcs.map((pc) => spellPitchClass(pc, tonic, key));
+}
+
+/**
+ * Spell a chord's tones, in the chord's own (tertian) order, relative to a key.
+ *
+ * Diatonic chords spell exactly (e.g. G7 in C major -> G B D F). Chromatic chord
+ * tones take their conventional spelling; enharmonically ambiguous altered
+ * tensions may be spelled by the general convention rather than by chord
+ * function.
+ *
+ * @param chord The chord.
+ * @param tonic The spelled tonic of the key.
+ * @param key The key/scale.
+ * @returns Spelled chord tones, root first.
+ */
+export function spellChord(chord: Chord, tonic: Note, key: KeyScale): Note[] {
+  return chord.intervals.map((interval) =>
+    spellPitchClass(mod12(chord.rootPc + interval), tonic, key),
+  );
+}
+
+/**
+ * Convenience: render spelled notes as letter-name strings.
+ *
+ * @param notes The notes.
+ * @returns Their formatted names.
+ */
+export function noteNames(notes: Note[]): string[] {
+  return notes.map(formatNote);
+}

package/src/symbol/index.ts

@@ -0,0 +1,213 @@
+/**
+ * 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 { type Chord, type ChordQuality, makeChord } from '../chord/index.js';
+import { formatNote, midiToNote, noteToPitchClass, parseNote } from '../pitch/index.js';
+
+/** Matches a chord root: a letter A-G with an optional single-direction accidental. */
+const ROOT_RE = /^[A-G](?:#{1,2}|b{1,2})?/;
+
+/** Matches a bare note usable as a slash-chord bass (no octave). */
+const BASS_RE = /^[A-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;
+}
+
+/** Pitch class of a bare note token (letter plus optional accidental). */
+function bassPitchClass(token: string): number {
+  return noteToPitchClass(parseNote(token));
+}
+
+/**
+ * Parse a lead-sheet chord symbol into a {@link Chord}.
+ *
+ * Accepts `<root><quality>[/<bass>]`, e.g. `Cmaj7`, `F#m7b5`, `Bb7`, `C/G`,
+ * `C6/9`. The `/` after a quality is ambiguous between a slash bass and the
+ * `6/9` quality; it resolves to a bass only when the token following it is
+ * itself a valid note.
+ *
+ * @param text The chord symbol text.
+ * @returns The parsed chord.
+ * @throws If the root or quality is not recognized.
+ */
+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 rootPc = noteToPitchClass(parseNote(rootToken));
+  const rest = trimmed.slice(rootToken.length);
+
+  const slashIndex = rest.indexOf('/');
+  if (slashIndex === -1) {
+    const quality = QUALITY_MAP[rest];
+    if (quality === undefined) {
+      throw new Error(`Unrecognized chord quality: ${text}`);
+    }
+    return makeChord(rootPc, quality);
+  }
+
+  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 makeChord(rootPc, beforeQuality, bassPitchClass(after));
+  }
+
+  const combinedQuality = QUALITY_MAP[rest];
+  if (combinedQuality !== undefined) {
+    return makeChord(rootPc, combinedQuality);
+  }
+
+  throw new Error(`Unrecognized chord quality: ${text}`);
+}
+
+/**
+ * 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.
+ *
+ * @param chord The chord to format.
+ * @param opts Formatting options.
+ * @param opts.flats Prefer flat spellings over sharps for altered roots/basses.
+ * @returns The chord symbol text.
+ */
+export function formatChordSymbol(chord: Chord, opts?: { flats?: boolean }): string {
+  const spelling = opts?.flats ? 'flat' : 'sharp';
+  const rootNote = midiToNote(60 + pitchClass(chord.rootPc), spelling);
+  const rootName = formatNote({ letter: rootNote.letter, alter: rootNote.alter });
+  const suffix = CANONICAL_SUFFIX[chord.quality];
+  let symbol = `${rootName}${suffix}`;
+  if (chord.bassPc !== undefined && pitchClass(chord.bassPc) !== pitchClass(chord.rootPc)) {
+    const bassNote = midiToNote(60 + pitchClass(chord.bassPc), spelling);
+    symbol += `/${formatNote({ letter: bassNote.letter, alter: bassNote.alter })}`;
+  }
+  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.
+ */
+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);
+}