@libraz/libcantus 0.9.0

package/src/detect/index.ts

@@ -0,0 +1,176 @@
+/**
+ * Recognition: infer a chord name from a set of pitches, or a key from a set of
+ * pitch classes. This is the inverse direction of the chord/scale builders,
+ * which only go name -> notes.
+ */
+
+import type { Chord, ChordQuality } from '../chord/index.js';
+import { chordPitchClasses, chordQualities, makeChord } from '../chord/index.js';
+import { majorKey, minorKey } from '../scale/index.js';
+import type { KeyScale } from '../types.js';
+
+/** A candidate chord interpretation of a pitch set. */
+export type ChordMatch = {
+  rootPc: number;
+  quality: ChordQuality;
+  /** Chord tones absent from the input (an incomplete voicing). */
+  missingPcs: number[];
+  /** Input pitch classes not belonging to the chord. */
+  extraPcs: number[];
+  /** True when the input pitch-class set equals the chord exactly. */
+  exact: boolean;
+  /** Inversion implied by the lowest note: 0 root position, 1 first, ... */
+  inversion: number;
+  /** Bass pitch class when inverted (the lowest note is not the root). */
+  bassPc?: number;
+};
+
+/** A candidate key interpretation of a pitch-class set. */
+export type KeyMatch = {
+  key: KeyScale;
+  mode: 'major' | 'minor';
+  /** Fraction of input pitch classes that are in the scale, in [0, 1]. */
+  fit: number;
+};
+
+/** Reduce any integer to a pitch class in [0, 11]. */
+function pitchClass(value: number): number {
+  return ((Math.trunc(value) % 12) + 12) % 12;
+}
+
+/** Unique pitch classes of the input, sorted ascending. */
+function uniquePitchClasses(pitches: number[]): number[] {
+  return [...new Set(pitches.map(pitchClass))].sort((a, b) => a - b);
+}
+
+/**
+ * Identify chords matching a set of pitches.
+ *
+ * Every input pitch class is tried as a root against every known chord quality.
+ * A match is reported when all of the chord's tones are present in the input, or
+ * when the only absent tone is the perfect fifth (a common omission in shell
+ * voicings); matches are ranked best-first by fewest extra notes, then fewest
+ * missing notes, then most specific (largest) chord. An exact match (no extras,
+ * no missing) is flagged and ranked first.
+ *
+ * @param pitches MIDI pitches or bare pitch classes (octave-agnostic).
+ * @returns Ranked chord interpretations (may be empty).
+ */
+export function detectChord(pitches: number[]): ChordMatch[] {
+  const input = uniquePitchClasses(pitches);
+  if (input.length === 0) {
+    return [];
+  }
+  const bassPc = pitchClass(Math.min(...pitches));
+  const inputSet = new Set(input);
+  const matches: ChordMatch[] = [];
+  const qualities = chordQualities();
+  for (const rootPc of input) {
+    for (const quality of qualities) {
+      const chord = makeChord(rootPc, quality);
+      const tones = chordPitchClasses(chord);
+      const toneSet = new Set(tones);
+      const missingPcs = tones.filter((pc) => !inputSet.has(pc));
+      // Accept an exact-tone match, or one whose only absent tone is the perfect
+      // fifth; any other missing tone (third, sus tone, seventh, ...) rejects.
+      const fifthPc = pitchClass(rootPc + 7);
+      if (missingPcs.length > 1 || (missingPcs.length === 1 && missingPcs[0] !== fifthPc)) {
+        continue;
+      }
+      const extraPcs = input.filter((pc) => !toneSet.has(pc));
+      const bassIndex = chord.intervals.findIndex((iv) => pitchClass(rootPc + iv) === bassPc);
+      const inversion = bassIndex > 0 ? bassIndex : 0;
+      const match: ChordMatch = {
+        rootPc,
+        quality,
+        missingPcs,
+        extraPcs,
+        exact: extraPcs.length === 0,
+        inversion,
+      };
+      if (inversion > 0) {
+        match.bassPc = bassPc;
+      }
+      matches.push(match);
+    }
+  }
+  matches.sort((a, b) => {
+    if (a.extraPcs.length !== b.extraPcs.length) {
+      return a.extraPcs.length - b.extraPcs.length;
+    }
+    if (a.missingPcs.length !== b.missingPcs.length) {
+      return a.missingPcs.length - b.missingPcs.length;
+    }
+    // Prefer root position (the bass is the chord root) on a tie.
+    if ((a.inversion === 0) !== (b.inversion === 0)) {
+      return a.inversion === 0 ? -1 : 1;
+    }
+    const aSize = chordPitchClasses(makeChord(a.rootPc, a.quality)).length;
+    const bSize = chordPitchClasses(makeChord(b.rootPc, b.quality)).length;
+    return bSize - aSize;
+  });
+  return matches;
+}
+
+/**
+ * The single best chord interpretation of a pitch set, or null if none.
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @returns The top-ranked chord, or null when nothing matches.
+ */
+export function detectChordBest(pitches: number[]): Chord | null {
+  const best = detectChord(pitches)[0];
+  if (!best) {
+    return null;
+  }
+  return makeChord(best.rootPc, best.quality, best.bassPc);
+}
+
+/**
+ * Rank major and minor keys by how well they contain a set of pitch classes.
+ *
+ * The tonic is weighted so that, among equally-fitting keys, the one whose root
+ * appears in the input is preferred. Returns all 24 keys ranked best-first.
+ *
+ * @param pitches MIDI pitches or bare pitch classes.
+ * @returns Ranked key interpretations.
+ */
+export function detectKey(pitches: number[]): KeyMatch[] {
+  const input = uniquePitchClasses(pitches);
+  const counts = new Map<number, number>();
+  for (const pc of pitches.map(pitchClass)) {
+    counts.set(pc, (counts.get(pc) ?? 0) + 1);
+  }
+  const total = pitches.length || 1;
+  const results: (KeyMatch & { score: number })[] = [];
+  for (let tonic = 0; tonic < 12; tonic += 1) {
+    for (const mode of ['major', 'minor'] as const) {
+      const key = mode === 'major' ? majorKey(tonic) : minorKey(tonic);
+      let inScale = 0;
+      let weighted = 0;
+      for (const pc of input) {
+        const offset = (pc - tonic + 12) % 12;
+        if ((key.modeMask12 >> offset) & 1) {
+          inScale += 1;
+        }
+      }
+      for (const [pc, count] of counts) {
+        const offset = (pc - tonic + 12) % 12;
+        if ((key.modeMask12 >> offset) & 1) {
+          weighted += count;
+        }
+        if (pc === tonic) {
+          weighted += count * 0.5;
+        }
+      }
+      results.push({
+        key,
+        mode,
+        fit: input.length === 0 ? 0 : inScale / input.length,
+        score: weighted / total,
+      });
+    }
+  }
+  results.sort((a, b) => b.score - a.score);
+  return results.map(({ key, mode, fit }) => ({ key, mode, fit }));
+}

