@libraz/libcantus 0.9.3 → 0.9.4

package/src/generate/rhythm/index.ts

@@ -1,175 +0,0 @@
-/**
- * Deterministic rhythm generation over a metric grid.
- *
- * Builds a fixed-resolution grid across one or more bars of a time signature
- * and decides, per grid slot, whether it becomes a note onset. Onset
- * probability follows the metric-accent hierarchy from the `meter` module, so
- * strong positions (downbeats, secondary pulses) are favored over weak
- * off-pulse subdivisions. Given a seed the output is fully reproducible.
- *
- * Positions and durations are measured in quarter-note beats, matching the
- * library-wide convention.
- */
-
-import { beatsPerBar, metricWeight, type TimeSignature } from '../../core/meter/index.js';
-import { createRng } from '../../core/random/index.js';
-import {
-  assertFiniteNumber,
-  assertGenerationBudget,
-  assertPositiveInt,
-} from '../../core/validation/index.js';
-
-/**
- * A single rhythmic note: an onset position and how long it sounds.
- *
- * @category Rhythm & Meter
- */
-export type RhythmEvent = {
-  /** Onset position in quarter-note beats, absolute from the start of the span. */
-  position: number;
-  /** Duration in quarter-note beats, extending to the next onset. */
-  duration: number;
-};
-
-/**
- * Options controlling {@link generateRhythm}.
- *
- * @category Rhythm & Meter
- */
-export type RhythmOptions = {
-  /**
-   * Seed for the deterministic PRNG.
-   *
-   * @defaultValue 0
-   */
-  seed?: number;
-  /**
-   * Number of bars to generate.
-   *
-   * @defaultValue 1
-   */
-  bars?: number;
-  /**
-   * Grid resolution as the number of equal grid steps per quarter-note beat.
-   * The default of 2 yields an eighth-note grid; 4 yields a sixteenth-note
-   * grid, 3 an eighth-note triplet grid, and so on.
-   *
-   * @defaultValue 2
-   */
-  subdivision?: number;
-  /**
-   * Overall onset density in [0, 1]. Scales the per-slot onset probability, so
-   * higher values fill more grid slots. Values outside [0, 1] are clamped into
-   * range.
-   *
-   * @defaultValue 0.5
-   */
-  density?: number;
-};
-
-const DEFAULT_SUBDIVISION = 2;
-const DEFAULT_DENSITY = 0.5;
-const DEFAULT_BARS = 1;
-
-/**
- * Map a metric weight (0–3 from {@link metricWeight}) to a base onset
- * probability before density scaling. Strong positions are much more likely to
- * carry an onset than weak ones; the curve is intentionally small and explicit
- * so its behavior is easy to inspect and test.
- *
- * @param weight The metric weight, 0 (off-pulse) to 3 (downbeat).
- * @returns A base onset probability in [0, 1].
- * @category Rhythm & Meter
- */
-export function onsetWeightCurve(weight: number): number {
-  switch (weight) {
-    case 3:
-      return 1;
-    case 2:
-      return 0.8;
-    case 1:
-      return 0.55;
-    default:
-      return 0.25;
-  }
-}
-
-/**
- * Generate a deterministic rhythmic pattern over `bars` bars of a time
- * signature. A grid is built at the chosen subdivision; each slot becomes an
- * onset with a probability derived from its metric weight scaled by `density`
- * and sampled from the seeded PRNG. Every bar's downbeat is always an onset, so
- * a pattern of any length has a reliable pulse independent of the seed. Each
- * event's duration extends to the next onset, and the last event extends to the
- * end of the span. `density` is clamped to [0, 1].
- *
- * @param ts The time signature.
- * @param opts Generation options.
- * @returns Onset events sorted by position, non-overlapping, covering the span.
- * @example
- * ```ts
- * import { parseTimeSignature, generateRhythm } from '@libraz/libcantus';
- * const ts = parseTimeSignature('4/4');
- * generateRhythm(ts, { seed: 42, density: 0.6 }); // onset events over one bar
- * ```
- * @category Rhythm & Meter
- */
-export function generateRhythm(ts: TimeSignature, opts: RhythmOptions = {}): RhythmEvent[] {
-  const seed = opts.seed ?? 0;
-  const bars = opts.bars ?? DEFAULT_BARS;
-  const subdivision = opts.subdivision ?? DEFAULT_SUBDIVISION;
-  const requestedDensity = assertFiniteNumber(opts.density ?? DEFAULT_DENSITY, 'rhythm density');
-  const density = Math.min(1, Math.max(0, requestedDensity));
-
-  assertPositiveInt(bars, 'rhythm bars');
-  assertPositiveInt(subdivision, 'rhythm subdivision');
-
-  const barBeats = beatsPerBar(ts);
-  const spanBeats = barBeats * bars;
-  const step = 1 / subdivision;
-  const slotCount = Math.round(spanBeats * subdivision);
-  assertGenerationBudget(slotCount, 'rhythm grid slots');
-  const slotsPerBar = Math.round(barBeats * subdivision);
-  const rng = createRng(seed);
-
-  const positions: number[] = [];
-  for (let i = 0; i < slotCount; i += 1) {
-    const position = i * step;
-    // Force every bar's downbeat so the pulse is reliable regardless of seed.
-    if (i % slotsPerBar === 0) {
-      positions.push(position);
-      continue;
-    }
-    const weight = metricWeight(position, ts);
-    const probability = onsetWeightCurve(weight) * density;
-    if (rng.prob(probability)) {
-      positions.push(position);
-    }
-  }
-
-  const events: RhythmEvent[] = [];
-  for (let i = 0; i < positions.length; i += 1) {
-    const position = positions[i] ?? 0;
-    const nextPosition = positions[i + 1] ?? spanBeats;
-    events.push({ position, duration: nextPosition - position });
-  }
-  return events;
-}
-
-/**
- * Onset density of a generated pattern: the mean number of onsets per bar.
- *
- * @param events Events from {@link generateRhythm}.
- * @param ts The time signature.
- * @returns The onset count divided by the number of bars the events span.
- * @category Rhythm & Meter
- */
-export function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number {
-  if (events.length === 0) {
-    return 0;
-  }
-  const last = events[events.length - 1];
-  const spanBeats = (last?.position ?? 0) + (last?.duration ?? 0);
-  const bars = spanBeats / beatsPerBar(ts);
-  return bars > 0 ? events.length / bars : 0;
-}

