@libraz/libcantus 0.9.3 → 0.9.4

package/src/theory/voicing/satb.ts

@@ -1,216 +0,0 @@
-import {
-  assertFiniteNumber,
-  assertGenerationBudget,
-  assertPositiveInt,
-} from '../../core/validation/index.js';
-import type { Chord } from '../chord/index.js';
-import {
-  DEFAULT_MAX_SPACING,
-  enumerateVoicings,
-  structuralPenalty,
-  VIOLATION_PENALTY,
-  violationCount,
-} from './internal.js';
-import { voiceLeadingCost } from './leading.js';
-
-/**
- * An inclusive MIDI pitch range for a single voice.
- *
- * @category Voicing & Counterpoint
- */
-export type VoiceRange = {
-  min: number;
-  max: number;
-};
-
-/**
- * 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 },
-  { min: 48, max: 67 },
-  { min: 55, max: 74 },
-  { min: 60, max: 79 },
-];
-
-/**
- * Options controlling {@link voiceChord} and {@link voiceProgression}.
- *
- * @category Voicing & Counterpoint
- */
-export type VoicingOptions = {
-  /**
-   * 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.
-   *
-   * @defaultValue 12
-   */
-  maxSpacing?: number;
-};
-
-/** Overall pitch floor/ceiling used when deriving ranges for arbitrary voice counts. */
-const DERIVED_LOW = 40;
-const DERIVED_HIGH = 79;
-/** Span of each derived per-voice range in semitones. */
-const DERIVED_SPAN = 19;
-
-/**
- * Resolve the per-voice ranges implied by the options: explicit `ranges` win,
- * four voices use {@link SATB_RANGES}, and other counts get evenly spaced
- * ranges spanning roughly the bass-to-soprano compass.
- */
-export function resolveRanges(opts?: VoicingOptions): VoiceRange[] {
-  if (opts?.ranges !== undefined) {
-    if (opts.ranges.length === 0) {
-      throw new Error('ranges must contain at least one voice range');
-    }
-    assertGenerationBudget(opts.ranges.length, 'voice ranges', 128);
-    return opts.ranges.map((range, index) => {
-      assertFiniteNumber(range.min, `ranges[${index}].min`);
-      assertFiniteNumber(range.max, `ranges[${index}].max`);
-      if (range.min > range.max) {
-        throw new RangeError(`ranges[${index}].min must not exceed max`);
-      }
-      assertGenerationBudget(
-        Math.floor(range.max) - Math.ceil(range.min) + 1,
-        `ranges[${index}] span`,
-        4096,
-      );
-      return { ...range };
-    });
-  }
-  const voices = opts?.voices ?? 4;
-  assertPositiveInt(voices, 'voices', 128);
-  if (voices === 4) {
-    return SATB_RANGES.map((range) => ({ ...range }));
-  }
-  if (voices === 1) {
-    return [{ min: DERIVED_LOW, max: DERIVED_HIGH }];
-  }
-  const ranges: VoiceRange[] = [];
-  for (let i = 0; i < voices; i += 1) {
-    const min = Math.round(
-      DERIVED_LOW + (i * (DERIVED_HIGH - DERIVED_SPAN - DERIVED_LOW)) / (voices - 1),
-    );
-    ranges.push({ min, max: min + DERIVED_SPAN });
-  }
-  return ranges;
-}
-
-/**
- * Realize a single chord as one MIDI pitch per voice, ascending (index 0 =
- * lowest). The bass voice takes the chord's `bassPc` when set, otherwise the
- * root; upper voices take chord pitch classes, doubling the root or fifth as
- * needed to fill all voices. The result stays inside each voice's range, keeps
- * adjacent upper voices within `maxSpacing`, avoids voice crossing, and is
- * deterministic: a compact close-position voicing centered in the ranges.
- *
- * @param chord The chord to voice.
- * @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);
-  const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
-  assertFiniteNumber(maxSpacing, 'maxSpacing');
-  if (maxSpacing < 0) throw new RangeError('maxSpacing must be non-negative');
-  const candidates = enumerateVoicings(chord, ranges, maxSpacing);
-  let best: number[] | undefined;
-  let bestScore = Number.POSITIVE_INFINITY;
-  for (const candidate of candidates) {
-    let score = structuralPenalty(candidate, chord);
-    for (let i = 0; i < candidate.length; i += 1) {
-      const pitch = candidate[i];
-      const range = ranges[i];
-      if (pitch === undefined || range === undefined) {
-        continue;
-      }
-      // Prefer pitches near the middle of each voice's range for a centered,
-      // compact default voicing.
-      score += Math.abs(pitch - (range.min + range.max) / 2);
-    }
-    if (score < bestScore) {
-      bestScore = score;
-      best = candidate;
-    }
-  }
-  if (best === undefined) {
-    throw new Error('no voicing satisfies the given ranges');
-  }
-  return best;
-}
-
-/**
- * Voice a chord progression with smooth voice leading. The first chord is
- * voiced with {@link voiceChord}; each subsequent chord picks, from a bounded
- * deterministic candidate set, the voicing minimizing the voice-leading cost
- * from the previous voicing plus a large penalty per counterpoint violation
- * (parallel perfects/octaves, voice crossing, voice overlap, and over-wide
- * upper-voice spacing).
- *
- * @param chords The chords to voice in order.
- * @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[][] {
-  assertGenerationBudget(chords.length * 4000, 'voiced progression search');
-  const ranges = resolveRanges(opts);
-  const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
-  assertFiniteNumber(maxSpacing, 'maxSpacing');
-  if (maxSpacing < 0) throw new RangeError('maxSpacing must be non-negative');
-  const result: number[][] = [];
-  let prev: number[] | undefined;
-  for (const chord of chords) {
-    if (prev === undefined) {
-      prev = voiceChord(chord, opts);
-      result.push(prev);
-      continue;
-    }
-    const candidates = enumerateVoicings(chord, ranges, maxSpacing);
-    let best: number[] | undefined;
-    let bestScore = Number.POSITIVE_INFINITY;
-    for (const candidate of candidates) {
-      const score =
-        structuralPenalty(candidate, chord) +
-        voiceLeadingCost(prev, candidate) +
-        VIOLATION_PENALTY * violationCount(prev, candidate, maxSpacing);
-      if (score < bestScore) {
-        bestScore = score;
-        best = candidate;
-      }
-    }
-    if (best === undefined) {
-      throw new Error('no voicing satisfies the given ranges');
-    }
-    result.push(best);
-    prev = best;
-  }
-  return result;
-}

package/src/theory/voicing/styled.ts

@@ -1,199 +0,0 @@
-import { assertFiniteNumber, assertInteger } from '../../core/validation/index.js';
-import type { Chord } from '../chord/index.js';
-import { chordToneRole } from '../chord/index.js';
-import { pitchClass } from './internal.js';
-
-/**
- * A tertian voicing style for {@link voiceChordStyled}.
- *
- * - `close`: the plain close-position tertian stack.
- * - `drop2`: the second voice from the top dropped an octave (drop-2 voicing).
- * - `drop3`: the third voice from the top dropped an octave (drop-3 voicing).
- * - `shell`: root plus guide tones (third and seventh) for seventh chords, or
- *   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}.
- *
- * @category Voicing & Counterpoint
- */
-export type StyledVoicingOptions = {
-  /**
-   * 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`.
-   *
-   * @defaultValue 4
-   */
-  octave?: number;
-  /**
-   * Omit the root regardless of style (relevant for jazz voicings).
-   *
-   * @defaultValue false
-   */
-  rootless?: boolean;
-};
-
-/** Default base octave for a styled close-position stack. */
-const DEFAULT_STYLE_OCTAVE = 4;
-
-/** Return the pitch classes of a list in order, without duplicates. */
-function dedupePcs(pcs: number[]): number[] {
-  const seen = new Set<number>();
-  const result: number[] = [];
-  for (const pc of pcs) {
-    if (!seen.has(pc)) {
-      seen.add(pc);
-      result.push(pc);
-    }
-  }
-  return result;
-}
-
-/** The lowest MIDI pitch of a pitch class at or above a floor. */
-function lowestPitchAtOrAbove(pc: number, floor: number): number {
-  return floor + ((((pc - pitchClass(floor)) % 12) + 12) % 12);
-}
-
-/** The pitch class in `pcs` whose circular distance to `target` is smallest. */
-function nearestPc(target: number, pcs: number[]): number {
-  let best = pcs[0] ?? target;
-  let bestDist = 12;
-  for (const pc of pcs) {
-    const dist = Math.min((((pc - target) % 12) + 12) % 12, (((target - pc) % 12) + 12) % 12);
-    if (dist < bestDist) {
-      bestDist = dist;
-      best = pc;
-    }
-  }
-  return best;
-}
-
-/**
- * Realize a single chord as an explicit tertian voicing in a chosen style,
- * independent of the SATB range search used by {@link voiceChord}.
- *
- * The chord tones are stacked in close position from the bass (`bassPc`, else
- * `rootPc`) in the given scientific-pitch `octave` upward (octave 4 starts the
- * bass near C4 = MIDI 60, matching {@link midiToNote} and the bass module).
- * When `topNote` is given the stack is rotated so the highest voice's pitch
- * class equals that note (or the nearest chord tone). The chosen
- * {@link VoicingStyle} then transforms the stack, and the result is returned as
- * ascending MIDI pitches (index 0 = lowest).
- *
- * @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';
-  const octave = opts?.octave ?? DEFAULT_STYLE_OCTAVE;
-  assertInteger(octave, 'styled voicing octave', -10, 10);
-  if (opts?.topNote !== undefined) {
-    assertFiniteNumber(opts.topNote, 'styled voicing topNote');
-  }
-  const base = 12 * (octave + 1);
-  const rootPc = pitchClass(chord.rootPc);
-  const bassPc = pitchClass(chord.bassPc ?? chord.rootPc);
-  const omitRoot = style === 'rootless' || opts?.rootless === true;
-
-  // Tertian chord tones in order, with the bass tone rotated to the bottom.
-  let order = dedupePcs(chord.intervals.map((interval) => pitchClass(chord.rootPc + interval)));
-  const bassIndex = order.indexOf(bassPc);
-  if (bassIndex > 0) {
-    order = [...order.slice(bassIndex), ...order.slice(0, bassIndex)];
-  } else if (bassIndex < 0) {
-    order = [bassPc, ...order];
-  }
-
-  if (style === 'shell') {
-    const roles = order.map((pc) => chordToneRole(pc, chord));
-    // The guide tone is the seventh when present; on a sixth chord the sixth
-    // stands in for it, and otherwise the voicing falls back to the fifth.
-    const guide = roles.includes('seventh')
-      ? 'seventh'
-      : roles.includes('sixth')
-        ? 'sixth'
-        : 'fifth';
-    order = order.filter((_pc, i) => {
-      const role = roles[i];
-      return _pc === bassPc || role === 'root' || role === 'third' || role === guide;
-    });
-  }
-
-  if (omitRoot) {
-    order = order.filter((pc) => pc !== rootPc || (chord.bassPc !== undefined && pc === bassPc));
-  }
-
-  if (order.length === 0) {
-    return [];
-  }
-
-  if (opts?.topNote !== undefined) {
-    const target = order.includes(pitchClass(opts.topNote))
-      ? pitchClass(opts.topNote)
-      : nearestPc(pitchClass(opts.topNote), order);
-    const targetIndex = order.indexOf(target);
-    order = [...order.slice(targetIndex + 1), ...order.slice(0, targetIndex + 1)];
-  }
-
-  // Stack the ordered pitch classes upward in close position.
-  const stack: number[] = [];
-  let prev: number | undefined;
-  for (const pc of order) {
-    if (prev === undefined) {
-      prev = lowestPitchAtOrAbove(pc, base);
-    } else {
-      let delta = (((pc - pitchClass(prev)) % 12) + 12) % 12;
-      if (delta === 0) {
-        delta = 12;
-      }
-      prev += delta;
-    }
-    stack.push(prev);
-  }
-
-  if (style === 'drop2' && stack.length >= 2) {
-    stack[stack.length - 2] = (stack[stack.length - 2] ?? 0) - 12;
-  } else if (style === 'drop3' && stack.length >= 3) {
-    stack[stack.length - 3] = (stack[stack.length - 3] ?? 0) - 12;
-  }
-
-  // An explicit slash bass is a structural requirement, including when it is
-  // not a chord member. Drop voicings and top-note rotation may have moved a
-  // different tone below it, so lower the retained bass by octaves before the
-  // final sort. This gives the bass priority over a conflicting top-note hint.
-  if (chord.bassPc !== undefined) {
-    const bassIndexInStack = stack.findIndex((pitch) => pitchClass(pitch) === bassPc);
-    if (bassIndexInStack >= 0) {
-      const otherLowest = Math.min(
-        ...stack.filter((_pitch, index) => index !== bassIndexInStack),
-        Number.POSITIVE_INFINITY,
-      );
-      while ((stack[bassIndexInStack] ?? 0) >= otherLowest) {
-        stack[bassIndexInStack] = (stack[bassIndexInStack] ?? 0) - 12;
-      }
-    }
-  }
-
-  return stack.sort((a, b) => a - b);
-}

package/tsconfig.json

@@ -1,23 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "lib": ["ES2022"],
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "ignoreDeprecations": "6.0",
-    "verbatimModuleSyntax": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": false,
-    "declaration": true,
-    "sourceMap": true,
-    "outDir": "dist",
-    "rootDir": "src",
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "esModuleInterop": true,
-    "isolatedModules": true
-  },
-  "include": ["src"],
-  "exclude": ["dist", "node_modules"]
-}