package/src/drums/beat.ts

@@ -0,0 +1,266 @@
+import {
+  getGhostDensity,
+  getGhostProbabilityAtPosition,
+  getGhostVelocity,
+  selectGhostPositions,
+} from './ghost.js';
+import {
+  footHiHatVelocity,
+  type HiHatLevel,
+  hiHatNote,
+  hiHatTypeVelocityMultiplier,
+  hiHatVelocityMultiplier,
+  OHH_VEL_BOOST,
+  roleHiHatInstrument,
+  sectionHiHatType,
+  shouldAddOpenHHAccent,
+  shouldPlayHiHat,
+  shouldUseBridgeCrossStick,
+} from './hihat.js';
+import type { HitList } from './hit.js';
+import type { BackingDensity, DrumRole, DrumStyle, Feel, SectionType } from './internal.js';
+import { EIGHTH, GM, type MoodCategory, SIXTEENTH } from './internal.js';
+import type { KickPattern } from './kick.js';
+import type { DrumRng } from './rng.js';
+import { effectiveSwing, quantizeSwing } from './swing.js';
+
+/** Per-section drum state shared across the bars of a section. */
+export type SectionCtx = {
+  style: DrumStyle;
+  feel: Feel;
+  densityMult: number;
+  backingDensity: BackingDensity;
+  hhLevel: HiHatLevel;
+  useGhostNotes: boolean;
+  ghostBoost: boolean;
+  useRide: boolean;
+  useFootHh: boolean;
+  role: DrumRole;
+  ghostMood: MoodCategory;
+  snareBeat3: boolean;
+};
+
+/** Per-beat context passed to every beat processor. */
+export type BeatCtx = {
+  track: HitList;
+  beatTick: number;
+  beat: number;
+  velocity: number;
+  section: SectionType;
+  bpm: number;
+  bar: number;
+  sectionBars: number;
+  inPrechorusLift: boolean;
+  swingAmount: number;
+  barHasOpenHh: boolean;
+  openHhBeat: number;
+  rng: DrumRng;
+};
+
+function swing16(tick: number, feel: Feel, swingAmount: number): number {
+  return quantizeSwing(tick, effectiveSwing(feel, swingAmount), 'sixteenth');
+}
+
+function hatSwingFactor(style: DrumStyle): number {
+  if (style === 'trap') {
+    return 0;
+  }
+  if (style === 'latin') {
+    return 0.35;
+  }
+  return 0.5;
+}
+
+/** Emit the kick for one beat. */
+export function generateKickForBeat(ctx: BeatCtx, sec: SectionCtx, kick: KickPattern): void {
+  if (ctx.inPrechorusLift) {
+    return;
+  }
+  const on = [kick.beat1, kick.beat2, kick.beat3, kick.beat4][ctx.beat] ?? false;
+  const and = [kick.beat1and, kick.beat2and, kick.beat3and, kick.beat4and][ctx.beat] ?? false;
+
+  if (on) {
+    ctx.track.add(GM.BD, ctx.beatTick, EIGHTH, ctx.velocity);
+  }
+  if (and) {
+    const andTick = swing16(ctx.beatTick + EIGHTH, sec.feel, ctx.swingAmount);
+    ctx.track.add(GM.BD, andTick, EIGHTH, ctx.velocity * 0.85);
+  }
+}
+
+/** Emit the backbeat snare (or side-stick) for one beat. */
+export function generateSnareForBeat(ctx: BeatCtx, sec: SectionCtx, isIntroFirst: boolean): void {
+  if (ctx.inPrechorusLift) {
+    return;
+  }
+  const snareOn = sec.snareBeat3 ? ctx.beat === 2 : ctx.beat === 1 || ctx.beat === 3;
+  if (!snareOn || isIntroFirst) {
+    return;
+  }
+  if (sec.useRide && shouldUseBridgeCrossStick(ctx.section, ctx.beat)) {
+    return;
+  }
+
+  const backbeatVel = Math.min(127, ctx.velocity + 16);
+  const promoteSparseChorus =
+    sec.style === 'sparse' && ctx.section === 'chorus' && sec.role === 'full';
+
+  if (promoteSparseChorus) {
+    ctx.track.add(GM.SD, ctx.beatTick, EIGHTH, backbeatVel);
+  } else if (sec.style === 'sparse' || sec.role === 'ambient') {
+    if (sec.role !== 'fxOnly' && sec.role !== 'minimal') {
+      ctx.track.add(GM.SIDESTICK, ctx.beatTick, EIGHTH, ctx.velocity * 0.8);
+    }
+  } else {
+    ctx.track.add(GM.SD, ctx.beatTick, EIGHTH, backbeatVel);
+  }
+}
+
+/** Emit ghost snares at the "e"/"a" 16ths of beats 1 and 3. */
+export function generateGhostNotesForBeat(ctx: BeatCtx, sec: SectionCtx): void {
+  if (ctx.beat !== 0 && ctx.beat !== 2) {
+    return;
+  }
+  const positions = selectGhostPositions(sec.ghostMood, ctx.rng);
+  let ghostProb = getGhostDensity(sec.ghostMood, ctx.section, sec.backingDensity, ctx.bpm);
+  if (sec.ghostBoost) {
+    ghostProb = Math.min(1, ghostProb * 1.4);
+  }
+
+  for (const pos of positions) {
+    const sixteenthInBeat = pos === 'e' ? 1 : 3;
+    const posProb = getGhostProbabilityAtPosition(ctx.beat, sixteenthInBeat);
+    if (!ctx.rng.prob(ghostProb * posProb)) {
+      continue;
+    }
+    const variation = ctx.rng.float(0.85, 1.15);
+    const ghostBase = getGhostVelocity(ctx.section, ctx.beat / 2, false);
+    let ghostVel = ctx.velocity * ghostBase * variation;
+    if (pos === 'a') {
+      ghostVel *= 0.9;
+    }
+    const offset = pos === 'e' ? SIXTEENTH : 3 * SIXTEENTH;
+    const tick = swing16(ctx.beatTick + offset, sec.feel, ctx.swingAmount);
+    ctx.track.add(GM.SD, tick, SIXTEENTH, ghostVel);
+  }
+}
+
+/** Emit the pre-chorus lift buildup for one beat. */
+export function generatePreChorusBuildup(
+  ctx: BeatCtx,
+  sec: SectionCtx,
+  isSectionLastBar: boolean,
+): void {
+  if (sec.style === 'sparse') {
+    if (isSectionLastBar && ctx.beat === 3) {
+      ctx.track.add(GM.SD, ctx.beatTick, EIGHTH, Math.max(45, ctx.velocity * 0.75));
+      ctx.track.add(GM.CRASH, ctx.beatTick + EIGHTH + SIXTEENTH, SIXTEENTH, ctx.velocity * 0.9);
+    }
+    return;
+  }
+  const barsInLift = 2;
+  const barInLift = ctx.bar - (ctx.sectionBars - barsInLift);
+  const progress = (barInLift * 4 + ctx.beat) / (barsInLift * 4);
+  const buildupVel = ctx.velocity * (0.5 + 0.5 * progress);
+  ctx.track.add(GM.SD, ctx.beatTick, EIGHTH, buildupVel);
+  ctx.track.add(GM.SD, ctx.beatTick + EIGHTH, EIGHTH, buildupVel * 0.85);
+  if (isSectionLastBar && ctx.beat === 3) {
+    ctx.track.add(GM.CRASH, ctx.beatTick + EIGHTH + SIXTEENTH, SIXTEENTH, ctx.velocity * 1.1);
+  }
+}
+
+/** Emit the timekeeping hi-hat (or ride/foot) for one beat. */
+export function generateHiHatForBeat(ctx: BeatCtx, sec: SectionCtx): void {
+  if (!shouldPlayHiHat(sec.role)) {
+    if (sec.useFootHh && (ctx.beat === 0 || ctx.beat === 2)) {
+      ctx.track.add(GM.FHH, ctx.beatTick, EIGHTH, footHiHatVelocity(ctx.rng));
+    }
+    return;
+  }
+
+  const crossStick = sec.useRide && shouldUseBridgeCrossStick(ctx.section, ctx.beat);
+  const hhInstrument = crossStick ? GM.SIDESTICK : roleHiHatInstrument(sec.role, sec.useRide);
+  const hhType = sectionHiHatType(ctx.section, sec.role);
+  const typeMult = hiHatTypeVelocityMultiplier(hhType);
+  const isDynamicOpen = ctx.barHasOpenHh && ctx.beat === ctx.openHhBeat;
+  const dm = sec.densityMult;
+
+  if (sec.hhLevel === 'quarter') {
+    const introRest = ctx.section === 'intro' && ctx.beat !== 0;
+    if (!introRest) {
+      if (isDynamicOpen) {
+        ctx.track.add(
+          GM.OHH,
+          ctx.beatTick,
+          EIGHTH,
+          ctx.velocity * dm * 0.75 * typeMult + OHH_VEL_BOOST,
+        );
+      } else {
+        ctx.track.add(
+          hhInstrument,
+          ctx.beatTick,
+          EIGHTH,
+          Math.max(20, ctx.velocity * dm * 0.75 * typeMult),
+        );
+      }
+    } else if (sec.useFootHh) {
+      ctx.track.add(GM.FHH, ctx.beatTick, EIGHTH, footHiHatVelocity(ctx.rng));
+    }
+    return;
+  }
+
+  if (sec.hhLevel === 'eighth') {
+    for (let eighth = 0; eighth < 2; eighth += 1) {
+      let hhTick = ctx.beatTick + eighth * EIGHTH;
+      if (eighth === 1) {
+        hhTick = swing16(hhTick, sec.feel, ctx.swingAmount);
+      }
+      if (ctx.section === 'intro' && eighth === 1) {
+        if (sec.useFootHh && ctx.beat % 2 === 0) {
+          ctx.track.add(GM.FHH, hhTick, EIGHTH, footHiHatVelocity(ctx.rng));
+        }
+        continue;
+      }
+      const hhVel = Math.max(20, ctx.velocity * dm * typeMult * (eighth === 0 ? 0.9 : 0.65));
+      if (isDynamicOpen && eighth === 0) {
+        ctx.track.add(GM.OHH, hhTick, EIGHTH, hhVel + OHH_VEL_BOOST);
+        continue;
+      }
+      let useOpen = false;
+      if (sec.style === 'fourOnFloor' && eighth === 1) {
+        const openProb = Math.max(0.15, Math.min(0.8, 45 / ctx.bpm));
+        useOpen = (ctx.beat === 1 || ctx.beat === 3) && ctx.rng.prob(openProb);
+      } else if (eighth === 0) {
+        useOpen = shouldAddOpenHHAccent(ctx.section, ctx.beat, ctx.bar, ctx.rng);
+      }
+      if (useOpen) {
+        ctx.track.add(hiHatNote('open'), hhTick, EIGHTH, Math.max(20, hhVel * 1.1));
+      } else {
+        ctx.track.add(hhInstrument, hhTick, EIGHTH / 2, hhVel);
+      }
+    }
+    return;
+  }
+
+  for (let sixteenth = 0; sixteenth < 4; sixteenth += 1) {
+    let hhTick = ctx.beatTick + sixteenth * SIXTEENTH;
+    if (sixteenth === 1 || sixteenth === 3) {
+      const swung = effectiveSwing(sec.feel, ctx.swingAmount) * hatSwingFactor(sec.style);
+      hhTick = quantizeSwing(hhTick, swung, 'sixteenth');
+    }
+    const metricVel = hiHatVelocityMultiplier(sixteenth, ctx.rng);
+    const hhVel = Math.max(20, ctx.velocity * dm * typeMult * metricVel);
+    if (isDynamicOpen && sixteenth === 0) {
+      ctx.track.add(GM.OHH, hhTick, SIXTEENTH, hhVel + OHH_VEL_BOOST);
+      continue;
+    }
+    if (ctx.beat === 3 && sixteenth === 3) {
+      const openProb = Math.max(0.1, Math.min(0.4, 30 / ctx.bpm));
+      if (ctx.rng.prob(openProb)) {
+        ctx.track.add(GM.OHH, hhTick, SIXTEENTH, Math.max(20, hhVel * 1.2));
+        continue;
+      }
+    }
+    ctx.track.add(hhInstrument, hhTick, SIXTEENTH / 2, hhVel);
+  }
+}

