@libraz/libcantus 0.9.0 → 0.9.2

package/src/generate/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Public API of the generate layer. Re-exports every generate-layer module;
+ * also available from the package root.
+ */
+export type { BassLineOptions, BassSegment, BassStyle } from './bass/index.js';
+export { generateBassLine } from './bass/index.js';
+export type { CounterMelodyOptions } from './countermelody/index.js';
+export { generateCounterMelody } from './countermelody/index.js';
+export type {
+  DrumHit,
+  DrumRole,
+  DrumsOptions,
+  EuclideanKick,
+  GrooveFeel,
+  GrooveStyle,
+  Section,
+} from './drums/index.js';
+export { generateDrums } from './drums/index.js';
+export type { GrooveSlot, GrooveTemplate, HumanizeOptions } from './groove/index.js';
+export { applyGrooveTemplate, extractGrooveTemplate, humanize } from './groove/index.js';
+export type {
+  HarmonizeOptions,
+  HarmonizeResult,
+  MelodyNote,
+} from './harmonize/index.js';
+export { harmonizeMelody } from './harmonize/index.js';
+export type {
+  MotifCell,
+  MotifContour,
+  MotifNote,
+  MotifOptions,
+  MotifTransform,
+} from './motif/index.js';
+export { developMotif, generateMotif, transformMotif } from './motif/index.js';
+export type {
+  ChordSpan,
+  ProgFunction,
+  ProgressionOptions,
+  ProgressionPreset,
+  ProgStyle,
+} from './progression/index.js';
+export {
+  generateProgression,
+  progressions,
+  progressionsByStyle,
+} from './progression/index.js';
+export type {
+  BorrowedChord,
+  SubstituteOptions,
+  Substitution,
+  SubstitutionType,
+} from './reharmony/index.js';
+export {
+  modalInterchangePalette,
+  negativeHarmonyMirror,
+  substituteChord,
+} from './reharmony/index.js';
+export type { RhythmEvent, RhythmOptions } from './rhythm/index.js';
+export { generateRhythm, onsetWeightCurve, rhythmDensity } from './rhythm/index.js';

package/src/{motif → generate/motif}/index.ts

@@ -1,10 +1,14 @@
-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';
+import type { ChordTimeline } from '../../analyze/timeline/index.js';
+import type { KeyScale } from '../../core/types.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { chordPitchClasses } from '../../theory/chord/index.js';
+import { isScaleTone, nearestScaleTone } from '../../theory/scale/index.js';
 
-/** A transformation applicable to a motif cell. */
+/**
+ * A transformation applicable to a motif cell.
+ *
+ * @category Composition
+ */
 export type MotifTransform =
   | 'transposeDiatonic'
   | 'transposeChromatic'
@@ -14,27 +18,62 @@ export type MotifTransform =
   | 'diminish'
   | 'sequence';
 
-/** A single note within a motif cell. */
+/**
+ * A single note within a motif cell.
+ *
+ * @category Composition
+ */
 export type MotifNote = {
   pitch: number;
   startBeat: number;
   durationBeat: number;
 };
 
-/** A short melodic cell. */
+/**
+ * A short melodic cell.
+ *
+ * @category Composition
+ */
 export type MotifCell = {
   notes: MotifNote[];
 };
 
-/** Melodic contour shape for {@link generateMotif}. */
+/**
+ * Melodic contour shape for {@link generateMotif}.
+ *
+ * @category Composition
+ */
 export type MotifContour = 'arch' | 'ascending' | 'descending' | 'wave';
 
