@libraz/libcantus 0.9.2 → 0.9.4

package/src/core/meter/index.ts

@@ -1,282 +0,0 @@
-/**
- * Meter and time signatures: bar/beat arithmetic, simple vs. compound meters,
- * metric-accent hierarchy, and tuplet subdivision.
- *
- * Positions and durations are measured in quarter-note beats, matching the rest
- * of the library's beat convention (four quarter-note beats per bar in 4/4).
- */
-
-/**
- * A time signature as a numerator over a note-value denominator.
- *
- * @category Rhythm & Meter
- */
-export type TimeSignature = {
-  numerator: number;
-  denominator: number;
-  /**
-   * Optional additive grouping of the bar's main pulses, as the felt-beat
-   * lengths in pulses — e.g. `[2, 2, 3]` for a 2+2+3 reading of 7/8, or
-   * `[3, 2]` for 5/8. The entries must be positive integers summing to
-   * {@link pulsesPerBar}. When present, the head pulse of each group (other
-   * than the downbeat) is treated as a secondary strong pulse by
-   * {@link metricWeight}/{@link isStrongBeat}; when absent, all main pulses
-   * are weighted equally as flat, evenly divided pulses.
-   */
-  grouping?: number[];
-};
-
-/**
- * A position expressed as a bar index and a quarter-note offset within the bar.
- *
- * @category Rhythm & Meter
- */
-export type BarPosition = {
-  bar: number;
-  /** Quarter-note offset from the start of the bar. */
-  beat: number;
-};
-
-const EPS = 1e-9;
-
-/** Whether `value` is an integer multiple of `unit` (within a float tolerance). */
-function isMultiple(value: number, unit: number): boolean {
-  if (unit === 0) {
-    return false;
-  }
-  const ratio = value / unit;
-  return Math.abs(ratio - Math.round(ratio)) < EPS;
-}
-
-/**
- * Parse a time signature such as `"4/4"` or `"6/8"`.
- *
- * @param text The signature text.
- * @returns The parsed time signature.
- * @throws If the text is not `n/d` with positive integers.
- * @example
- * ```ts
- * import { parseTimeSignature } from '@libraz/libcantus';
- * parseTimeSignature('6/8'); // { numerator: 6, denominator: 8 }
- * ```
- * @category Rhythm & Meter
- */
-export function parseTimeSignature(text: string): TimeSignature {
-  const match = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(text);
-  if (!match) {
-    throw new Error(`Invalid time signature: ${text}`);
-  }
-  const numerator = Number.parseInt(match[1] ?? '', 10);
-  const denominator = Number.parseInt(match[2] ?? '', 10);
-  if (numerator <= 0 || denominator <= 0) {
-    throw new Error(`Invalid time signature: ${text}`);
-  }
-  return { numerator, denominator };
-}
-
-/**
- * Render a time signature as `"n/d"`.
- *
- * @category Rhythm & Meter
- */
-export function formatTimeSignature(ts: TimeSignature): string {
-  return `${ts.numerator}/${ts.denominator}`;
-}
-
-/**
- * Whether a meter is compound: its main pulses each divide into three, as in
- * 6/8, 9/8, 12/8, or 6/4. Compound meters are those whose numerator is a
- * multiple of three greater than three, independent of the denominator. Meters
- * like 3/8 and 3/4 (simple triples, numerator 3) are not compound.
- *
- * @param ts The time signature.
- * @returns True for compound meters.
- * @category Rhythm & Meter
- */
-export function isCompound(ts: TimeSignature): boolean {
-  return ts.numerator % 3 === 0 && ts.numerator > 3;
-}
-
-/** Length of one denominator unit in quarter-note beats. */
-function unitBeats(ts: TimeSignature): number {
-  return 4 / ts.denominator;
-}
-
-/**
- * Length of a bar in quarter-note beats.
- *
- * @param ts The time signature.
- * @returns The bar length in quarter notes.
- * @category Rhythm & Meter
- */
-export function beatsPerBar(ts: TimeSignature): number {
-  return ts.numerator * unitBeats(ts);
-}
-
-/** Length of one main pulse (a dotted value in compound meters) in quarter notes. */
-function pulseBeats(ts: TimeSignature): number {
-  return isCompound(ts) ? 3 * unitBeats(ts) : unitBeats(ts);
-}
-
-/**
- * Number of main pulses (felt beats) per bar: the numerator for simple meters,
- * a third of it for compound meters.
- *
- * For additive/irregular meters such as 7/8 or 5/8 this counts the raw pulses
- * (7 and 5 respectively), which are otherwise felt as flat, evenly divided and
- * equally accented pulses. To recover a 2+2+3 or 3+2 felt-beat grouping, set
- * {@link TimeSignature.grouping}; {@link metricWeight} then accents each
- * group's head pulse.
- *
- * @param ts The time signature.
- * @returns The pulse count per bar.
- * @category Rhythm & Meter
- */
-export function pulsesPerBar(ts: TimeSignature): number {
-  return beatsPerBar(ts) / pulseBeats(ts);
-}
-
-/**
- * Whether `grouping` is a valid additive grouping for a bar of `pulses` main
- * pulses: a non-empty list of positive integers summing to `pulses`.
- */
-function isValidGrouping(grouping: number[], pulses: number): boolean {
-  if (grouping.length === 0) {
-    return false;
-  }
-  let sum = 0;
-  for (const g of grouping) {
-    if (!Number.isInteger(g) || g <= 0) {
-      return false;
-    }
-    sum += g;
-  }
-  return sum === pulses;
-}
-
-/** Whether `pulseIndex` is the head pulse of one of the additive groups. */
-function isGroupHead(grouping: number[], pulseIndex: number): boolean {
-  let acc = 0;
-  for (const g of grouping) {
-    if (acc === pulseIndex) {
-      return true;
-    }
-    acc += g;
-  }
-  return false;
-}
-
-/**
- * Convert an absolute quarter-note position to a bar index and in-bar offset.
- *
- * @param beatInQuarters Absolute position in quarter-note beats.
- * @param ts The time signature.
- * @returns The bar and in-bar quarter-note offset.
- * @example
- * ```ts
- * import { parseTimeSignature, beatToBarPosition } from '@libraz/libcantus';
- * const ts = parseTimeSignature('4/4');
- * beatToBarPosition(5, ts); // { bar: 1, beat: 1 }
- * ```
- * @category Rhythm & Meter
- */
-export function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition {
-  const barLen = beatsPerBar(ts);
-  const bar = Math.floor(beatInQuarters / barLen);
-  return { bar, beat: beatInQuarters - bar * barLen };
-}
-
-/**
- * Convert a bar index and in-bar offset back to an absolute quarter-note
- * position.
- *
- * @param pos The bar position.
- * @param ts The time signature.
- * @returns The absolute position in quarter-note beats.
- * @category Rhythm & Meter
- */
-export function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number {
-  return pos.bar * beatsPerBar(ts) + pos.beat;
-}
-
-/**
- * Metric weight of a position within its bar, on a 0–3 scale:
- * 3 the downbeat, 2 a secondary strong pulse, 1 any other main pulse, and 0 an
- * off-pulse subdivision.
- *
- * The secondary strong pulse is the bar's midpoint in even simple/compound
- * meters. For an additive/irregular meter with {@link TimeSignature.grouping}
- * set (e.g. `[2, 2, 3]` for 7/8), each group's head pulse other than the
- * downbeat is the secondary strong pulse instead; without a grouping every
- * non-downbeat main pulse of such a meter weighs 1 (flat, evenly divided
- * pulses).
- *
- * @param beatInQuarters Absolute or in-bar quarter-note position.
- * @param ts The time signature.
- * @returns The metric weight (0–3).
- * @throws If `ts.grouping` is present but is not a positive-integer list
- *   summing to {@link pulsesPerBar}.
- * @example
- * ```ts
- * import { parseTimeSignature, metricWeight } from '@libraz/libcantus';
- * const ts = parseTimeSignature('4/4');
- * metricWeight(0, ts); // 3 (the downbeat)
- * ```
- * @category Rhythm & Meter
- */
-export function metricWeight(beatInQuarters: number, ts: TimeSignature): number {
-  const { beat } = beatToBarPosition(beatInQuarters, ts);
-  const pulse = pulseBeats(ts);
-  if (!isMultiple(beat, pulse)) {
-    return 0;
-  }
-  const pulses = pulsesPerBar(ts);
-  const pulseIndex = Math.round(beat / pulse) % pulses;
-  if (pulseIndex === 0) {
-    return 3;
-  }
-  const grouping = ts.grouping;
-  if (grouping !== undefined) {
-    if (!isValidGrouping(grouping, pulses)) {
-      throw new Error(
-        `Invalid grouping [${grouping.join(', ')}] for ${formatTimeSignature(ts)}: ` +
-          `entries must be positive integers summing to ${pulses}`,
-      );
-    }
-    return isGroupHead(grouping, pulseIndex) ? 2 : 1;
-  }
-  if (pulses % 2 === 0 && pulseIndex === pulses / 2) {
-    return 2;
-  }
-  return 1;
-}
-
-/**
- * Whether a position is metrically accented (weight 2 or more — a downbeat or a
- * secondary strong pulse).
- *
- * @param beatInQuarters Absolute or in-bar quarter-note position.
- * @param ts The time signature.
- * @returns True on strong beats.
- * @category Rhythm & Meter
- */
-export function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean {
-  return metricWeight(beatInQuarters, ts) >= 2;
-}
-
-/**
- * Subdivide a span into `count` equal tuplet durations (e.g. an eighth-note
- * triplet is `tuplet(1, 3)`).
- *
- * @param totalBeats Total span in quarter-note beats.
- * @param count Number of equal parts.
- * @returns `count` equal durations summing to `totalBeats`.
- * @throws If `count` is not a positive integer.
- * @category Rhythm & Meter
- */
-export function tuplet(totalBeats: number, count: number): number[] {
-  if (!Number.isInteger(count) || count <= 0) {
-    throw new Error(`Invalid tuplet count: ${count}`);
-  }
-  return new Array<number>(count).fill(totalBeats / count);
-}