package/src/drums/euclid.ts

@@ -0,0 +1,58 @@
+/**
+ * Generate a euclidean onset pattern (Bjorklund's algorithm), distributing
+ * `pulses` as evenly as possible across `steps`, then rotating.
+ *
+ * @param pulses Number of onsets, clamped to [0, steps].
+ * @param steps Total steps (>= 1).
+ * @param rotation Steps to rotate onsets toward later positions.
+ * @returns One boolean per step; true marks an onset.
+ */
+export function euclideanRhythm(pulses: number, steps: number, rotation = 0): boolean[] {
+  if (steps < 1) {
+    return [];
+  }
+  const p = Math.max(0, Math.min(pulses, steps));
+  const base = bjorklund(p, steps);
+  const shift = ((rotation % steps) + steps) % steps;
+  if (shift === 0) {
+    return base;
+  }
+  return base.map((_, i) => base[(i - shift + steps) % steps] ?? false);
+}
+
+/** True when the 16-step bitmask has an onset at `step`. */
+export function hasHit(mask: number, step: number): boolean {
+  return ((mask >> step) & 1) === 1;
+}
+
+/** Convert a euclidean boolean pattern to a 16-step bitmask (LSB = step 0). */
+export function patternToMask(pattern: boolean[]): number {
+  let mask = 0;
+  for (let i = 0; i < pattern.length; i += 1) {
+    if (pattern[i]) {
+      mask |= 1 << i;
+    }
+  }
+  return mask;
+}
+
+function bjorklund(pulses: number, steps: number): boolean[] {
+  if (pulses === 0) {
+    return Array.from({ length: steps }, () => false);
+  }
+  if (pulses >= steps) {
+    return Array.from({ length: steps }, () => true);
+  }
+  let head: boolean[][] = Array.from({ length: pulses }, () => [true]);
+  let remainder: boolean[][] = Array.from({ length: steps - pulses }, () => [false]);
+  while (remainder.length > 1) {
+    const count = Math.min(head.length, remainder.length);
+    const next: boolean[][] = [];
+    for (let i = 0; i < count; i += 1) {
+      next.push([...(head[i] ?? []), ...(remainder[i] ?? [])]);
+    }
+    remainder = head.length > count ? head.slice(count) : remainder.slice(count);
+    head = next;
+  }
+  return [...head.flat(), ...remainder.flat()];
+}