@libraz/libcantus 0.9.0 → 0.9.1

package/src/harmonize/index.ts

@@ -5,23 +5,46 @@ import { roleOf } from '../harmony/index.js';
 import type { TimeSignature } from '../meter/index.js';
 import { isStrongBeat } from '../meter/index.js';
 import type { GeneratedChord } from '../progression/index.js';
-import { isScaleTone, majorKey, scaleTonesInDegreeOrder } from '../scale/index.js';
+import {
+  isScaleTone,
+  majorKey,
+  minorKey,
+  NATURAL_MINOR_MASK,
+  scaleTonesInDegreeOrder,
+} from '../scale/index.js';
 import type { KeyScale, NoteEvent } from '../types.js';
 
-/** A melody note supplied to the harmonizer: a {@link NoteEvent}. */
+/**
+ * A melody note supplied to the harmonizer: a {@link NoteEvent}.
+ *
+ * @category Reharmonization
+ */
 export type MelodyNote = NoteEvent;
 
-/** Options controlling {@link harmonizeMelody}. */
+/**
+ * Options controlling {@link harmonizeMelody}.
+ *
+ * @category Reharmonization
+ */
 export type HarmonizeOptions = {
   melody: MelodyNote[];
   key: KeyScale | 'infer';
   harmonicRhythm: number;
   reharmonize: 'diatonic' | 'secondaryDominant' | 'borrowed';
   placement: { transposeSearch: boolean; octaveSearch: boolean };
+  /**
+   * Seed for the deterministic tie-break perturbation.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
 };
 
-/** The chosen transpose, key, chord path, and per-note roles. */
+/**
+ * The chosen transpose, key, chord path, and per-note roles.
+ *
+ * @category Reharmonization
+ */
 export type HarmonizeResult = {
   transposeSemitones: number;
   key: KeyScale;
@@ -50,6 +73,15 @@ const COMFORT_LOW = 55;
 const COMFORT_HIGH = 79;
 const TESSITURA_WEIGHT = 0.001;
 
+/**
+ * Magnitude of the seed-driven per-candidate perturbation. Kept far below the
+ * smallest real cost difference (transition/emission terms are on the order of
+ * 0.3 and up), so it can only decide between candidates or paths whose costs are
+ * otherwise exactly equal. The seed therefore breaks ties deterministically and
+ * never overrides melody fit or functional flow.
+ */
+const TIE_BREAK_JITTER = 1e-6;
+
 function pitchClass(pitch: number): number {
   return ((Math.trunc(pitch) % 12) + 12) % 12;
 }
@@ -65,28 +97,47 @@ function mulberry32(seed: number): () => number {
   };
 }
 
-/** Estimate the best-fit major key from a melody's pitch-class weighting. */
+/**
+ * Estimate the best-fit key from a melody's pitch-class weighting.
+ *
+ * Both major and natural-minor tonics are scored, so a minor melody is
+ * recognized as its own minor key rather than being folded into the relative
+ * major (which shares identical pitch-class content). Each in-scale note adds
+ * its duration weight; notes matching the candidate tonic add a further
+ * half-weight, and that tonic emphasis is what separates a minor key from its
+ * relative major. For minor candidates the raised leading tone (the
+ * harmonic-minor seventh) also counts as in-scale, so cadential leading tones do
+ * not penalize the true minor key. Ties are broken toward the earlier candidate,
+ * and major is scored before minor at each tonic.
+ */
 function inferKey(melody: MelodyNote[]): KeyScale {
-  let best = 0;
+  let best: KeyScale = majorKey(0);
   let bestScore = Number.NEGATIVE_INFINITY;
+  const candidates: KeyScale[] = [];
   for (let tonic = 0; tonic < 12; tonic += 1) {
-    const key = majorKey(tonic);
+    candidates.push(majorKey(tonic), minorKey(tonic));
+  }
+  for (const key of candidates) {
+    const tonic = pitchClass(key.rootPc);
+    const isMinor = key.modeMask12 === NATURAL_MINOR_MASK;
+    const leadingTone = (tonic + 11) % 12;
     let score = 0;
     for (const n of melody) {
       const w = Math.max(0.25, n.durationBeat);
-      if (isScaleTone(n.pitch, key)) {
+      const pc = pitchClass(n.pitch);
+      if (isScaleTone(n.pitch, key) || (isMinor && pc === leadingTone)) {
         score += w;
       }
-      if (pitchClass(n.pitch) === tonic) {
+      if (pc === tonic) {
         score += 0.5 * w;
       }
     }
     if (score > bestScore) {
       bestScore = score;
-      best = tonic;
+      best = key;
     }
   }
-  return majorKey(best);
+  return best;
 }
 
 /** Enumerate candidate chords for the key, gated by reharmonization strength. */
@@ -283,16 +334,38 @@ function harmonizeOnce(
  * `(transpose, progression)` pair is returned; a small tessitura cost breaks
  * ties toward placements that keep the melody in a comfortable register.
  *
+ * The `seed` drives a deterministic tie-break only: it perturbs candidates by a
+ * magnitude far below any real cost difference (see {@link TIE_BREAK_JITTER}),
+ * so it can decide between chords or paths of otherwise-equal cost but never
+ * overrides melody fit or functional flow. For a well-determined melody the
+ * result is identical across seeds; the same seed always yields the same result.
+ *
  * @param opts Melody, key (or `'infer'`), harmonic rhythm, reharmonization
  *   strength, height-search flags, and seed.
  * @returns The chosen transpose, key, chord path, and per-note roles.
+ * @example
+ * ```ts
+ * import { harmonizeMelody, majorKey } from '@libraz/libcantus';
+ * const result = harmonizeMelody({
+ *   melody: [
+ *     { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *     { pitch: 64, startBeat: 1, durationBeat: 1 },
+ *   ],
+ *   key: majorKey(0),
+ *   harmonicRhythm: 1,
+ *   reharmonize: 'diatonic',
+ *   placement: { transposeSearch: false, octaveSearch: false },
+ * });
+ * result.chords; // one GeneratedChord per harmonic-rhythm segment
+ * ```
+ * @category Reharmonization
  */
 export function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult {
   const key = opts.key === 'infer' ? inferKey(opts.melody) : opts.key;
   const candidates = buildCandidates(key, opts.reharmonize);
   const candAt = (i: number): Candidate => candidates[i] ?? FALLBACK;
   const rng = mulberry32(opts.seed ?? 0);
-  const jitter = candidates.map(() => rng() * 1e-6);
+  const jitter = candidates.map(() => rng() * TIE_BREAK_JITTER);
 
   const melodyEnd = opts.melody.reduce((m, n) => Math.max(m, n.startBeat + n.durationBeat), 0);
   const hr = Math.max(0.25, opts.harmonicRhythm);

package/src/harmony/index.ts

@@ -1,6 +1,10 @@
 import type { Chord } from '../chord/index.js';
 
-/** Harmonic role a pitch plays within a chord. */
+/**
+ * Harmonic role a pitch plays within a chord.
+ *
+ * @category Functional Harmony
+ */
 export type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'tension' | 'doubling';
 
 /**
@@ -9,10 +13,16 @@ export type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'te
  * - `identity`: moving it produces a different chord (the root).
  * - `quality`: moving it flips the chord quality (the third).
  * - `voicing`: it can move freely without changing chord identity or quality.
+ *
+ * @category Functional Harmony
  */
 export type LockLevel = 'identity' | 'quality' | 'voicing';
 
-/** A pitch's role, lock level, and owning chord. */
+/**
+ * A pitch's role, lock level, and owning chord.
+ *
+ * @category Functional Harmony
+ */
 export type VoicedRole = {
   role: HarmonyRole;
   lock: LockLevel;
@@ -36,6 +46,13 @@ export type VoicedRole = {
  * @param chord The chord providing the root reference.
  * @param chordId Identifier stored on the result (defaults to 0).
  * @returns The pitch's role, lock level, and owning chord id.
+ * @example
+ * ```ts
+ * import { roleOf, makeChord } from '@libraz/libcantus';
+ * roleOf(64, makeChord(0, 'maj')); // E over C major
+ * // { role: 'third', lock: 'quality', belongsToChordId: 0 }
+ * ```
+ * @category Functional Harmony
  */
 export function roleOf(pitch: number, chord: Chord, chordId = 0): VoicedRole {
   const interval = (((Math.trunc(pitch) - chord.rootPc) % 12) + 12) % 12;

package/src/index.ts

@@ -51,6 +51,7 @@ export type {
   DrumGenOptions,
   DrumHit,
   DrumRole,
+  EuclideanKick,
   GrooveFeel,
   GrooveStyle,
   Section,

package/src/interval/index.ts

@@ -1,4 +1,8 @@
-/** Counterpoint classification of a harmonic interval. */
+/**
+ * Counterpoint classification of a harmonic interval.
+ *
+ * @category Pitch & Intervals
+ */
 export enum IntervalQuality {
   PerfectConsonance = 0,
   ImperfectConsonance = 1,
@@ -21,6 +25,14 @@ function simpleInterval(semitones: number): number {
  * @param semitones Interval size in semitones (may be negative or compound).
  * @param twoVoice When true, the perfect fourth is treated as dissonant.
  * @returns The counterpoint quality of the interval.
+ * @example
+ * ```ts
+ * import { classifyInterval, IntervalQuality } from '@libraz/libcantus';
+ * classifyInterval(7); // IntervalQuality.PerfectConsonance
+ * classifyInterval(5); // IntervalQuality.Dissonance (two-voice)
+ * classifyInterval(5, false); // IntervalQuality.ImperfectConsonance
+ * ```
+ * @category Pitch & Intervals
  */
 export function classifyInterval(semitones: number, twoVoice = true): IntervalQuality {
   const pc = simpleInterval(semitones);
@@ -41,6 +53,7 @@ export function classifyInterval(semitones: number, twoVoice = true): IntervalQu
  *
  * @param semitones Interval size in semitones (may be negative or compound).
  * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.
+ * @category Pitch & Intervals
  */
 export function isPerfectInterval(semitones: number): boolean {
   const pc = simpleInterval(semitones);
@@ -57,6 +70,7 @@ export function isPerfectInterval(semitones: number): boolean {
  * @param semitones Interval size in semitones (may be negative or compound).
  * @param twoVoice When true, the perfect fourth is treated as dissonant.
  * @returns True if the interval is consonant in the given context.
+ * @category Pitch & Intervals
  */
 export function isConsonantInterval(semitones: number, twoVoice = true): boolean {
   const pc = simpleInterval(semitones);

package/src/meter/index.ts

@@ -6,13 +6,31 @@
  * 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. */
+/**
+ * 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. */
+/**
+ * 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. */
@@ -36,6 +54,12 @@ function isMultiple(value: number, unit: number): boolean {
  * @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);
@@ -50,7 +74,11 @@ export function parseTimeSignature(text: string): TimeSignature {
   return { numerator, denominator };
 }
 
-/** Render a time signature as `"n/d"`. */
+/**
+ * Render a time signature as `"n/d"`.
+ *
+ * @category Rhythm & Meter
+ */
 export function formatTimeSignature(ts: TimeSignature): string {
   return `${ts.numerator}/${ts.denominator}`;
 }
@@ -63,6 +91,7 @@ export function formatTimeSignature(ts: TimeSignature): string {
  *
  * @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;
@@ -78,6 +107,7 @@ function unitBeats(ts: TimeSignature): number {
  *
  * @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);
@@ -92,19 +122,63 @@ function pulseBeats(ts: TimeSignature): number {
  * 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);
@@ -119,6 +193,7 @@ export function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): Ba
  * @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;
@@ -126,12 +201,28 @@ export function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number {
 
 /**
  * Metric weight of a position within its bar, on a 0–3 scale:
- * 3 the downbeat, 2 a secondary strong pulse (the bar's midpoint in even
- * meters), 1 any other main pulse, and 0 an off-pulse subdivision.
+ * 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);
@@ -144,6 +235,16 @@ export function metricWeight(beatInQuarters: number, ts: TimeSignature): number
   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;
   }
@@ -157,6 +258,7 @@ export function metricWeight(beatInQuarters: number, ts: TimeSignature): number
  * @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;
@@ -170,6 +272,7 @@ export function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean
  * @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) {