@libraz/libcantus 0.9.0

package/src/countermelody/index.ts

@@ -0,0 +1,349 @@
+import type { Chord } from '../chord/index.js';
+import { chordToneRole } from '../chord/index.js';
+import {
+  createsParallelOctave,
+  createsParallelPerfect,
+  isForbiddenMelodicLeap,
+} from '../counterpoint/index.js';
+import type { TimeSignature } from '../meter/index.js';
+import { isStrongBeat } from '../meter/index.js';
+import type { Rng } from '../random/index.js';
+import { createRng } from '../random/index.js';
+import type { VoiceSnapshot } from '../safety/index.js';
+import { enumerateSafePitches } from '../safety/index.js';
+import { nearestScaleTone } from '../scale/index.js';
+import type { KeyScale, NoteEvent } from '../types.js';
+
+/** Options controlling {@link generateCounterMelody}. */
+export type CounterMelodyOptions = {
+  /** The lead line to write against, in ascending onset order. */
+  melody: NoteEvent[];
+  /** Chord sounding at an absolute beat position, or null when none applies. */
+  chordAt: (beat: number) => Chord | null;
+  /** Key/scale context for scale-tone decisions. */
+  key: KeyScale;
+  /** Meter used for strong-beat decisions (default 4/4). */
+  ts?: TimeSignature;
+  /** Which side of the melody the counter line occupies (default `'below'`). */
+  register?: 'above' | 'below';
+  /**
+   * Onset strategy: `'complement'` (default) moves where the melody holds or
+   * rests and reinforces some strong beats; `'follow'` mirrors melody onsets.
+   */
+  rhythm?: 'complement' | 'follow';
+  /** Safety profile applied to candidate pitches (default `'pop'`). */
+  profile?: 'strict' | 'pop';
+  /** Lowest MIDI pitch the counter line may use (default derived from `register`). */
+  pitchLow?: number;
+  /** Highest MIDI pitch the counter line may use (default derived from `register`). */
+  pitchHigh?: number;
+  /** PRNG seed; the same seed always yields the same line (default 0). */
+  seed?: number;
+};
+
+/** Meter assumed when none is supplied. */
+const DEFAULT_TS: TimeSignature = { numerator: 4, denominator: 4 };
+
+/** Tolerance for beat-position comparisons. */
+const EPS = 1e-9;
+
+/** Grid resolution, in quarter-note beats, scanned for complement onsets. */
+const GRID_STEP = 0.5;
+
+/** Minimum spacing between counter onsets, keeping the line uncluttered. */
+const MIN_ONSET_GAP = 1;
+
+/** Semitone offset of the counter register's centre from the melody's mean pitch. */
+const REGISTER_OFFSET = 12;
+
+/** Half-width, in semitones, of the default counter register. */
+const DEFAULT_HALF_RANGE = 10;
+
+/** Probability of moving on a whole beat while the melody sustains. */
+const HOLD_ON_BEAT_PROB = 0.55;
+
+/** Probability of moving on an off-beat subdivision while the melody sustains. */
+const HOLD_OFF_BEAT_PROB = 0.2;
+
+/** Probability of reinforcing a strong beat that the melody also attacks. */
+const REINFORCE_PROB = 0.35;
+
+/** Velocity assumed for melody notes that carry none. */
+const DEFAULT_MELODY_VELOCITY = 96;
+
+/** How far below the concurrent melody velocity the counter line sits. */
+const VELOCITY_DROP = 16;
+
+/** Whether a beat position falls on a whole quarter-note beat. */
+function isWholeBeat(beat: number): boolean {
+  return Math.abs(beat - Math.round(beat)) < EPS;
+}
+
+/** The melody note sounding at a beat (latest onset wins on overlaps). */
+function melodyNoteAt(melody: NoteEvent[], beat: number): NoteEvent | undefined {
+  let found: NoteEvent | undefined;
+  for (const note of melody) {
+    if (note.startBeat - EPS <= beat && beat < note.startBeat + note.durationBeat - EPS) {
+      if (!found || note.startBeat > found.startBeat) {
+        found = note;
+      }
+    }
+  }
+  return found;
+}
+
+/** Whether any melody note attacks exactly at a beat. */
+function melodyAttacksAt(melody: NoteEvent[], beat: number): boolean {
+  return melody.some((note) => Math.abs(note.startBeat - beat) < EPS);
+}
+
+/** Counter onsets mirroring the melody's own onsets, deduplicated and sorted. */
+function followOnsets(melody: NoteEvent[]): number[] {
+  return [...new Set(melody.map((note) => note.startBeat))].sort((a, b) => a - b);
+}
+
+/**
+ * Counter onsets complementing the melody: whole beats inside rests are always
+ * taken, positions where the melody sustains are taken probabilistically, and
+ * strong beats the melody also attacks are occasionally reinforced. A minimum
+ * gap between accepted onsets keeps the line sparse.
+ */
+function complementOnsets(
+  melody: NoteEvent[],
+  ts: TimeSignature,
+  spanStart: number,
+  spanEnd: number,
+  rng: Rng,
+): number[] {
+  const onsets: number[] = [];
+  const gridStart = Math.floor(spanStart / GRID_STEP) * GRID_STEP;
+  let last = Number.NEGATIVE_INFINITY;
+  for (let beat = gridStart; beat < spanEnd - EPS; beat += GRID_STEP) {
+    const attacked = melodyAttacksAt(melody, beat);
+    const sounding = melodyNoteAt(melody, beat) !== undefined;
+    let place = false;
+    if (!attacked && !sounding) {
+      place = isWholeBeat(beat);
+    } else if (!attacked) {
+      place = rng.prob(isWholeBeat(beat) ? HOLD_ON_BEAT_PROB : HOLD_OFF_BEAT_PROB);
+    } else if (isStrongBeat(beat, ts)) {
+      place = rng.prob(REINFORCE_PROB);
+    }
+    if (place && beat - last >= MIN_ONSET_GAP - EPS) {
+      onsets.push(beat);
+      last = beat;
+    }
+  }
+  return onsets;
+}
+
+/**
+ * Preference score for one candidate counter pitch. Rewards imperfect
+ * consonance with the melody, chord-tone membership, contrary or oblique
+ * motion, and stepwise movement; penalizes wide or forbidden leaps, weak-beat
+ * clashes, and drifting from the register centre.
+ */
+function scoreCandidate(
+  pitch: number,
+  melPitch: number | undefined,
+  melPrev: number | undefined,
+  prevPitch: number | undefined,
+  chord: Chord | null,
+  center: number,
+): number {
+  let score = 0;
+  if (melPitch !== undefined) {
+    const ic = Math.abs(pitch - melPitch) % 12;
+    if (ic === 3 || ic === 4 || ic === 8 || ic === 9) {
+      score += 2; // imperfect consonance: thirds and sixths
+    } else if (ic === 0 || ic === 7) {
+      score += 0.5; // perfect consonance: allowed but less colourful
+    } else if (ic === 1 || ic === 2 || ic === 6 || ic === 10 || ic === 11) {
+      score -= 2; // dissonant even on weak beats
+    }
+  }
+  if (chord && chordToneRole(pitch, chord) !== null) {
+    score += 1;
+  }
+  if (prevPitch !== undefined) {
+    const move = pitch - prevPitch;
+    const dist = Math.abs(move);
+    score -= dist * 0.3;
+    if (dist > 0 && dist <= 2) {
+      score += 1; // stepwise motion
+    }
+    if (isForbiddenMelodicLeap(prevPitch, pitch)) {
+      score -= 6;
+    }
+    if (melPitch !== undefined && melPrev !== undefined) {
+      const melMove = melPitch - melPrev;
+      if ((move > 0 && melMove < 0) || (move < 0 && melMove > 0)) {
+        score += 2; // contrary motion
+      } else if (move === 0 || melMove === 0) {
+        score += 1; // oblique motion
+      } else {
+        score -= 1; // similar motion
+      }
+    }
+  }
+  score -= Math.abs(pitch - center) * 0.02;
+  return score;
+}
+
+/**
+ * Last-resort pitch when no safe candidate survives filtering: the scale tone
+ * nearest the previous pitch (or the register centre), pushed onto the correct
+ * side of the sounding melody note.
+ */
+function fallbackPitch(
+  melPitch: number | undefined,
+  prevPitch: number | undefined,
+  center: number,
+  register: 'above' | 'below',
+  low: number,
+  high: number,
+  key: KeyScale,
+): number {
+  let target = prevPitch ?? Math.round(center);
+  if (melPitch !== undefined) {
+    if (register === 'below' && target >= melPitch) {
+      target = melPitch - 5;
+    } else if (register === 'above' && target <= melPitch) {
+      target = melPitch + 5;
+    }
+  }
+  target = Math.min(Math.max(target, low), high);
+  let pitch = nearestScaleTone(target, key);
+  // Push onto the requested side of the melody, but only by whole octaves that
+  // keep the pitch inside [low, high]; the declared range is a hard bound while
+  // the register side is a soft preference. A final clamp guarantees the range.
+  if (melPitch !== undefined) {
+    while (register === 'below' && pitch >= melPitch && pitch - 12 >= low) {
+      pitch -= 12;
+    }
+    while (register === 'above' && pitch <= melPitch && pitch + 12 <= high) {
+      pitch += 12;
+    }
+  }
+  return Math.min(Math.max(pitch, low), high);
+}
+
+/**
+ * Generate a counter melody against a lead line.
+ *
+ * Onsets are chosen per `rhythm`: `'follow'` places one counter note on each
+ * melody onset; `'complement'` fills melody rests and sustains and reinforces
+ * an occasional strong beat, spaced at least a beat apart. Each onset's pitch
+ * is picked from the safe pitches in the counter register (chord tones and
+ * consonant tensions against the sounding melody note), rejecting candidates
+ * that would form a parallel perfect interval with the melody or sit on the
+ * wrong side of it, then scored to favour contrary or oblique motion, imperfect
+ * consonance, and stepwise movement. Ties break toward the lower pitch, so a
+ * given seed always yields the same line. Notes extend to the next counter
+ * onset (the last to the melody's end) at a velocity slightly under the melody.
+ *
+ * @param opts The lead line, chord context callback, key, and generation knobs.
+ * @returns The counter line as note events sorted by onset; `[]` for an empty melody.
+ */
+export function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[] {
+  const melody = [...opts.melody].sort((a, b) => a.startBeat - b.startBeat);
+  if (melody.length === 0) {
+    return [];
+  }
+  const ts = opts.ts ?? DEFAULT_TS;
+  const register = opts.register ?? 'below';
+  const rhythm = opts.rhythm ?? 'complement';
+  const profile = opts.profile ?? 'pop';
+  const rng = createRng(opts.seed ?? 0);
+
+  const spanStart = melody[0]?.startBeat ?? 0;
+  const spanEnd = melody.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), spanStart);
+  const meanPitch = melody.reduce((sum, n) => sum + n.pitch, 0) / melody.length;
+  const defaultCenter =
+    register === 'below' ? meanPitch - REGISTER_OFFSET : meanPitch + REGISTER_OFFSET;
+  const low = opts.pitchLow ?? Math.round(defaultCenter) - DEFAULT_HALF_RANGE;
+  const high = opts.pitchHigh ?? Math.round(defaultCenter) + DEFAULT_HALF_RANGE;
+  const center = (low + high) / 2;
+
+  const onsets =
+    rhythm === 'follow'
+      ? followOnsets(melody)
+      : complementOnsets(melody, ts, spanStart, spanEnd, rng);
+
+  const out: NoteEvent[] = [];
+  let prevPitch: number | undefined;
+  let prevOnset: number | undefined;
+  for (const beat of onsets) {
+    const melNote = melodyNoteAt(melody, beat);
+    const melPitch = melNote?.pitch;
+    const melPrev = prevOnset !== undefined ? melodyNoteAt(melody, prevOnset)?.pitch : undefined;
+    const chord = opts.chordAt(beat);
+    const otherVoices: VoiceSnapshot[] =
+      melPitch !== undefined ? [{ pitch: melPitch, prevPitch: melPrev }] : [];
+
+    const candidates = enumerateSafePitches(
+      {
+        profile,
+        prevPitch,
+        chord,
+        key: opts.key,
+        otherVoices,
+        strongBeat: isStrongBeat(beat, ts),
+        vocalLow: low,
+        vocalHigh: high,
+      },
+      low,
+      high,
+    );
+
+    let bestPitch: number | undefined;
+    let bestScore = Number.NEGATIVE_INFINITY;
+    for (const candidate of candidates) {
+      if (melPitch !== undefined) {
+        if (register === 'below' && candidate >= melPitch) {
+          continue;
+        }
+        if (register === 'above' && candidate <= melPitch) {
+          continue;
+        }
+        if (
+          prevPitch !== undefined &&
+          melPrev !== undefined &&
+          (createsParallelPerfect(prevPitch, candidate, melPrev, melPitch) ||
+            createsParallelOctave(prevPitch, candidate, melPrev, melPitch))
+        ) {
+          continue;
+        }
+      }
+      const score = scoreCandidate(candidate, melPitch, melPrev, prevPitch, chord, center);
+      const tie =
+        Math.abs(score - bestScore) <= EPS && candidate < (bestPitch ?? Number.POSITIVE_INFINITY);
+      if (score > bestScore + EPS || tie) {
+        bestScore = score;
+        bestPitch = candidate;
+      }
+    }
+
+    const pitch =
+      bestPitch ?? fallbackPitch(melPitch, prevPitch, center, register, low, high, opts.key);
+    const velocity = Math.max(
+      1,
+      Math.min(127, Math.round((melNote?.velocity ?? DEFAULT_MELODY_VELOCITY) - VELOCITY_DROP)),
+    );
+    out.push({ pitch, startBeat: beat, durationBeat: GRID_STEP, velocity });
+    prevPitch = pitch;
+    prevOnset = beat;
+  }
+
+  // Extend each note to the next counter onset; the last to the melody's end.
+  for (let i = 0; i < out.length; i += 1) {
+    const note = out[i];
+    if (!note) {
+      continue;
+    }
+    const next = out[i + 1];
+    const end = next ? next.startBeat : Math.max(spanEnd, note.startBeat + GRID_STEP);
+    note.durationBeat = end - note.startBeat;
+  }
+  return out;
+}