package/src/core/pitch/index.ts

@@ -1,311 +0,0 @@
-/**
- * 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.
- *
- * @category Pitch & Intervals
- */
-export type Note = {
-  letter: number;
-  alter: number;
-  octave?: number;
-};
-
-/**
- * A spelled interval: a diatonic number, a quality label, and its semitone span.
- *
- * @category Pitch & Intervals
- */
-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.
- * @example
- * ```ts
- * import { parseNote, noteToMidi } from '@libraz/libcantus';
- * const n = parseNote('C#4');
- * noteToMidi(n); // 61
- * ```
- * @category Pitch & Intervals
- */
-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.
- * @example
- * ```ts
- * import { formatNote, parseNote } from '@libraz/libcantus';
- * formatNote(parseNote('C#4')); // 'C#4'
- * ```
- * @category Pitch & Intervals
- */
-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.
- * @example
- * ```ts
- * import { noteToPitchClass, parseNote } from '@libraz/libcantus';
- * noteToPitchClass(parseNote('Db')); // 1
- * ```
- * @category Pitch & Intervals
- */
-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.
- * @example
- * ```ts
- * import { noteToMidi, parseNote } from '@libraz/libcantus';
- * noteToMidi(parseNote('A4')); // 69
- * ```
- * @category Pitch & Intervals
- */
-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.
- *
- * The input is rounded to the nearest integer but is not clamped to the MIDI
- * range 0..127: out-of-range values extrapolate linearly (e.g. `-1` -> `B-2`,
- * `128` -> `G#9`) and remain an exact inverse of {@link noteToMidi}.
- *
- * @param midi The MIDI number.
- * @param spelling Whether to prefer sharps or flats for black keys.
- * @returns The spelled note, with octave.
- * @example
- * ```ts
- * import { midiToNote, formatNote } from '@libraz/libcantus';
- * formatNote(midiToNote(61)); // 'C#4'
- * formatNote(midiToNote(61, 'flat')); // 'Db4'
- * ```
- * @category Pitch & Intervals
- */
-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.
- * @example
- * ```ts
- * import { spelledInterval, parseNote } from '@libraz/libcantus';
- * spelledInterval(parseNote('C4'), parseNote('G4'));
- * // { number: 5, quality: 'P', semitones: 7 }
- * ```
- * @category Pitch & Intervals
- */
-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 stay consistent with the diatonic number instead of
-    // collapsing modulo 12. The correction is bidirectional: an upward wrap
-    // (e.g. Ab -> G# = augmented seventh) adds an octave, while a same-letter or
-    // downward chromatic step (e.g. E -> Eb, F# -> F, C -> Cb = descending
-    // diminished/augmented unison) subtracts one so the sign follows pitch
-    // direction instead of returning a garbage stack of augmentations.
-    const reference = SIMPLE_REFERENCE[letterSteps + 1] ?? 0;
-    if (reference - rawSemis > 6) {
-      rawSemis += 12;
-    } else if (rawSemis - reference > 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 };
-}

