@libraz/libcantus 0.9.0

package/src/motif/index.ts

@@ -0,0 +1,321 @@
+import type { Chord } from '../chord/index.js';
+import { chordPitchClasses } from '../chord/index.js';
+import { isScaleTone, nearestScaleTone } from '../scale/index.js';
+import type { ChordTimeline } from '../timeline/index.js';
+import type { KeyScale } from '../types.js';
+
+/** A transformation applicable to a motif cell. */
+export type MotifTransform =
+  | 'transposeDiatonic'
+  | 'transposeChromatic'
+  | 'invert'
+  | 'retrograde'
+  | 'augment'
+  | 'diminish'
+  | 'sequence';
+
+/** A single note within a motif cell. */
+export type MotifNote = {
+  pitch: number;
+  startBeat: number;
+  durationBeat: number;
+};
+
+/** A short melodic cell. */
+export type MotifCell = {
+  notes: MotifNote[];
+};
+
+/** Melodic contour shape for {@link generateMotif}. */
+export type MotifContour = 'arch' | 'ascending' | 'descending' | 'wave';
+
+/** Options controlling {@link generateMotif}. */
+export type GenerateMotifOptions = {
+  key: KeyScale;
+  chord?: Chord | null;
+  bars: number;
+  contour?: MotifContour;
+  seed?: number;
+};
+
+function pitchClass(pitch: number): number {
+  return ((Math.trunc(pitch) % 12) + 12) % 12;
+}
+
+/**
+ * Smallest span, in beats, treated as a distinct tile step. A positive but
+ * near-zero cell span is clamped to this so tiling cannot stall.
+ */
+const MIN_TILE_SPAN = 1 / 256;
+
+/** Nearest in-scale pitch strictly above `pitch`. */
+function upScaleTone(pitch: number, key: KeyScale): number {
+  for (let d = 1; d <= 12; d += 1) {
+    if (isScaleTone(pitch + d, key)) {
+      return pitch + d;
+    }
+  }
+  return pitch + 12;
+}
+
+/** Nearest in-scale pitch strictly below `pitch`. */
+function downScaleTone(pitch: number, key: KeyScale): number {
+  for (let d = 1; d <= 12; d += 1) {
+    if (isScaleTone(pitch - d, key)) {
+      return pitch - d;
+    }
+  }
+  return pitch - 12;
+}
+
+/** Shift a pitch by a number of diatonic scale degrees. */
+function stepDiatonic(pitch: number, degrees: number, key: KeyScale): number {
+  let p = nearestScaleTone(pitch, key);
+  const steps = Math.abs(Math.trunc(degrees));
+  for (let i = 0; i < steps; i += 1) {
+    p = degrees >= 0 ? upScaleTone(p, key) : downScaleTone(p, key);
+  }
+  return p;
+}
+
+/** Nearest chord tone to `pitch`, preferring the lower pitch on a tie. */
+function nearestChordTone(pitch: number, chord: Chord): number {
+  const pcs = chordPitchClasses(chord);
+  for (let d = 0; d <= 12; d += 1) {
+    if (pcs.includes(pitchClass(pitch - d))) {
+      return pitch - d;
+    }
+    if (pcs.includes(pitchClass(pitch + d))) {
+      return pitch + d;
+    }
+  }
+  return pitch;
+}
+
+/** Earliest onset in a cell; the time origin for timing transforms. */
+function cellOrigin(notes: MotifNote[]): number {
+  return notes.length === 0 ? 0 : Math.min(...notes.map((n) => n.startBeat));
+}
+
+/** Total beat span covered by a cell (from first onset to last offset). */
+function cellSpan(cell: MotifCell): number {
+  if (cell.notes.length === 0) {
+    return 0;
+  }
+  const start = cellOrigin(cell.notes);
+  const end = Math.max(...cell.notes.map((n) => n.startBeat + n.durationBeat));
+  return end - start;
+}
+
+function clone(cell: MotifCell): MotifCell {
+  return { notes: cell.notes.map((n) => ({ ...n })) };
+}
+
+/** Deterministic 32-bit PRNG in [0, 1). */
+function mulberry32(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Diatonic scale-degree offsets shaping a contour of `count` notes. */
+function contourOffsets(contour: MotifContour, count: number): number[] {
+  const offsets: number[] = [];
+  const half = Math.floor(count / 2);
+  for (let i = 0; i < count; i += 1) {
+    switch (contour) {
+      case 'ascending':
+        offsets.push(i);
+        break;
+      case 'descending':
+        offsets.push(-i);
+        break;
+      case 'arch':
+        offsets.push(i <= half ? i : count - 1 - i);
+        break;
+      case 'wave':
+        offsets.push([0, 1, 0, -1][i % 4] ?? 0);
+        break;
+    }
+  }
+  return offsets;
+}
+
+/**
+ * Generate a short seed motif over `bars`.
+ *
+ * The melody follows the requested contour in diatonic steps from the tonic,
+ * snapped to the key. When a chord is supplied, notes landing on bar downbeats
+ * are pulled to the nearest chord tone. Output is deterministic for a given seed.
+ *
+ * @param opts Key, optional chord, length, contour, and seed.
+ * @returns The generated motif cell.
+ */
+export function generateMotif(opts: GenerateMotifOptions): MotifCell {
+  const contour = opts.contour ?? 'arch';
+  const bars = Math.max(1, Math.trunc(opts.bars));
+  const totalBeats = bars * 4;
+  const noteCount = Math.max(3, bars * 2);
+  const beatsPerNote = totalBeats / noteCount;
+  const rng = mulberry32(opts.seed ?? 0);
+  const tonic = pitchClass(opts.key.rootPc) + 60;
+  const offsets = contourOffsets(contour, noteCount);
+
+  const notes: MotifNote[] = [];
+  for (let i = 0; i < noteCount; i += 1) {
+    const jitter = rng() < 0.25 ? 1 : 0;
+    let pitch = stepDiatonic(tonic, (offsets[i] ?? 0) + jitter, opts.key);
+    const startBeat = i * beatsPerNote;
+    if (opts.chord && startBeat % 4 === 0) {
+      pitch = nearestChordTone(pitch, opts.chord);
+    }
+    notes.push({ pitch, startBeat, durationBeat: beatsPerNote });
+  }
+  return { notes };
+}
+
+/**
+ * Apply a transformation to a motif cell.
+ *
+ * `invert` reflects pitches about the first note (chromatic, self-inverse);
+ * `retrograde` mirrors onsets about the cell span, preserving rests (self-inverse);
+ * `augment`/`diminish` scale time by `amount ?? 2` and its reciprocal;
+ * `transposeChromatic` adds `amount` semitones; `transposeDiatonic` shifts by
+ * `amount` scale degrees when a `key` is given, or — with no `key` — falls back
+ * to a chromatic shift of `amount` semitones; `sequence` appends a shifted copy
+ * (by `amount` diatonic degrees with a `key`, or by `amount` semitones without
+ * one, since it delegates to `transposeDiatonic`).
+ *
+ * @param cell The cell to transform.
+ * @param t The transformation.
+ * @param amount Optional parameter (semitones, degrees, or time factor).
+ * @param key Key context for the diatonic transforms; without it,
+ *   `transposeDiatonic` and `sequence` shift chromatically by semitones.
+ * @returns The transformed cell.
+ */
+export function transformMotif(
+  cell: MotifCell,
+  t: MotifTransform,
+  amount?: number,
+  key?: KeyScale,
+): MotifCell {
+  const notes = cell.notes;
+  switch (t) {
+    case 'transposeChromatic': {
+      const semis = amount ?? 0;
+      return { notes: notes.map((n) => ({ ...n, pitch: n.pitch + semis })) };
+    }
+    case 'transposeDiatonic': {
+      const degrees = amount ?? 1;
+      return {
+        notes: notes.map((n) => ({
+          ...n,
+          // With a key, shift by scale degrees; without one, fall back to a
+          // chromatic shift of `degrees` semitones.
+          pitch: key ? stepDiatonic(n.pitch, degrees, key) : n.pitch + degrees,
+        })),
+      };
+    }
+    case 'invert': {
+      const pivot = notes[0]?.pitch ?? 0;
+      return { notes: notes.map((n) => ({ ...n, pitch: 2 * pivot - n.pitch })) };
+    }
+    case 'retrograde': {
+      if (notes.length === 0) {
+        return { notes: [] };
+      }
+      const start = cellOrigin(notes);
+      const end = Math.max(...notes.map((n) => n.startBeat + n.durationBeat));
+      return {
+        notes: notes.map((n) => ({
+          pitch: n.pitch,
+          startBeat: start + (end - (n.startBeat + n.durationBeat)),
+          durationBeat: n.durationBeat,
+        })),
+      };
+    }
+    case 'augment':
+      return scaleTime(cell, amount ?? 2);
+    case 'diminish':
+      return scaleTime(cell, 1 / (amount ?? 2));
+    case 'sequence': {
+      const degrees = amount ?? 2;
+      const span = cellSpan(cell);
+      // Delegates to transposeDiatonic: a diatonic shift when `key` is given,
+      // otherwise a chromatic shift of `degrees` semitones.
+      const copy = transformMotif(cell, 'transposeDiatonic', degrees, key);
+      const shifted = copy.notes.map((n) => ({ ...n, startBeat: n.startBeat + span }));
+      return { notes: [...clone(cell).notes, ...shifted] };
+    }
+  }
+}
+
+/** Scale a cell's timing about its origin by `factor`. */
+function scaleTime(cell: MotifCell, factor: number): MotifCell {
+  const origin = cellOrigin(cell.notes);
+  return {
+    notes: cell.notes.map((n) => ({
+      pitch: n.pitch,
+      startBeat: origin + (n.startBeat - origin) * factor,
+      durationBeat: n.durationBeat * factor,
+    })),
+  };
+}
+
+/**
+ * Lay a motif across `bars` and snap it to a chord timeline.
+ *
+ * The cell is tiled back-to-back to fill the requested span; each note is then
+ * pulled to the nearest chord tone of the segment sounding at its onset, so the
+ * developed line spells the underlying harmony.
+ *
+ * @param cell The source motif.
+ * @param timeline Chord segments to snap against.
+ * @param key Key context (used to keep snapped pitches sensible).
+ * @param bars Number of four-beat bars to fill.
+ * @returns The developed, harmony-aware cell.
+ */
+export function developMotif(
+  cell: MotifCell,
+  timeline: ChordTimeline,
+  key: KeyScale,
+  bars: number,
+): MotifCell {
+  const span = cellSpan(cell);
+  const totalBeats = Math.max(1, Math.trunc(bars)) * 4;
+  const origin = cellOrigin(cell.notes);
+  const out: MotifNote[] = [];
+
+  if (span <= 0) {
+    return clone(cell);
+  }
+
+  // Clamp a degenerate near-zero span so the tile count stays finite, and step
+  // the offset multiplicatively so rounding error cannot accumulate over tiles.
+  const tileSpan = Math.max(span, MIN_TILE_SPAN);
+  const tileCount = Math.ceil(totalBeats / tileSpan);
+  for (let k = 0; k < tileCount; k += 1) {
+    const offset = k * tileSpan;
+    for (const n of cell.notes) {
+      const startBeat = offset + (n.startBeat - origin);
+      if (startBeat >= totalBeats) {
+        continue;
+      }
+      const chord = timeline.at(startBeat);
+      let pitch = n.pitch;
+      if (chord) {
+        const isMember = chordPitchClasses(chord).includes(pitchClass(pitch));
+        pitch = isMember ? pitch : nearestChordTone(pitch, chord);
+      } else {
+        pitch = nearestScaleTone(pitch, key);
+      }
+      out.push({ pitch, startBeat, durationBeat: n.durationBeat });
+    }
+  }
+  return { notes: out };
+}

package/src/pitch/index.ts

@@ -0,0 +1,256 @@
+/**
+ * Pitch spelling: letter-name notes, enharmonic-aware conversion, and spelled
+ * intervals.
+ *
+ * The rest of the library works in pitch classes (0..11), which cannot tell a
+ * G# from an Ab or an augmented fourth from a diminished fifth. This module adds
+ * an explicit spelling layer — a note is a diatonic letter plus a chromatic
+ * alteration — so interval quality (P/M/m/A/d) and enharmonic identity are
+ * preserved.
+ */
+
+/** 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;
+
+/** Letter glyphs indexed by letter number (0 = C .. 6 = B). */
+const LETTER_NAMES = ['C', 'D', 'E', 'F', 'G', 'A', 'B'] as const;
+
+/**
+ * A spelled note: a diatonic letter, a chromatic alteration, and an optional
+ * octave.
+ *
+ * - `letter` is 0..6 for C..B.
+ * - `alter` is the number of semitones of alteration: -2 double-flat, -1 flat,
+ *   0 natural, +1 sharp, +2 double-sharp.
+ * - `octave` follows scientific pitch notation (middle C = C4 = MIDI 60). When
+ *   absent, the note denotes a bare pitch class.
+ */
+export type Note = {
+  letter: number;
+  alter: number;
+  octave?: number;
+};
+
+/** A spelled interval: a diatonic number, a quality label, and its semitone span. */
+export type SpelledInterval = {
+  /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */
+  number: number;
+  /** Quality label: 'P', 'M', 'm', or repeated 'A'/'d' for (multiply) aug/dim. */
+  quality: string;
+  /** Signed semitone distance from the first note to the second. */
+  semitones: number;
+};
+
+/** Reduce any integer to a pitch class in [0, 11]. */
+function mod12(n: number): number {
+  return ((n % 12) + 12) % 12;
+}
+
+/** Reduce any integer to [0, 7). */
+function mod7(n: number): number {
+  return ((n % 7) + 7) % 7;
+}
+
+/**
+ * Parse scientific pitch notation into a {@link Note}.
+ *
+ * Accepts a letter (case-insensitive) followed by any number of same-direction
+ * accidentals and an optional octave, e.g. `"C"`, `"C#4"`, `"Bb"`, `"F##3"`,
+ * `"Ebb2"`. Both `#` and `x` (double-sharp) are accepted for sharps; `b` for
+ * flats. Mixing sharps and flats (e.g. `"C#b"`) is rejected.
+ *
+ * @param text The note text.
+ * @returns The parsed note.
+ * @throws If the text is not a valid note.
+ */
+export function parseNote(text: string): Note {
+  const match = /^([A-Ga-g])([#x]*|b*)(-?\d+)?$/.exec(text.trim());
+  if (!match) {
+    throw new Error(`Invalid note: ${text}`);
+  }
+  const letterGlyph = (match[1] ?? '').toUpperCase();
+  const letter = LETTER_NAMES.indexOf(letterGlyph as (typeof LETTER_NAMES)[number]);
+  let alter = 0;
+  for (const ch of match[2] ?? '') {
+    if (ch === '#') {
+      alter += 1;
+    } else if (ch === 'x') {
+      alter += 2;
+    } else if (ch === 'b') {
+      alter -= 1;
+    }
+  }
+  const note: Note = { letter, alter };
+  if (match[3] !== undefined) {
+    note.octave = Number.parseInt(match[3], 10);
+  }
+  return note;
+}
+
+/** Render an alteration as accidental glyphs (`##`, `b`, empty for natural). */
+function formatAlter(alter: number): string {
+  if (alter > 0) {
+    return '#'.repeat(alter);
+  }
+  if (alter < 0) {
+    return 'b'.repeat(-alter);
+  }
+  return '';
+}
+
+/**
+ * Render a {@link Note} as scientific pitch notation.
+ *
+ * @param note The note to format.
+ * @returns The note text, including the octave when present.
+ */
+export function formatNote(note: Note): string {
+  const glyph = LETTER_NAMES[mod7(note.letter)] ?? 'C';
+  const octave = note.octave === undefined ? '' : String(note.octave);
+  return `${glyph}${formatAlter(note.alter)}${octave}`;
+}
+
+/**
+ * Pitch class (0..11) of a note, ignoring octave.
+ *
+ * @param note The note.
+ * @returns The pitch class.
+ */
+export function noteToPitchClass(note: Note): number {
+  const natural = LETTER_SEMITONES[mod7(note.letter)] ?? 0;
+  return mod12(natural + note.alter);
+}
+
+/**
+ * MIDI number of a note (middle C = C4 = 60).
+ *
+ * @param note The note; must carry an octave.
+ * @returns The MIDI number.
+ * @throws If the note has no octave.
+ */
+export function noteToMidi(note: Note): number {
+  if (note.octave === undefined) {
+    throw new Error('noteToMidi requires an octave');
+  }
+  const natural = LETTER_SEMITONES[mod7(note.letter)] ?? 0;
+  return (note.octave + 1) * 12 + natural + note.alter;
+}
+
+/** Preferred spelling when naming a black key from a bare MIDI number. */
+const SHARP_SPELLING: readonly [number, number][] = [
+  [0, 0],
+  [0, 1],
+  [1, 0],
+  [1, 1],
+  [2, 0],
+  [3, 0],
+  [3, 1],
+  [4, 0],
+  [4, 1],
+  [5, 0],
+  [5, 1],
+  [6, 0],
+];
+
+const FLAT_SPELLING: readonly [number, number][] = [
+  [0, 0],
+  [1, -1],
+  [1, 0],
+  [2, -1],
+  [2, 0],
+  [3, 0],
+  [4, -1],
+  [4, 0],
+  [5, -1],
+  [5, 0],
+  [6, -1],
+  [6, 0],
+];
+
+/**
+ * Name a MIDI number as a {@link Note}, choosing sharp or flat spelling.
+ *
+ * @param midi The MIDI number.
+ * @param spelling Whether to prefer sharps or flats for black keys.
+ * @returns The spelled note, with octave.
+ */
+export function midiToNote(midi: number, spelling: 'sharp' | 'flat' = 'sharp'): Note {
+  const rounded = Math.round(midi);
+  const pc = mod12(rounded);
+  const octave = Math.floor(rounded / 12) - 1;
+  const table = spelling === 'sharp' ? SHARP_SPELLING : FLAT_SPELLING;
+  const entry = table[pc] ?? [0, 0];
+  return { letter: entry[0], alter: entry[1], octave };
+}
+
+/** Reference semitone span of a perfect/major simple interval by diatonic number. */
+const SIMPLE_REFERENCE = [0, 0, 2, 4, 5, 7, 9, 11] as const;
+
+/** Whether a simple diatonic number (1..7 within an octave) is a perfect kind. */
+function isPerfectNumber(simpleNumber: number): boolean {
+  return simpleNumber === 1 || simpleNumber === 4 || simpleNumber === 5;
+}
+
+/** Quality label from a diatonic number and its actual semitone span. */
+function qualityFromSpan(numberValue: number, semitones: number): string {
+  const octaves = Math.floor((numberValue - 1) / 7);
+  const simple = numberValue - 7 * octaves;
+  const reference = (SIMPLE_REFERENCE[simple] ?? 0) + 12 * octaves;
+  const delta = semitones - reference;
+  if (isPerfectNumber(simple)) {
+    if (delta === 0) {
+      return 'P';
+    }
+    return delta > 0 ? 'A'.repeat(delta) : 'd'.repeat(-delta);
+  }
+  if (delta === 0) {
+    return 'M';
+  }
+  if (delta === -1) {
+    return 'm';
+  }
+  return delta > 0 ? 'A'.repeat(delta) : 'd'.repeat(-delta - 1);
+}
+
+/** Diatonic ladder index of a note (letter + 7 * octave when octave-bearing). */
+function diatonicIndex(note: Note): number {
+  return mod7(note.letter) + 7 * (note.octave ?? 0);
+}
+
+/**
+ * The spelled interval from one note to another.
+ *
+ * When both notes carry octaves, the interval reflects their full signed
+ * distance (so `C4 -> C5` is a perfect octave). When either lacks an octave the
+ * interval is measured within a single ascending octave from `a` to `b`.
+ *
+ * @param a The lower/first note.
+ * @param b The upper/second note.
+ * @returns The diatonic number, quality, and semitone span.
+ */
+export function spelledInterval(a: Note, b: Note): SpelledInterval {
+  const octaved = a.octave !== undefined && b.octave !== undefined;
+  let letterSteps: number;
+  let semitones: number;
+  if (octaved) {
+    letterSteps = diatonicIndex(b) - diatonicIndex(a);
+    // Signed pitch distance from a to b, so a note below a yields a negative span.
+    semitones = noteToMidi(b) - noteToMidi(a);
+  } else {
+    letterSteps = mod7(b.letter - a.letter);
+    let rawSemis = mod12(noteToPitchClass(b) - noteToPitchClass(a));
+    // Lift the chromatic span into the octave nearest the diatonic reference so
+    // wraparound intervals (e.g. Ab -> G# = augmented seventh) stay consistent
+    // with the ascending diatonic number instead of collapsing modulo 12.
+    const reference = SIMPLE_REFERENCE[letterSteps + 1] ?? 0;
+    if (reference - rawSemis > 6) {
+      rawSemis += 12;
+    }
+    semitones = rawSemis;
+  }
+  const absSteps = Math.abs(letterSteps);
+  const number = absSteps + 1;
+  // Quality comes from the absolute chromatic span; semitones keeps its sign.
+  const quality = qualityFromSpan(number, Math.abs(semitones));
+  return { number, quality, semitones };
+}