@libraz/libcantus 0.9.3 → 0.9.4

package/src/generate/harmonize/index.ts

@@ -1,451 +0,0 @@
-import { isDiatonic, parallelKey } from '../../analyze/functional/index.js';
-import { createNoteEventIndex } from '../../core/event-index/index.js';
-import type { TimeSignature } from '../../core/meter/index.js';
-import { isStrongBeat } from '../../core/meter/index.js';
-import { createRng } from '../../core/random/index.js';
-import type { KeyScale, NoteEvent } from '../../core/types.js';
-import { assertGenerationBudget, assertRange } from '../../core/validation/index.js';
-import type { Chord, ChordQuality } from '../../theory/chord/index.js';
-import { chordPitchClasses, diatonicTriad, makeChord } from '../../theory/chord/index.js';
-import type { HarmonyRole } from '../../theory/harmony/index.js';
-import { roleOf } from '../../theory/harmony/index.js';
-import {
-  isScaleTone,
-  majorKey,
-  minorKey,
-  NATURAL_MINOR_MASK,
-  scaleTonesInDegreeOrder,
-} from '../../theory/scale/index.js';
-import type { ChordSpan } from '../progression/index.js';
-
-/**
- * A melody note supplied to the harmonizer: a {@link NoteEvent}.
- *
- * @category Reharmonization
- */
-export type MelodyNote = NoteEvent;
-
-/**
- * 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.
- *
- * @category Reharmonization
- */
-export type HarmonizeResult = {
-  transposeSemitones: number;
-  key: KeyScale;
-  chords: ChordSpan[];
-  melodyRoles: { noteIndex: number; role: HarmonyRole }[];
-};
-
-type Candidate = {
-  rootPc: number;
-  quality: ChordQuality;
-  degree?: number;
-  secondaryDominant: boolean;
-  targetDegree?: number;
-  base: number;
-};
-
-type Segment = { startBeat: number; endBeat: number; noteIndices: number[] };
-
-const FALLBACK: Candidate = { rootPc: 0, quality: 'maj', secondaryDominant: false, base: 0 };
-
-/** Default meter used to weight metric accents when none is supplied. */
-const DEFAULT_METER: TimeSignature = { numerator: 4, denominator: 4 };
-
-/** Comfortable melodic range (MIDI) and the per-semitone cost of leaving it. */
-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;
-}
-
-/**
- * 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: KeyScale = majorKey(0);
-  let bestScore = Number.NEGATIVE_INFINITY;
-  const candidates: KeyScale[] = [];
-  for (let tonic = 0; tonic < 12; tonic += 1) {
-    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);
-      const pc = pitchClass(n.pitch);
-      if (isScaleTone(n.pitch, key) || (isMinor && pc === leadingTone)) {
-        score += w;
-      }
-      if (pc === tonic) {
-        score += 0.5 * w;
-      }
-    }
-    if (score > bestScore) {
-      bestScore = score;
-      best = key;
-    }
-  }
-  return best;
-}
-
-/** Enumerate candidate chords for the key, gated by reharmonization strength. */
-function buildCandidates(key: KeyScale, reharmonize: HarmonizeOptions['reharmonize']): Candidate[] {
-  const tones = scaleTonesInDegreeOrder(key);
-  const candidates: Candidate[] = tones.map((rootPc, degree) => ({
-    rootPc,
-    quality: diatonicTriad(degree, key).quality,
-    degree,
-    secondaryDominant: false,
-    base: 0,
-  }));
-
-  if (reharmonize !== 'diatonic') {
-    for (const target of [1, 3, 4, 5]) {
-      const targetRoot = tones[target] ?? 0;
-      candidates.push({
-        rootPc: (targetRoot + 7) % 12,
-        quality: 'dom7',
-        secondaryDominant: true,
-        targetDegree: target,
-        base: 1.5,
-      });
-    }
-  }
-
-  if (reharmonize === 'borrowed') {
-    const parallel = parallelKey(key);
-    const parallelTones = scaleTonesInDegreeOrder(parallel);
-    for (let degree = 0; degree < parallelTones.length; degree += 1) {
-      const chord = diatonicTriad(degree, parallel);
-      if (!isDiatonic(chord, key)) {
-        candidates.push({
-          rootPc: chord.rootPc,
-          quality: chord.quality,
-          secondaryDominant: false,
-          base: 1.25,
-        });
-      }
-    }
-  }
-
-  const seen = new Set<string>();
-  return candidates.filter((candidate) => {
-    const id = `${candidate.rootPc}:${candidate.quality}`;
-    if (seen.has(id)) {
-      return false;
-    }
-    seen.add(id);
-    return true;
-  });
-}
-
-/**
- * Melody-fit cost of a candidate over a segment's notes.
- *
- * Each note is weighted by the portion of its duration that overlaps the
- * segment, so a note sustained across a boundary contributes to every segment
- * it sounds in rather than only the one it starts in.
- */
-function emissionCost(seg: Segment, cand: Candidate, melody: MelodyNote[], key: KeyScale): number {
-  const pcs = chordPitchClasses(makeChord(cand.rootPc, cand.quality));
-  let cost = cand.base;
-  for (const idx of seg.noteIndices) {
-    const note = melody[idx];
-    if (!note) {
-      continue;
-    }
-    const overlapStart = Math.max(note.startBeat, seg.startBeat);
-    const overlap = Math.min(note.startBeat + note.durationBeat, seg.endBeat) - overlapStart;
-    if (overlap <= 0) {
-      continue;
-    }
-    const w = Math.max(0.25, overlap);
-    if (pcs.includes(pitchClass(note.pitch))) {
-      continue;
-    }
-    const strong = isStrongBeat(overlapStart, DEFAULT_METER);
-    cost += (strong ? 10 : 2) * w;
-    if (!isScaleTone(note.pitch, key)) {
-      cost += w;
-    }
-  }
-  return cost;
-}
-
-/**
- * Register cost of a placed melody: a small penalty for notes pushed outside a
- * comfortable range. Kept far below emission/transition costs so it only breaks
- * ties between otherwise-equal octave placements.
- */
-function tessituraCost(melody: MelodyNote[]): number {
-  let cost = 0;
-  for (const n of melody) {
-    if (n.pitch < COMFORT_LOW) {
-      cost += (COMFORT_LOW - n.pitch) * TESSITURA_WEIGHT;
-    } else if (n.pitch > COMFORT_HIGH) {
-      cost += (n.pitch - COMFORT_HIGH) * TESSITURA_WEIGHT;
-    }
-  }
-  return cost;
-}
-
-/** Functional-flow cost of moving from one candidate chord to the next. */
-function transitionCost(prev: Candidate, cur: Candidate, tonicPc: number): number {
-  let cost = 0;
-  if ((prev.rootPc - cur.rootPc + 12) % 12 === 7) {
-    cost -= 2; // descending-fifth root motion
-  }
-  if (
-    prev.rootPc === (tonicPc + 7) % 12 &&
-    (prev.quality === 'maj' || prev.quality === 'dom7') &&
-    cur.rootPc === tonicPc
-  ) {
-    cost -= 3; // V -> I
-  }
-  if (prev.secondaryDominant) {
-    cost += cur.degree === prev.targetDegree ? -3 : 2;
-  }
-  const dist = Math.min((prev.rootPc - cur.rootPc + 12) % 12, (cur.rootPc - prev.rootPc + 12) % 12);
-  cost += dist * 0.3;
-  return cost;
-}
-
-/** Run one Viterbi harmonization pass over a fixed melody and key. */
-function harmonizeOnce(
-  melody: MelodyNote[],
-  key: KeyScale,
-  candidates: Candidate[],
-  segments: Segment[],
-  jitter: number[],
-): { cost: number; path: number[] } {
-  const tonicPc = pitchClass(key.rootPc);
-  const n = candidates.length;
-  const candAt = (i: number): Candidate => candidates[i] ?? FALLBACK;
-  const seg0 = segments[0];
-
-  let dp = candidates.map(
-    (c, ci) => (seg0 ? emissionCost(seg0, c, melody, key) : 0) + (jitter[ci] ?? 0),
-  );
-  const back: number[][] = [];
-
-  for (let s = 1; s < segments.length; s += 1) {
-    const seg = segments[s];
-    if (!seg) {
-      continue;
-    }
-    const next: number[] = [];
-    const ptr: number[] = [];
-    for (let c = 0; c < n; c += 1) {
-      let best = Number.POSITIVE_INFINITY;
-      let bestPrev = 0;
-      for (let p = 0; p < n; p += 1) {
-        const cost =
-          (dp[p] ?? Number.POSITIVE_INFINITY) + transitionCost(candAt(p), candAt(c), tonicPc);
-        if (cost < best) {
-          best = cost;
-          bestPrev = p;
-        }
-      }
-      next[c] = best + emissionCost(seg, candAt(c), melody, key) + (jitter[c] ?? 0);
-      ptr[c] = bestPrev;
-    }
-    dp = next;
-    back.push(ptr);
-  }
-
-  let bestCost = Number.POSITIVE_INFINITY;
-  let bestEnd = 0;
-  for (let c = 0; c < n; c += 1) {
-    const cadence = candAt(c).rootPc === tonicPc ? -2 : 0;
-    const total = (dp[c] ?? Number.POSITIVE_INFINITY) + cadence;
-    if (total < bestCost) {
-      bestCost = total;
-      bestEnd = c;
-    }
-  }
-
-  const path: number[] = new Array<number>(segments.length).fill(bestEnd);
-  for (let s = segments.length - 2; s >= 0; s -= 1) {
-    const ptr = back[s];
-    const nextIdx = path[s + 1] ?? bestEnd;
-    path[s] = ptr ? (ptr[nextIdx] ?? bestEnd) : bestEnd;
-  }
-  return { cost: bestCost, path };
-}
-
-/**
- * Harmonize a melody with a min-cost chord progression.
- *
- * The melody is segmented by `harmonicRhythm`; each segment is scored against
- * diatonic (and, per `reharmonize`, secondary-dominant and borrowed) candidate
- * chords by melody fit, and a Viterbi search picks the lowest-cost path using a
- * functional-flow transition cost. When `placement.transposeSearch`/`octaveSearch`
- * is set, the whole melody is transposed across a range and the best
- * `(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 ChordSpan per harmonic-rhythm segment
- * ```
- * @category Reharmonization
- */
-export function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult {
-  const noteIndex = createNoteEventIndex(opts.melody);
-  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 = createRng(opts.seed ?? 0);
-  const jitter = candidates.map(() => rng.next() * TIE_BREAK_JITTER);
-
-  const melodyEnd = noteIndex.notes.reduce((m, n) => Math.max(m, n.endBeat), 0);
-  const requestedHr = assertRange(
-    opts.harmonicRhythm,
-    Number.MIN_VALUE,
-    Number.MAX_SAFE_INTEGER,
-    'harmonic rhythm',
-  );
-  const hr = Math.max(0.25, requestedHr);
-  const segCount = Math.max(1, Math.ceil(melodyEnd / hr));
-  assertGenerationBudget(segCount, 'harmonic segments');
-  assertGenerationBudget(segCount * candidates.length * candidates.length, 'harmonization search');
-  const segments: Segment[] = Array.from({ length: segCount }, (_, s) => ({
-    startBeat: s * hr,
-    endBeat: (s + 1) * hr,
-    noteIndices: [],
-  }));
-  // Associate each note only with the windows it actually spans. This replaces
-  // the former per-window full melody scan and creates no temporary note objects.
-  let memberships = 0;
-  for (const indexed of noteIndex.notes) {
-    const first = Math.max(0, Math.floor(indexed.note.startBeat / hr));
-    const lastExclusive = Math.min(segCount, Math.ceil(indexed.endBeat / hr - Number.EPSILON));
-    memberships += Math.max(0, lastExclusive - first);
-    assertGenerationBudget(memberships, 'note-to-segment memberships');
-    for (let segment = first; segment < lastExclusive; segment += 1) {
-      segments[segment]?.noteIndices.push(indexed.originalIndex);
-    }
-  }
-
-  const transposes: number[] = [0];
-  if (opts.placement.transposeSearch) {
-    for (let s = -6; s <= 6; s += 1) {
-      if (s !== 0) {
-        transposes.push(s);
-      }
-    }
-  }
-  if (opts.placement.octaveSearch) {
-    for (const o of [-12, 12]) {
-      if (!transposes.includes(o)) {
-        transposes.push(o);
-      }
-    }
-  }
-
-  let bestCost = Number.POSITIVE_INFINITY;
-  let bestTs = 0;
-  let bestPath: number[] = [];
-  let bestMelody = opts.melody;
-  for (const ts of transposes) {
-    const shifted = opts.melody.map((n) => ({ ...n, pitch: n.pitch + ts }));
-    const { cost, path } = harmonizeOnce(shifted, key, candidates, segments, jitter);
-    const total = cost + tessituraCost(shifted);
-    if (total < bestCost) {
-      bestCost = total;
-      bestTs = ts;
-      bestPath = path;
-      bestMelody = shifted;
-    }
-  }
-
-  const chords: ChordSpan[] = bestPath.map((ci, s) => {
-    const cand = candAt(ci);
-    const chord: ChordSpan = {
-      rootPc: cand.rootPc,
-      quality: cand.quality,
-      startBeat: segments[s]?.startBeat ?? s * hr,
-    };
-    if (cand.degree !== undefined) {
-      chord.degree = cand.degree;
-    }
-    if (cand.secondaryDominant) {
-      chord.secondaryDominant = true;
-    }
-    return chord;
-  });
-
-  const melodyRoles = bestMelody.map((note, noteIndex) => {
-    const segIdx = Math.min(segments.length - 1, Math.max(0, Math.floor(note.startBeat / hr)));
-    const cand = candAt(bestPath[segIdx] ?? 0);
-    const chord: Chord = makeChord(cand.rootPc, cand.quality);
-    return { noteIndex, role: roleOf(note.pitch, chord).role };
-  });
-
-  return { transposeSemitones: bestTs, key, chords, melodyRoles };
-}

package/src/generate/index.ts

@@ -1,58 +0,0 @@
-/**
- * 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 {
-  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';