@libraz/libcantus 0.9.0 → 0.9.1

package/src/tuning/index.ts

@@ -11,6 +11,8 @@
 /**
  * An equal-tempered tuning: a reference pitch and a number of equal divisions of
  * the octave. With `divisions === 12` a step index is an ordinary MIDI number.
+ *
+ * @category Pitch & Intervals
  */
 export type Tuning = {
   /** Step index (MIDI number when `divisions` is 12) whose frequency is `refFreq`. */
@@ -21,7 +23,11 @@ export type Tuning = {
   divisions: number;
 };
 
-/** Standard twelve-tone equal temperament, A4 (MIDI 69) = 440 Hz. */
+/**
+ * Standard twelve-tone equal temperament, A4 (MIDI 69) = 440 Hz.
+ *
+ * @category Pitch & Intervals
+ */
 export const TWELVE_TET: Tuning = { refStep: 69, refFreq: 440, divisions: 12 };
 
 /**
@@ -31,6 +37,13 @@ export const TWELVE_TET: Tuning = { refStep: 69, refFreq: 440, divisions: 12 };
  * @param refFreq Reference frequency in Hz (default 440).
  * @param refStep Step index of the reference (default 69).
  * @returns The tuning.
+ * @example
+ * ```ts
+ * import { edo, frequencyOf } from '@libraz/libcantus';
+ * const et19 = edo(19); // { refStep: 69, refFreq: 440, divisions: 19 }
+ * frequencyOf(70, et19); // one 19-EDO step above A4
+ * ```
+ * @category Pitch & Intervals
  */
 export function edo(n: number, refFreq = 440, refStep = 69): Tuning {
   return { refStep, refFreq, divisions: n };
@@ -42,6 +55,13 @@ export function edo(n: number, refFreq = 440, refStep = 69): Tuning {
  * @param step Step index (a MIDI number under 12-EDO).
  * @param tuning The tuning (default 12-TET).
  * @returns The frequency in Hz.
+ * @example
+ * ```ts
+ * import { frequencyOf } from '@libraz/libcantus';
+ * frequencyOf(69); // 440 (A4 in 12-TET)
+ * frequencyOf(60); // middle C in Hz
+ * ```
+ * @category Pitch & Intervals
  */
 export function frequencyOf(step: number, tuning: Tuning = TWELVE_TET): number {
   return tuning.refFreq * 2 ** ((step - tuning.refStep) / tuning.divisions);
@@ -54,6 +74,7 @@ export function frequencyOf(step: number, tuning: Tuning = TWELVE_TET): number {
  * @param freq Frequency in Hz.
  * @param tuning The tuning (default 12-TET).
  * @returns The nearest step index.
+ * @category Pitch & Intervals
  */
 export function nearestStep(freq: number, tuning: Tuning = TWELVE_TET): number {
   return Math.round(tuning.refStep + tuning.divisions * Math.log2(freq / tuning.refFreq));
@@ -65,6 +86,7 @@ export function nearestStep(freq: number, tuning: Tuning = TWELVE_TET): number {
  * @param a Lower/first frequency in Hz.
  * @param b Upper/second frequency in Hz.
  * @returns Cents from `a` to `b` (negative if `b` is lower).
+ * @category Pitch & Intervals
  */
 export function centsBetweenFreq(a: number, b: number): number {
   return 1200 * Math.log2(b / a);
@@ -76,6 +98,7 @@ export function centsBetweenFreq(a: number, b: number): number {
  * @param steps Number of steps.
  * @param tuning The tuning (default 12-TET).
  * @returns The cents.
+ * @category Pitch & Intervals
  */
 export function centsOfSteps(steps: number, tuning: Tuning = TWELVE_TET): number {
   return (steps * 1200) / tuning.divisions;
@@ -88,6 +111,7 @@ export function centsOfSteps(steps: number, tuning: Tuning = TWELVE_TET): number
  * @param numerator Ratio numerator.
  * @param denominator Ratio denominator.
  * @returns The interval in cents.
+ * @category Pitch & Intervals
  */
 export function ratioToCents(numerator: number, denominator: number): number {
   return 1200 * Math.log2(numerator / denominator);
@@ -96,6 +120,8 @@ export function ratioToCents(numerator: number, denominator: number): number {
 /**
  * Five-limit just-intonation ratios for the twelve interval classes above a
  * unison, indexed by semitone class (0..12).
+ *
+ * @category Pitch & Intervals
  */
 export const JUST_RATIOS: Record<number, [number, number]> = {
   0: [1, 1],
@@ -119,6 +145,7 @@ export const JUST_RATIOS: Record<number, [number, number]> = {
  *
  * @param semitoneClass Semitone class in [0, 12].
  * @returns The deviation in cents, or NaN if the class has no listed ratio.
+ * @category Pitch & Intervals
  */
 export function justDeviationCents(semitoneClass: number): number {
   const ratio = JUST_RATIOS[semitoneClass];

package/src/voicing/index.ts

@@ -1,14 +1,18 @@
 import type { Chord } from '../chord/index.js';
 import { chordPitchClasses, chordToneRole } from '../chord/index.js';
 import {
-  createsParallelOctave,
+  createsHiddenParallelPerfect,
   createsParallelPerfect,
   createsVoiceCrossing,
   createsVoiceOverlap,
   exceedsSpacing,
 } from '../counterpoint/index.js';
 
-/** An inclusive MIDI pitch range for a single voice. */
+/**
+ * An inclusive MIDI pitch range for a single voice.
+ *
+ * @category Voicing & Counterpoint
+ */
 export type VoiceRange = {
   min: number;
   max: number;
@@ -18,6 +22,8 @@ export type VoiceRange = {
  * Default four-voice SATB ranges, ascending (index 0 = lowest):
  * bass E2–C4 (40–60), tenor C3–G4 (48–67), alto G3–D5 (55–74),
  * soprano C4–G5 (60–79).
+ *
+ * @category Voicing & Counterpoint
  */
 export const SATB_RANGES: readonly VoiceRange[] = [
   { min: 40, max: 60 },
@@ -26,13 +32,25 @@ export const SATB_RANGES: readonly VoiceRange[] = [
   { min: 60, max: 79 },
 ];
 
-/** Options controlling {@link voiceChord} and {@link voiceProgression}. */
+/**
+ * Options controlling {@link voiceChord} and {@link voiceProgression}.
+ *
+ * @category Voicing & Counterpoint
+ */
 export type VoicingOptions = {
-  /** Number of voices to realize (default 4). Ignored when `ranges` is given. */
+  /**
+   * Number of voices to realize. Ignored when `ranges` is given.
+   *
+   * @defaultValue 4
+   */
   voices?: number;
   /** Explicit per-voice ranges, ascending (index 0 = lowest). Takes precedence over `voices`. */
   ranges?: VoiceRange[];
-  /** Maximum spacing in semitones between adjacent upper voices (default 12). */
+  /**
+   * Maximum spacing in semitones between adjacent upper voices.
+   *
+   * @defaultValue 12
+   */
   maxSpacing?: number;
 };
 
@@ -51,6 +69,13 @@ const VIOLATION_PENALTY = 1000;
 const MISSING_TONE_PENALTY = 500;
 /** Score penalty per doubled tone that is neither the root nor the fifth. */
 const POOR_DOUBLING_PENALTY = 4;
+/**
+ * Moderate penalty for a hidden/direct perfect fifth or octave reached on the
+ * outer-voice (bass–soprano) pair. Unlike a true parallel perfect it is
+ * discouraged rather than forbidden, so the weight sits alongside voice-leading
+ * motion rather than the hard {@link VIOLATION_PENALTY}.
+ */
+const HIDDEN_PERFECT_PENALTY = 6;
 /** Hard cap on candidate voicings evaluated per chord, keeping the search bounded. */
 const MAX_CANDIDATES = 4000;
 
@@ -91,7 +116,13 @@ function resolveRanges(opts?: VoicingOptions): VoiceRange[] {
   return ranges;
 }
 
-/** All MIDI pitches of a pitch class inside an inclusive range, ascending. */
+/**
+ * All MIDI pitches of a pitch class inside an inclusive range, ordered from the
+ * centre of the range outward (ties break toward the lower pitch). Enumerating
+ * centre-outward keeps the candidate set balanced around the register when it
+ * is truncated at {@link MAX_CANDIDATES}, instead of skewing to the low octaves
+ * that a plain ascending scan would visit first.
+ */
 function pitchesForPc(pc: number, range: VoiceRange): number[] {
   const result: number[] = [];
   for (let midi = Math.ceil(range.min); midi <= range.max; midi += 1) {
@@ -99,7 +130,12 @@ function pitchesForPc(pc: number, range: VoiceRange): number[] {
       result.push(midi);
     }
   }
-  return result;
+  const center = (range.min + range.max) / 2;
+  return result.sort((a, b) => {
+    const da = Math.abs(a - center);
+    const db = Math.abs(b - center);
+    return da === db ? a - b : da - db;
+  });
 }
 
 /**
@@ -178,9 +214,10 @@ function structuralPenalty(pitches: number[], chord: Chord): number {
 
 /**
  * Count counterpoint violations between two consecutive voicings of equal
- * length: parallel perfects and parallel octaves on every voice pair, voice
- * crossings in the new voicing, and — on adjacent pairs — voice overlaps and
- * over-wide spacing between upper voices.
+ * length: parallel perfects (fifths and octaves alike, since octaves are the
+ * perfect-class-zero case of {@link createsParallelPerfect}) on every voice
+ * pair, voice crossings in the new voicing, and — on adjacent pairs — voice
+ * overlaps and over-wide spacing between upper voices.
  */
 function violationCount(prev: number[], cur: number[], maxSpacing: number): number {
   let count = 0;
@@ -201,9 +238,6 @@ function violationCount(prev: number[], cur: number[], maxSpacing: number): numb
       if (createsParallelPerfect(prevUpper, curUpper, prevLower, curLower)) {
         count += 1;
       }
-      if (createsParallelOctave(prevUpper, curUpper, prevLower, curLower)) {
-        count += 1;
-      }
       if (createsVoiceCrossing(curUpper, curLower)) {
         count += 1;
       }
@@ -222,12 +256,16 @@ function violationCount(prev: number[], cur: number[], maxSpacing: number): numb
 
 /**
  * Total voice-leading cost between two voicings: the sum of absolute semitone
- * motion across voices. The arrays must be the same length; when they differ
- * the voicings are not comparable and the cost is `Infinity`.
+ * motion across voices, plus a moderate {@link HIDDEN_PERFECT_PENALTY} when the
+ * outer-voice (bass–soprano) pair reaches a hidden/direct perfect fifth or
+ * octave by similar motion. The arrays must be the same length; when they
+ * differ the voicings are not comparable and the cost is `Infinity`.
  *
  * @param from The previous voicing, one MIDI pitch per voice.
  * @param to The next voicing, one MIDI pitch per voice.
- * @returns The summed absolute motion, or `Infinity` when lengths differ.
+ * @returns The summed absolute motion (plus any hidden-perfect penalty), or
+ *   `Infinity` when lengths differ.
+ * @category Voicing & Counterpoint
  */
 export function voiceLeadingCost(from: number[], to: number[]): number {
   if (from.length !== to.length) {
@@ -242,6 +280,23 @@ export function voiceLeadingCost(from: number[], to: number[]): number {
     }
     total += Math.abs(b - a);
   }
+  // Discourage hidden/direct perfects between the outermost voices, where they
+  // are most audible. True parallels are handled (and forbidden) elsewhere.
+  if (from.length >= 2) {
+    const bassPrev = from[0];
+    const bassCur = to[0];
+    const sopPrev = from[from.length - 1];
+    const sopCur = to[to.length - 1];
+    if (
+      bassPrev !== undefined &&
+      bassCur !== undefined &&
+      sopPrev !== undefined &&
+      sopCur !== undefined &&
+      createsHiddenParallelPerfect(bassPrev, bassCur, sopPrev, sopCur)
+    ) {
+      total += HIDDEN_PERFECT_PENALTY;
+    }
+  }
   return total;
 }
 
@@ -257,6 +312,13 @@ export function voiceLeadingCost(from: number[], to: number[]): number {
  * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
  * @returns MIDI pitches, ascending, one per voice.
  * @throws If no voicing fits the given ranges.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, voiceChord } from '@libraz/libcantus';
+ * const chord = parseChordSymbol('Cmaj7');
+ * voiceChord(chord); // four ascending MIDI pitches within the SATB ranges
+ * ```
+ * @category Voicing & Counterpoint
  */
 export function voiceChord(chord: Chord, opts?: VoicingOptions): number[] {
   const ranges = resolveRanges(opts);
@@ -299,6 +361,13 @@ export function voiceChord(chord: Chord, opts?: VoicingOptions): number[] {
  * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
  * @returns One voicing per chord, each ascending with one MIDI pitch per voice.
  * @throws If any chord admits no voicing within the given ranges.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, voiceProgression } from '@libraz/libcantus';
+ * const chords = ['C', 'Am', 'F', 'G'].map((s) => parseChordSymbol(s));
+ * voiceProgression(chords); // one four-voice voicing per chord, smoothly led
+ * ```
+ * @category Voicing & Counterpoint
  */
 export function voiceProgression(chords: Chord[], opts?: VoicingOptions): number[][] {
   const ranges = resolveRanges(opts);
@@ -343,18 +412,36 @@ export function voiceProgression(chords: Chord[], opts?: VoicingOptions): number
  *   root/third/fifth for triads; the fifth and tensions are omitted.
  * - `rootless`: the root omitted, keeping third/fifth/seventh and tensions
  *   (a typical left-hand jazz voicing).
+ *
+ * @category Voicing & Counterpoint
  */
 export type VoicingStyle = 'close' | 'drop2' | 'drop3' | 'shell' | 'rootless';
 
-/** Options controlling {@link voiceChordStyled}. */
+/**
+ * Options controlling {@link voiceChordStyled}.
+ *
+ * @category Voicing & Counterpoint
+ */
 export type StyledVoicingOptions = {
-  /** Voicing style to build (default `close`). */
+  /**
+   * Voicing style to build.
+   *
+   * @defaultValue 'close'
+   */
   style?: VoicingStyle;
   /** Constrain the highest voice to this pitch class (0..11) when given. */
   topNote?: number;
-  /** Base octave for the close stack; the stack begins near `12 * octave` (default 4). */
+  /**
+   * Base octave for the close stack; the stack begins near `12 * octave`.
+   *
+   * @defaultValue 4
+   */
   octave?: number;
-  /** Omit the root regardless of style (relevant for jazz voicings). */
+  /**
+   * Omit the root regardless of style (relevant for jazz voicings).
+   *
+   * @defaultValue false
+   */
   rootless?: boolean;
 };
 
@@ -408,6 +495,13 @@ function nearestPc(target: number, pcs: number[]): number {
  * @param chord The chord to voice.
  * @param opts Styled voicing options; defaults to a close voicing at octave 4.
  * @returns MIDI pitches, ascending, one per retained voice.
+ * @example
+ * ```ts
+ * import { parseChordSymbol, voiceChordStyled } from '@libraz/libcantus';
+ * const chord = parseChordSymbol('Dm7');
+ * voiceChordStyled(chord, { style: 'drop2' }); // ascending MIDI pitches, drop-2 voicing
+ * ```
+ * @category Voicing & Counterpoint
  */
 export function voiceChordStyled(chord: Chord, opts?: StyledVoicingOptions): number[] {
   const style = opts?.style ?? 'close';
@@ -496,12 +590,18 @@ export function voiceChordStyled(chord: Chord, opts?: StyledVoicingOptions): num
  * @param opts Voicing options; when omitted, ranges follow `current`'s span.
  * @returns The chosen voicing, ascending with one MIDI pitch per voice.
  * @throws If no voicing fits the derived ranges.
+ * @category Voicing & Counterpoint
  */
 export function nextVoicing(current: number[], chord: Chord, opts?: VoicingOptions): number[] {
   const ranges =
     opts?.ranges !== undefined || opts?.voices !== undefined
       ? resolveRanges(opts)
-      : current.map((pitch) => ({ min: pitch - 12, max: pitch + 12 }));
+      : current.map((pitch) => {
+          // Window one octave around each current pitch, clamped so extreme-low
+          // or extreme-high input can never yield MIDI outside [0, 127].
+          const centre = Math.min(127, Math.max(0, pitch));
+          return { min: Math.max(0, centre - 12), max: Math.min(127, centre + 12) };
+        });
   const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
   const candidates = enumerateVoicings(chord, ranges, maxSpacing);
   let best: number[] | undefined;