package/src/core/random/index.ts

@@ -1,53 +0,0 @@
-/**
- * Deterministic seeded pseudo-random number generation shared across the
- * generative modules (rhythm, drums, bass, groove, counter-melody). A single
- * mulberry32 core exposes the small set of samplers those modules need; given a
- * seed the stream is fully reproducible.
- */
-
-/**
- * A deterministic PRNG with the sampling helpers the generators need.
- *
- * @category Utilities
- */
-export type Rng = {
-  /** Next float in [0, 1). */
-  next: () => number;
-  /** True with probability `p`. */
-  prob: (p: number) => boolean;
-  /** Integer in the inclusive range [lo, hi]. */
-  range: (lo: number, hi: number) => number;
-  /** Float in [lo, hi). */
-  float: (lo: number, hi: number) => number;
-};
-
-/**
- * Create a seeded PRNG (mulberry32) exposing the shared samplers.
- *
- * @param seed The 32-bit seed; the same seed always yields the same stream.
- * @returns The seeded generator.
- * @example
- * ```ts
- * import { createRng } from '@libraz/libcantus';
- * const rng = createRng(42);
- * rng.next(); // deterministic float in [0, 1)
- * rng.range(1, 6); // deterministic integer in [1, 6]
- * ```
- * @category Utilities
- */
-export function createRng(seed: number): Rng {
-  let state = seed >>> 0;
-  const next = () => {
-    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;
-  };
-  return {
-    next,
-    prob: (p) => next() < p,
-    range: (lo, hi) => lo + Math.floor(next() * (hi - lo + 1)),
-    float: (lo, hi) => lo + next() * (hi - lo),
-  };
-}