-/** Options controlling {@link generateMotif}. */
-export type GenerateMotifOptions = {
+/**
+ * Options controlling {@link generateMotif}.
+ *
+ * @category Composition
+ */
+export type MotifOptions = {
   key: KeyScale;
   chord?: Chord | null;
   bars: number;
+  /**
+   * Melodic contour shape the line follows.
+   *
+   * @defaultValue `'arch'`
+   */
   contour?: MotifContour;
+  /**
+   * Probability in [0, 1] that a note is nudged by a single diatonic step. The
+   * nudge direction is balanced (up or down with equal odds), so it adds
+   * variety without biasing the line off its contour. Default 0, which
+   * reproduces the requested contour exactly (no drift, tails return to tonic).
+   *
+   * @defaultValue 0
+   */
+  jitter?: number;
+  /**
+   * Seed for the deterministic PRNG.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
 };
 
@@ -126,7 +165,6 @@ function mulberry32(seed: number): () => number {
 /** 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':
@@ -136,7 +174,9 @@ function contourOffsets(contour: MotifContour, count: number): number[] {
         offsets.push(-i);
         break;
       case 'arch':
-        offsets.push(i <= half ? i : count - 1 - i);
+        // Symmetric rise-and-fall: a palindrome that starts and ends on the
+        // tonic (offset 0) for both odd and even lengths.
+        offsets.push(Math.min(i, count - 1 - i));
         break;
       case 'wave':
         offsets.push([0, 1, 0, -1][i % 4] ?? 0);
@@ -151,24 +191,42 @@ function contourOffsets(contour: MotifContour, count: number): number[] {
  *
  * 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.
+ * are pulled to the nearest chord tone. An optional `jitter` adds balanced
+ * per-note variation without biasing the contour; it is off by default, so the
+ * contour is reproduced exactly. Output is deterministic for a given seed.
  *
- * @param opts Key, optional chord, length, contour, and seed.
+ * @param opts Key, optional chord, length, contour, jitter, and seed.
  * @returns The generated motif cell.
+ *
+ * @example
+ * ```ts
+ * import { generateMotif, majorKey } from '@libraz/libcantus';
+ * const cell = generateMotif({ key: majorKey(0), bars: 2, contour: 'arch' });
+ * // cell.notes is a deterministic MotifCell (seed defaults to 0)
+ * ```
+ *
+ * @category Composition
  */
-export function generateMotif(opts: GenerateMotifOptions): MotifCell {
+export function generateMotif(opts: MotifOptions): 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 jitterProb = Math.min(1, Math.max(0, opts.jitter ?? 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;
+    // Opt-in, direction-balanced jitter: disabled by default so the contour is
+    // preserved exactly. When enabled it nudges up or down with equal odds,
+    // avoiding the upward bias that used to drift arch/wave tails off the tonic.
+    let jitter = 0;
+    if (jitterProb > 0 && rng() < jitterProb) {
+      jitter = rng() < 0.5 ? 1 : -1;
+    }
     let pitch = stepDiatonic(tonic, (offsets[i] ?? 0) + jitter, opts.key);
     const startBeat = i * beatsPerNote;
     if (opts.chord && startBeat % 4 === 0) {
@@ -197,6 +255,15 @@ export function generateMotif(opts: GenerateMotifOptions): MotifCell {
  * @param key Key context for the diatonic transforms; without it,
  *   `transposeDiatonic` and `sequence` shift chromatically by semitones.
  * @returns The transformed cell.
+ *
+ * @example
+ * ```ts
+ * import { generateMotif, transformMotif, majorKey } from '@libraz/libcantus';
+ * const cell = generateMotif({ key: majorKey(0), bars: 1 });
+ * const inverted = transformMotif(cell, 'invert');
+ * ```
+ *
+ * @category Composition
  */
 export function transformMotif(
   cell: MotifCell,
@@ -279,6 +346,16 @@ function scaleTime(cell: MotifCell, factor: number): MotifCell {
  * @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.
+ *
+ * @example
+ * ```ts
+ * import { chordTimelineFromChords, developMotif, generateMotif, majorKey } from '@libraz/libcantus';
+ * const key = majorKey(0);
+ * const timeline = chordTimelineFromChords([{ rootPc: 0, quality: 'maj', startBeat: 0 }], 8);
+ * const developed = developMotif(generateMotif({ key, bars: 1 }), timeline, key, 2);
+ * ```
+ *
+ * @category Composition
  */
 export function developMotif(
   cell: MotifCell,

package/src/{progression → generate/progression}/index.ts

@@ -1,15 +1,29 @@
-import type { ChordQuality } from '../chord/index.js';
-import { diatonicTriad } from '../chord/index.js';
-import { scaleTonesInDegreeOrder } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
+import type { KeyScale } from '../../core/types.js';
+import type { ChordQuality, ChordSpan } from '../../theory/chord/index.js';
+import { diatonicTriad } from '../../theory/chord/index.js';
+import { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';
 
-/** Broad production style a progression preset suits. */
+export type { ChordSpan } from '../../theory/chord/index.js';
+
+/**
+ * Broad production style a progression preset suits.
+ *
+ * @category Composition
+ */
 export type ProgStyle = 'minimal' | 'dance' | 'idol' | 'rock';
 
-/** Harmonic-function role of a progression as a whole. */
+/**
+ * Harmonic-function role of a progression as a whole.
+ *
+ * @category Composition
+ */
 export type ProgFunction = 'loop' | 'tensionBuild' | 'cadenceStrong' | 'stable';
 
-/** A named chord-progression preset expressed in scale degrees. */
+/**
+ * A named chord-progression preset expressed in scale degrees.
+ *
+ * @category Composition
+ */
 export type ProgressionPreset = {
   id: string;
   name: string;
@@ -18,26 +32,23 @@ export type ProgressionPreset = {
   styles: ProgStyle[];
 };
 
-/** A chord placed on the timeline by {@link generateProgression}. */
-export type GeneratedChord = {
-  rootPc: number;
-  quality: ChordQuality;
-  startBeat: number;
-  bassPc?: number;
-  /** 0-based scale degree of the chord root, when known. */
-  degree?: number;
-  /** True when the chord is a secondary dominant tonicizing another degree. */
-  secondaryDominant?: boolean;
-};
-
-/** Options controlling {@link generateProgression}. */
-export type GenerateProgressionOptions = {
+/**
+ * Options controlling {@link generateProgression}.
+ *
+ * @category Composition
+ */
+export type ProgressionOptions = {
   key: KeyScale;
   style: ProgStyle;
   bars: number;
   presetId?: string;
   ext?: ChordQuality | 'auto';
   reharmonize?: boolean;
+  /**
+   * Seed for the deterministic preset choice and reharmonization.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
 };
 
@@ -208,12 +219,20 @@ const BORROWED_OFFSET: Record<number, number> = {
   14: 6, // #IV
 };
 
-/** All built-in progression presets. */
+/**
+ * All built-in progression presets.
+ *
+ * @category Composition
+ */
 export function progressions(): ProgressionPreset[] {
   return PRESETS.map((p) => ({ ...p, degrees: [...p.degrees], styles: [...p.styles] }));
 }
 
-/** Presets whose style list includes the given style. */
+/**
+ * Presets whose style list includes the given style.
+ *
+ * @category Composition
+ */
 export function progressionsByStyle(style: ProgStyle): ProgressionPreset[] {
   return progressions().filter((p) => p.styles.includes(style));
 }
@@ -264,7 +283,9 @@ function autoQuality(degree: number, key: KeyScale): ChordQuality {
  * Generate a chord progression laid out one chord per bar.
  *
  * A preset is chosen by `presetId` when given, otherwise deterministically from
- * the presets matching `style`, seeded by `seed`. The preset's degrees cycle to
+ * the presets matching `style`, seeded by `seed`. An unknown `presetId` is a
+ * caller error and throws rather than silently falling back to a random preset.
+ * The preset's degrees cycle to
  * fill `bars`; each bar is four beats, so `startBeat` is `barIndex * 4`. Chord
  * roots come from the key's diatonic scale-degree mapping. When `ext` is
  * omitted or `'auto'`, each chord takes its diatonic triad quality; otherwise
@@ -274,12 +295,25 @@ function autoQuality(degree: number, key: KeyScale): ChordQuality {
  *
  * @param opts Generation options.
  * @returns One chord per bar in timeline order.
+ * @throws If `presetId` is given but does not match any built-in preset.
+ *
+ * @example
+ * ```ts
+ * import { generateProgression, majorKey } from '@libraz/libcantus';
+ * const chords = generateProgression({ key: majorKey(0), style: 'dance', bars: 4 });
+ * // Deterministic for a given seed (defaults to 0); one ChordSpan per bar.
+ * ```
+ *
+ * @category Composition
  */
-export function generateProgression(opts: GenerateProgressionOptions): GeneratedChord[] {
+export function generateProgression(opts: ProgressionOptions): ChordSpan[] {
   const seed = opts.seed ?? 0;
   let preset: ProgressionPreset | undefined;
   if (opts.presetId !== undefined) {
     preset = PRESETS.find((p) => p.id === opts.presetId);
+    if (preset === undefined) {
+      throw new Error(`Unknown progression preset: ${opts.presetId}`);
+    }
   }
   if (preset === undefined) {
     const pool = PRESETS.filter((p) => p.styles.includes(opts.style));
@@ -289,12 +323,12 @@ export function generateProgression(opts: GenerateProgressionOptions): Generated
     preset = candidates[index] ?? PRESETS[0];
   }
   const degrees = preset?.degrees ?? [0];
-  const chords: GeneratedChord[] = [];
+  const chords: ChordSpan[] = [];
   for (let bar = 0; bar < opts.bars; bar += 1) {
     const degree = degrees[bar % degrees.length] ?? 0;
     const quality =
       opts.ext !== undefined && opts.ext !== 'auto' ? opts.ext : autoQuality(degree, opts.key);
-    const chord: GeneratedChord = {
+    const chord: ChordSpan = {
       rootPc: degreeToRootPc(degree, opts.key),
       quality,
       startBeat: bar * 4,

package/src/{reharmony → generate/reharmony}/index.ts

@@ -7,14 +7,7 @@
  * Roots are pitch classes (0..11); no spelled key signature is required.
  */
 
-import {
-  type Chord,
-  type ChordQuality,
-  chordPitchClasses,
-  diatonicTriad,
-  makeChord,
-} from '../chord/index.js';
-import { detectChordBest } from '../detect/index.js';
+import { detectChordBest } from '../../analyze/detect/index.js';
 import {
   type BorrowedSource,
   borrowedSource,
@@ -23,16 +16,27 @@ import {
   type HarmonicFunction,
   isDiatonic,
   parallelKey,
-} from '../functional/index.js';
-import { scaleTonesInDegreeOrder } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
+} from '../../analyze/functional/index.js';
+import type { KeyScale } from '../../core/types.js';
+import {
+  type Chord,
+  type ChordQuality,
+  chordPitchClasses,
+  diatonicTriad,
+  makeChord,
+} from '../../theory/chord/index.js';
+import { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';
 
 /** Reduce a value to a pitch class in [0, 11]. */
 function mod12(n: number): number {
   return ((n % 12) + 12) % 12;
 }
 
-/** The kind of substitution relationship a candidate realizes. */
+/**
+ * The kind of substitution relationship a candidate realizes.
+ *
+ * @category Reharmonization
+ */
 export type SubstitutionType =
   | 'tritone'
   | 'relative'
@@ -40,7 +44,11 @@ export type SubstitutionType =
   | 'chromatic-mediant'
   | 'secondary-dominant';
 
-/** A proposed chord substitution with its relationship, numeral, and function. */
+/**
+ * A proposed chord substitution with its relationship, numeral, and function.
+ *
+ * @category Reharmonization
+ */
 export type Substitution = {
   chord: Chord;
   type: SubstitutionType;
@@ -48,7 +56,11 @@ export type Substitution = {
   function: HarmonicFunction;
 };
 
-/** Options controlling which substitutions {@link substituteChord} returns. */
+/**
+ * Options controlling which substitutions {@link substituteChord} returns.
+ *
+ * @category Reharmonization
+ */
 export type SubstituteOptions = {
   /**
    * Melody pitch classes that must remain chord tones. When given, only
@@ -132,6 +144,13 @@ const THIRD_OFFSETS = [3, 4, 8, 9] as const;
  * @param key The prevailing key.
  * @param opts Optional melody-preservation constraint.
  * @returns The deduplicated substitution candidates.
+ * @example
+ * ```ts
+ * import { substituteChord, makeChord, majorKey } from '@libraz/libcantus';
+ * const subs = substituteChord(makeChord(7, 'dom7'), majorKey(0));
+ * // includes the tritone sub Db7 (rootPc 1, quality 'dom7')
+ * ```
+ * @category Reharmonization
  */
 export function substituteChord(
   chord: Chord,
@@ -214,7 +233,11 @@ export function substituteChord(
   return results;
 }
 
-/** A borrowed chord in the modal-interchange palette of a key. */
+/**
+ * A borrowed chord in the modal-interchange palette of a key.
+ *
+ * @category Reharmonization
+ */
 export type BorrowedChord = {
   chord: Chord;
   roman: string;
@@ -231,6 +254,7 @@ export type BorrowedChord = {
  *
  * @param key The prevailing key.
  * @returns The borrowed-chord palette.
+ * @category Reharmonization
  */
 export function modalInterchangePalette(key: KeyScale): BorrowedChord[] {
   const palette: BorrowedChord[] = [];
@@ -275,6 +299,13 @@ export function modalInterchangePalette(key: KeyScale): BorrowedChord[] {
  * @param chord The chord to reflect.
  * @param key The prevailing key.
  * @returns The negative-harmony counterpart of the chord.
+ * @example
+ * ```ts
+ * import { negativeHarmonyMirror, makeChord, majorKey } from '@libraz/libcantus';
+ * negativeHarmonyMirror(makeChord(7, 'maj'), majorKey(0));
+ * // G major reflected across C's axis => F minor (rootPc 5, quality 'min')
+ * ```
+ * @category Reharmonization
  */
 export function negativeHarmonyMirror(chord: Chord, key: KeyScale): Chord {
   const tonic = mod12(key.rootPc);

package/src/{rhythm → generate/rhythm}/index.ts

@@ -11,10 +11,14 @@
  * library-wide convention.
  */
 
-import { beatsPerBar, metricWeight, type TimeSignature } from '../meter/index.js';
-import { createRng } from '../random/index.js';
+import { beatsPerBar, metricWeight, type TimeSignature } from '../../core/meter/index.js';
+import { createRng } from '../../core/random/index.js';
 
-/** A single rhythmic note: an onset position and how long it sounds. */
+/**
+ * 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;
@@ -22,21 +26,38 @@ export type RhythmEvent = {
   duration: number;
 };
 
-/** Options controlling {@link generateRhythm}. */
+/**
+ * Options controlling {@link generateRhythm}.
+ *
+ * @category Rhythm & Meter
+ */
 export type RhythmOptions = {
-  /** Seed for the deterministic PRNG. Default 0. */
+  /**
+   * Seed for the deterministic PRNG.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
-  /** Number of bars to generate. Default 1. */
+  /**
+   * 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. Default 0.5.
+   * higher values fill more grid slots. Values outside [0, 1] are clamped into
+   * range.
+   *
+   * @defaultValue 0.5
    */
   density?: number;
 };
@@ -53,6 +74,7 @@ const DEFAULT_BARS = 1;
  *
  * @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) {
@@ -71,29 +93,40 @@ export function onsetWeightCurve(weight: number): number {
  * 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. The first slot (the downbeat) is always an
- * onset. Each event's duration extends to the next onset, and the last event
- * extends to the end of the span.
+ * 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 density = opts.density ?? DEFAULT_DENSITY;
+  const density = Math.min(1, Math.max(0, opts.density ?? DEFAULT_DENSITY));
 
-  const spanBeats = beatsPerBar(ts) * bars;
+  const barBeats = beatsPerBar(ts);
+  const spanBeats = barBeats * bars;
   const step = 1 / subdivision;
   const slotCount = Math.round(spanBeats * subdivision);
+  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;
-    if (i === 0) {
+    // Force every bar's downbeat so the pulse is reliable regardless of seed.
+    if (i % slotsPerBar === 0) {
       positions.push(position);
       continue;
     }
@@ -119,6 +152,7 @@ export function generateRhythm(ts: TimeSignature, opts: RhythmOptions = {}): Rhy
  * @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) {