package/src/index.ts

@@ -1,13 +0,0 @@
-/**
- * Complete public API.
- *
- * Each layer barrel is the canonical source of that layer's runtime and type
- * exports. The package root composes those barrels so a symbol added to a
- * public layer cannot silently disappear from the root entry point.
- */
-
-export * from './analyze/index.js';
-export * from './core/index.js';
-export * from './generate/index.js';
-export * from './model/index.js';
-export * from './theory/index.js';

package/src/model/chord.ts

@@ -1,442 +0,0 @@
-import { type DetectChordOptions, detectChord, detectChordBest } from '../analyze/detect/index.js';
-import {
-  analyzeChord,
-  type BorrowedSource,
-  borrowedSource,
-  type ChordAnalysis,
-  chordToRoman,
-  functionOf,
-  type HarmonicFunction,
-  isBorrowedChord,
-} from '../analyze/functional/index.js';
-import { negativeHarmonyMirror } from '../generate/reharmony/index.js';
-import {
-  type Chord as ChordData,
-  type ChordQuality,
-  chordPitchClasses,
-  makeChord,
-} from '../theory/chord/index.js';
-import {
-  availableTensions,
-  avoidNotes,
-  type ChordScaleMatch,
-  chordScales,
-} from '../theory/chordscale/index.js';
-import { spellChord, spellChordFromRoot, spellPitchClass } from '../theory/spelling/index.js';
-import { formatChordSymbol, parseChordSymbol } from '../theory/symbol/index.js';
-import {
-  type StyledVoicingOptions,
-  type VoicingOptions,
-  voiceChord,
-  voiceChordStyled,
-} from '../theory/voicing/index.js';
-import type { Key } from './key.js';
-import { Note } from './note.js';
-import { Progression } from './progression.js';
-import { mod12, spellPitchClassBare } from './shared.js';
-
-/**
- * Defensive copy of a plain chord.
- *
- * Any enharmonic spelling hints (`rootSpelling`/`bassSpelling`, populated by
- * `parseChordSymbol`) are carried through so a flat-named chord round-trips
- * through the class API; a hint that no longer matches its pitch class is
- * simply ignored by the formatter.
- */
-function copyChord(data: ChordData): ChordData {
-  const copy: ChordData = {
-    rootPc: data.rootPc,
-    quality: data.quality,
-    intervals: [...data.intervals],
-  };
-  if (data.bassPc !== undefined) {
-    copy.bassPc = data.bassPc;
-  }
-  if (data.rootSpelling !== undefined) {
-    copy.rootSpelling = { letter: data.rootSpelling.letter, alter: data.rootSpelling.alter };
-  }
-  if (data.bassSpelling !== undefined) {
-    copy.bassSpelling = { letter: data.bassSpelling.letter, alter: data.bassSpelling.alter };
-  }
-  return copy;
-}
-
-/**
- * An immutable chord: a root pitch class, quality, interval template, and
- * optional slash bass, optionally carrying a {@link Key} context. Analysis
- * methods (`roman`, `function`, `analyze`, ...) use an explicitly passed key
- * first and fall back to the carried context.
- *
- * @category Class API
- * @example
- * ```ts
- * import { Chord } from '@libraz/libcantus';
- * Chord.parse('Cmaj7').invert(1).symbol(); // 'Cmaj7/E' (third in the bass)
- * ```
- */
-export class Chord {
-  readonly #data: ChordData;
-  readonly #key: Key | undefined;
-
-  /**
-   * Wrap a plain chord object.
-   *
-   * @param data The chord; it is copied, never retained or mutated.
-   * @param key Optional key context for analysis methods.
-   */
-  constructor(data: ChordData, key?: Key) {
-    const copy = copyChord(data);
-    if (copy.rootSpelling === undefined && key !== undefined) {
-      copy.rootSpelling = spellPitchClass(copy.rootPc, key.tonic.data, key.scale);
-    }
-    this.#data = copy;
-    this.#key = key;
-  }
-
-  /**
-   * Build a chord from a root and quality.
-   *
-   * @param root Root as a note name (e.g. `'Eb'`) or a pitch class.
-   * @param quality The chord quality.
-   * @param bass Optional slash-chord bass pitch class.
-   * @returns The chord (without key context).
-   */
-  static of(root: string | number, quality: ChordQuality, bass?: number): Chord {
-    if (typeof root === 'string') {
-      const rootNote = Note.of(root);
-      const data = makeChord(rootNote.pitchClass, quality, bass);
-      data.rootSpelling = { letter: rootNote.letter, alter: rootNote.alter };
-      return new Chord(data);
-    }
-    return new Chord(makeChord(root, quality, bass));
-  }
-
-  /**
-   * Wrap an existing plain chord object.
-   *
-   * @param data The plain chord.
-   * @returns The wrapped chord (without key context).
-   */
-  static from(data: ChordData): Chord {
-    return new Chord(data);
-  }
-
-  /**
-   * Parse a lead-sheet chord symbol (e.g. `'Cmaj7'`, `'F#m7b5'`, `'C/G'`).
-   *
-   * @param symbol The chord symbol.
-   * @returns The chord (without key context).
-   * @throws If the root or quality is not recognized.
-   */
-  static parse(symbol: string): Chord {
-    return new Chord(parseChordSymbol(symbol));
-  }
-
-  /**
-   * Identify the chords matching a set of pitches, best interpretation first.
-   *
-   * @param pitches MIDI pitches or bare pitch classes.
-   * @returns Ranked chord interpretations (may be empty).
-   */
-  static detect(pitches: number[], opts?: DetectChordOptions): Chord[] {
-    return detectChord(pitches, opts).map(
-      (match) => new Chord(makeChord(match.rootPc, match.quality, match.bassPc)),
-    );
-  }
-
-  /**
-   * The single best chord interpretation of a pitch set.
-   *
-   * @param pitches MIDI pitches or bare pitch classes.
-   * @returns The top-ranked chord, or null when nothing matches.
-   */
-  static detectBest(pitches: number[], opts?: DetectChordOptions): Chord | null {
-    const best = detectChordBest(pitches, opts);
-    return best === null ? null : new Chord(best);
-  }
-
-  /** The root pitch class (0..11). */
-  get rootPc(): number {
-    return this.#data.rootPc;
-  }
-
-  /** The chord quality. */
-  get quality(): ChordQuality {
-    return this.#data.quality;
-  }
-
-  /** A copy of the semitone offsets above the root. */
-  get intervals(): number[] {
-    return [...this.#data.intervals];
-  }
-
-  /** The slash-chord bass pitch class, or undefined in root position. */
-  get bassPc(): number | undefined {
-    return this.#data.bassPc;
-  }
-
-  /** A copy of the underlying plain chord object. */
-  get data(): ChordData {
-    return copyChord(this.#data);
-  }
-
-  /** The carried key context, if any. */
-  get key(): Key | undefined {
-    return this.#key;
-  }
-
-  /**
-   * A copy of this chord carrying the given key context.
-   *
-   * @param key The key context to attach.
-   * @returns The new chord.
-   */
-  withKey(key: Key): Chord {
-    return new Chord(this.#data, key);
-  }
-
-  /**
-   * The chord's sorted, deduplicated pitch classes.
-   *
-   * @returns Pitch classes ascending in [0, 11].
-   */
-  pitchClasses(): number[] {
-    return chordPitchClasses(this.#data);
-  }
-
-  /**
-   * The chord's Roman numeral in a key.
-   *
-   * @param key Key to analyze in; falls back to the carried context.
-   * @returns The Roman numeral string.
-   * @throws If no key is given and none is carried.
-   */
-  roman(key?: Key): string {
-    return chordToRoman(this.#data, this.#resolveKey(key).scale);
-  }
-
-  /**
-   * The chord's harmonic function (tonic / subdominant / dominant) in a key.
-   *
-   * @param key Key to analyze in; falls back to the carried context.
-   * @returns The harmonic function.
-   * @throws If no key is given and none is carried.
-   */
-  function(key?: Key): HarmonicFunction {
-    return functionOf(this.#data, this.#resolveKey(key).scale);
-  }
-
-  /**
-   * Full functional analysis: function, borrowing, and Roman numeral.
-   *
-   * @param key Key to analyze in; falls back to the carried context.
-   * @returns The chord analysis.
-   * @throws If no key is given and none is carried.
-   */
-  analyze(key?: Key): ChordAnalysis {
-    return analyzeChord(this.#data, this.#resolveKey(key).scale);
-  }
-
-  /**
-   * Whether the chord is borrowed from the parallel mode (modal interchange).
-   *
-   * @param key Key to analyze in; falls back to the carried context.
-   * @returns True if the chord is borrowed.
-   * @throws If no key is given and none is carried.
-   */
-  isBorrowed(key?: Key): boolean {
-    return isBorrowedChord(this.#data, this.#resolveKey(key).scale);
-  }
-
-  /**
-   * The origin of a non-diatonic chord (parallel mode or Neapolitan), or null.
-   *
-   * @param key Key to analyze in; falls back to the carried context.
-   * @returns The borrowing source, or null.
-   * @throws If no key is given and none is carried.
-   */
-  borrowedSource(key?: Key): BorrowedSource {
-    return borrowedSource(this.#data, this.#resolveKey(key).scale);
-  }
-
-  /**
-   * The chord rendered as a lead-sheet symbol (e.g. `'Cmaj7'`, `'F#m7'`, `'C/G'`).
-   *
-   * @param opts Set `flats: true` to spell the root/bass with flats.
-   * @returns The chord symbol.
-   */
-  symbol(opts?: { flats?: boolean }): string {
-    return formatChordSymbol(this.#data, opts);
-  }
-
-  /**
-   * Realize the chord as one MIDI pitch per voice, ascending.
-   *
-   * @param opts Voicing options; defaults to four SATB voices.
-   * @returns MIDI pitches, ascending, one per voice.
-   * @throws If no voicing fits the given ranges.
-   */
-  voice(opts?: VoicingOptions): number[] {
-    return voiceChord(this.#data, opts);
-  }
-
-  /**
-   * Realize the chord as a single styled voicing (`close`, `drop2`, `drop3`,
-   * `shell`, or `rootless`), optionally constraining the top voice.
-   *
-   * @param opts Styled-voicing options; defaults to a close-position voicing.
-   * @returns MIDI pitches, ascending.
-   */
-  styledVoicing(opts?: StyledVoicingOptions): number[] {
-    return voiceChordStyled(this.#data, opts);
-  }
-
-  /**
-   * The negative-harmony mirror of the chord about the key's tonic–dominant
-   * axis (major becomes minor and vice versa).
-   *
-   * @param key Key providing the reflection axis; falls back to the carried
-   *   context.
-   * @returns The mirrored chord, keeping any key context.
-   * @throws If no key is given and none is carried.
-   */
-  negativeHarmony(key?: Key): Chord {
-    const resolved = this.#resolveKey(key);
-    // Retain the key that anchored the reflection (explicit first, then carried)
-    // so a later no-arg analysis method still has a key context.
-    return new Chord(negativeHarmonyMirror(this.#data, resolved.scale), key ?? this.#key);
-  }
-
-  /**
-   * The n-th inversion: a copy whose bass is the chord tone `n` steps above the
-   * root in the interval template (`invert(1)` puts the third in the bass).
-   * `n` wraps around the template length; negative values count backwards.
-   *
-   * `invert(0)` (and any `n` that wraps to it) is root position, so it carries
-   * no slash bass and equals the original chord.
-   *
-   * @param n The inversion number.
-   * @returns The inverted chord, keeping any key context.
-   * @throws If the chord has no intervals.
-   */
-  invert(n: number): Chord {
-    const intervals = this.#data.intervals;
-    const length = intervals.length;
-    if (length === 0) {
-      throw new Error('cannot invert a chord with no intervals');
-    }
-    const index = ((n % length) + length) % length;
-    const data = copyChord(this.#data);
-    if (index === 0) {
-      delete data.bassPc;
-      delete data.bassSpelling;
-    } else {
-      data.bassPc = mod12(this.#data.rootPc + (intervals[index] ?? 0));
-      const rootSpelling =
-        data.rootSpelling ??
-        (this.#key
-          ? spellPitchClass(data.rootPc, this.#key.tonic.data, this.#key.scale)
-          : spellPitchClassBare(data.rootPc, 'sharp'));
-      const bassSpelling = spellChordFromRoot(data, rootSpelling)[index];
-      if (bassSpelling !== undefined) {
-        data.bassSpelling = bassSpelling;
-      }
-    }
-    return new Chord(data, this.#key);
-  }
-
-  /**
-   * The named scales that fit over this chord, best fit first, rooted on the
-   * chord root.
-   *
-   * @returns The matching scales.
-   */
-  scales(): ChordScaleMatch[] {
-    return chordScales(this.#data);
-  }
-
-  /**
-   * The available tensions (usable non-chord, non-avoid scale tones) of a
-   * scale over this chord.
-   *
-   * @param scaleName A named scale, rooted on the chord root.
-   * @returns Tension pitch classes, ascending in [0, 11].
-   */
-  tensions(scaleName: string): number[] {
-    return availableTensions(this.#data, scaleName);
-  }
-
-  /**
-   * The avoid notes (scale tones a semitone above a chord tone) of a scale
-   * over this chord.
-   *
-   * @param scaleName A named scale, rooted on the chord root.
-   * @returns Avoid-note pitch classes, ascending in [0, 11].
-   */
-  avoidNotes(scaleName: string): number[] {
-    return avoidNotes(this.#data, scaleName);
-  }
-
-  /**
-   * Spell the chord tones with letter names, root first, in the key's spelling.
-   *
-   * @param key Key providing the spelled tonic; falls back to the carried
-   *   context.
-   * @returns Spelled octave-less notes in the chord's own (tertian) order.
-   * @throws If no key is given and none is carried.
-   */
-  spell(key?: Key): Note[] {
-    const resolved = this.#resolveKey(key);
-    return spellChord(this.#data, resolved.tonic.data, resolved.scale).map(
-      (note) => new Note(note),
-    );
-  }
-
-  /**
-   * Start a progression with this chord followed by others, carrying this
-   * chord's key context (if any).
-   *
-   * @param others The chords following this one.
-   * @returns The progression.
-   */
-  progressionTo(...others: Chord[]): Progression {
-    return new Progression([this, ...others], this.#key);
-  }
-
-  /**
-   * Whether another chord has the same root, quality, intervals, and bass.
-   * Key context is not compared.
-   *
-   * @param other The chord to compare.
-   * @returns True if the chord data is identical.
-   */
-  equals(other: Chord): boolean {
-    const a = this.#data;
-    const b = other.#data;
-    return (
-      a.rootPc === b.rootPc &&
-      a.quality === b.quality &&
-      a.bassPc === b.bassPc &&
-      a.intervals.length === b.intervals.length &&
-      a.intervals.every((interval, i) => interval === b.intervals[i])
-    );
-  }
-
-  /**
-   * The plain chord data, for JSON serialization.
-   *
-   * @returns A copy of the underlying plain chord object.
-   */
-  toJSON(): ChordData {
-    return this.data;
-  }
-
-  /** Resolve the key for an analysis method: explicit first, then carried. */
-  #resolveKey(key?: Key): Key {
-    const resolved = key ?? this.#key;
-    if (resolved === undefined) {
-      throw new Error('chord has no key context; pass a Key or attach one with withKey()');
-    }
-    return resolved;
-  }
-}

package/src/model/index.ts

@@ -1,15 +0,0 @@
-/**
- * Fluent, immutable object model over the functional core.
- *
- * Each class wraps one of the library's plain data types (spelled notes,
- * chords, key/scales) and delegates every operation to the existing pure
- * functions. All instances are immutable: fields are read-only, transforming
- * methods return new instances, and getters hand out defensive copies of any
- * mutable data.
- */
-
-export { Chord } from './chord.js';
-export { Interval } from './interval.js';
-export { Key } from './key.js';
-export { Note } from './note.js';
-export { Progression } from './progression.js';