package/src/counterpoint/index.ts

@@ -0,0 +1,209 @@
+import { isConsonantInterval } from '../interval/index.js';
+import type { KeyScale } from '../types.js';
+
+/** Reduce a MIDI pitch (or pitch class) to a pitch class in [0, 11]. */
+function pitchClass(pitch: number): number {
+  return ((Math.trunc(pitch) % 12) + 12) % 12;
+}
+
+/**
+ * Whether an upper voice has crossed below a lower voice.
+ *
+ * @param upperPitch Pitch of the nominally higher voice.
+ * @param lowerPitch Pitch of the nominally lower voice.
+ * @returns True when the upper voice sits below the lower voice.
+ */
+export function createsVoiceCrossing(upperPitch: number, lowerPitch: number): boolean {
+  return upperPitch < lowerPitch;
+}
+
+/**
+ * Whether two simultaneous pitches form a dissonance.
+ *
+ * @param a First pitch.
+ * @param b Second pitch.
+ * @param twoVoice When true, the perfect fourth counts as dissonant.
+ * @returns True when the vertical interval is dissonant.
+ */
+export function createsVerticalDissonance(a: number, b: number, twoVoice: boolean): boolean {
+  return !isConsonantInterval(a - b, twoVoice);
+}
+
+/**
+ * Whether a melodic move is a forbidden leap: a tritone, either seventh (minor
+ * or major), or any leap wider than an octave.
+ *
+ * Operates on the raw absolute distance, so compound leaps are not reduced to
+ * their simple class before the octave check.
+ *
+ * @param prev Starting pitch.
+ * @param cur Ending pitch.
+ * @returns True when the leap is forbidden in strict counterpoint.
+ */
+export function isForbiddenMelodicLeap(prev: number, cur: number): boolean {
+  const semis = Math.abs(cur - prev);
+  return semis === 6 || semis === 10 || semis === 11 || semis > 12;
+}
+
+/** Reduce an interval to its simple class in [0, 11]. */
+function simpleClass(semitones: number): number {
+  return Math.abs(semitones) % 12;
+}
+
+/** Whether a simple interval class is a perfect kind (unison/octave or fifth). */
+function isPerfectClass(cls: number): boolean {
+  return cls === 0 || cls === 7;
+}
+
+/** Whether two voices move in the same direction (similar or parallel motion). */
+function similarMotion(aMove: number, bMove: number): boolean {
+  return aMove !== 0 && bMove !== 0 && aMove > 0 === bMove > 0;
+}
+
+/** Whether both voices actually move (neither is stationary — excludes oblique motion). */
+function bothVoicesMove(aMove: number, bMove: number): boolean {
+  return aMove !== 0 && bMove !== 0;
+}
+
+/**
+ * Whether two voices move into consecutive perfect intervals of the same kind
+ * (fifth-to-fifth, octave-to-octave, unison-to-unison).
+ *
+ * Both true parallels (similar motion) and anti-parallels — the same perfect
+ * class reached by contrary motion, e.g. octave to octave with the voices moving
+ * in opposite directions — are flagged, as both are forbidden in strict two-voice
+ * counterpoint. The rule requires that both voices actually move: oblique motion
+ * (either voice stationary) and the no-change case (identical pitches) are excluded.
+ *
+ * A fifth expanding to a twelfth counts (same perfect class); a fifth moving to
+ * an octave does not (different perfect kinds — the direct/hidden case owned by
+ * {@link createsHiddenParallelPerfect}).
+ */
+export function createsParallelPerfect(
+  aPrev: number,
+  aCur: number,
+  bPrev: number,
+  bCur: number,
+): boolean {
+  if (!bothVoicesMove(aCur - aPrev, bCur - bPrev)) {
+    return false;
+  }
+  const nowClass = simpleClass(aCur - bCur);
+  const prevClass = simpleClass(aPrev - bPrev);
+  return isPerfectClass(nowClass) && nowClass === prevClass;
+}
+
+/**
+ * Whether two voices move in consecutive parallel octaves (or unisons) by
+ * similar motion.
+ */
+export function createsParallelOctave(
+  aPrev: number,
+  aCur: number,
+  bPrev: number,
+  bCur: number,
+): boolean {
+  if (!similarMotion(aCur - aPrev, bCur - bPrev)) {
+    return false;
+  }
+  return simpleClass(aCur - bCur) === 0 && simpleClass(aPrev - bPrev) === 0;
+}
+
+/**
+ * Whether two voices move in consecutive parallel unisons — both landing on the
+ * same pitch, having shared a pitch on the previous move.
+ */
+export function createsParallelUnison(
+  aPrev: number,
+  aCur: number,
+  bPrev: number,
+  bCur: number,
+): boolean {
+  if (aCur === aPrev || bCur === bPrev) {
+    return false;
+  }
+  return aCur === bCur && aPrev === bPrev;
+}
+
+/**
+ * Whether two voices reach a perfect interval by similar motion from an
+ * imperfect one (a hidden/direct fifth or octave).
+ *
+ * The traditional step exception is applied: the approach is allowed when the
+ * upper of the two voices moves by step, so only leaps into the perfect
+ * interval are flagged.
+ */
+export function createsHiddenParallelPerfect(
+  aPrev: number,
+  aCur: number,
+  bPrev: number,
+  bCur: number,
+): boolean {
+  const aMove = aCur - aPrev;
+  const bMove = bCur - bPrev;
+  if (!similarMotion(aMove, bMove)) {
+    return false;
+  }
+  const nowClass = simpleClass(aCur - bCur);
+  const prevClass = simpleClass(aPrev - bPrev);
+  // Approaching the same perfect class (e.g. fifth to fifth) is a true parallel
+  // owned by createsParallelPerfect; approaching a different perfect interval
+  // (fifth to octave, or vice versa) is the hidden/direct case flagged here.
+  if (!isPerfectClass(nowClass) || prevClass === nowClass) {
+    return false;
+  }
+  const upperMove = aCur >= bCur ? aMove : bMove;
+  if (Math.abs(upperMove) <= 2) {
+    return false; // upper voice moves by step — direct interval is acceptable
+  }
+  return true;
+}
+
+/**
+ * Whether two voices overlap: the upper voice descends below where the lower
+ * voice just was, or the lower voice rises above where the upper voice just was.
+ * Distinct from a simultaneous voice crossing.
+ *
+ * @param upperPrev Previous pitch of the upper voice.
+ * @param upperCur Current pitch of the upper voice.
+ * @param lowerPrev Previous pitch of the lower voice.
+ * @param lowerCur Current pitch of the lower voice.
+ */
+export function createsVoiceOverlap(
+  upperPrev: number,
+  upperCur: number,
+  lowerPrev: number,
+  lowerCur: number,
+): boolean {
+  return upperCur < lowerPrev || lowerCur > upperPrev;
+}
+
+/**
+ * Whether two adjacent upper voices are spaced more than a maximum apart
+ * (commonly an octave). Bass-to-tenor spacing is conventionally exempt, so this
+ * is meant for the upper voice pairs.
+ *
+ * @param upperPitch Pitch of the higher voice.
+ * @param lowerPitch Pitch of the lower voice.
+ * @param maxSemitones Maximum allowed spacing in semitones (default an octave).
+ */
+export function exceedsSpacing(upperPitch: number, lowerPitch: number, maxSemitones = 12): boolean {
+  return Math.abs(upperPitch - lowerPitch) > maxSemitones;
+}
+
+/**
+ * Whether a leading tone resolves correctly upward to the tonic.
+ *
+ * @param prev The leading-tone pitch.
+ * @param cur The following pitch.
+ * @param key Key context supplying the tonic.
+ * @returns True when `prev` is the leading tone and `cur` is the tonic a step above.
+ */
+export function isLeadingToneResolution(prev: number, cur: number, key: KeyScale): boolean {
+  const tonic = pitchClass(key.rootPc);
+  const leading = (tonic + 11) % 12;
+  if (pitchClass(prev) !== leading || pitchClass(cur) !== tonic) {
+    return false;
+  }
+  return cur > prev && cur - prev <= 2;
+}