@libraz/libcantus 0.9.0

package/src/drums/hihat.ts

@@ -0,0 +1,285 @@
+import type { DrumRole, DrumStyle, SectionType } from './internal.js';
+import { GM } from './internal.js';
+import type { DrumRng } from './rng.js';
+
+/** Hi-hat subdivision level. */
+export type HiHatLevel = 'quarter' | 'eighth' | 'sixteenth';
+
+/** Hi-hat articulation type. */
+export type HiHatType = 'closed' | 'pedal' | 'open' | 'halfOpen' | 'ride';
+
+/** BPM at or above which 16th-note hi-hats become 8ths for playability. */
+export const HH_16TH_BPM_THRESHOLD = 150;
+
+const FHH_VEL_MIN = 45;
+const FHH_VEL_MAX = 60;
+/** Velocity boost applied to dynamic open hi-hat accents. */
+export const OHH_VEL_BOOST = 7;
+
+/** True unless the role suppresses timekeeping cymbals entirely. */
+export function shouldPlayHiHat(role: DrumRole): boolean {
+  return role !== 'fxOnly';
+}
+
+/** Preferred timekeeping instrument for a role. */
+export function roleHiHatInstrument(role: DrumRole, useRide: boolean): number {
+  if (role === 'ambient') {
+    return GM.RIDE;
+  }
+  return useRide ? GM.RIDE : GM.CHH;
+}
+
+function sparser(level: HiHatLevel): HiHatLevel {
+  if (level === 'sixteenth') {
+    return 'eighth';
+  }
+  if (level === 'eighth') {
+    return 'quarter';
+  }
+  return 'quarter';
+}
+
+function denser(level: HiHatLevel): HiHatLevel {
+  if (level === 'quarter') {
+    return 'eighth';
+  }
+  if (level === 'eighth') {
+    return 'sixteenth';
+  }
+  return 'sixteenth';
+}
+
+/** Choose the hi-hat subdivision for a section/style/density/BPM. */
+export function getHiHatLevel(
+  section: SectionType,
+  style: DrumStyle,
+  backingDensity: 'thin' | 'normal' | 'thick',
+  bpm: number,
+  rng: DrumRng,
+): HiHatLevel {
+  const allow16th = bpm < HH_16TH_BPM_THRESHOLD;
+  let base: HiHatLevel = 'eighth';
+
+  if (style === 'sparse') {
+    base = section === 'chorus' ? 'eighth' : 'quarter';
+  } else if (style === 'fourOnFloor') {
+    if (allow16th && section === 'chorus' && rng.prob(0.25)) {
+      return 'sixteenth';
+    }
+    return 'eighth';
+  } else if (style === 'synth') {
+    if (!allow16th) {
+      return 'eighth';
+    }
+    if (section === 'a' && rng.prob(0.2)) {
+      return 'eighth';
+    }
+    return 'sixteenth';
+  } else if (style === 'trap') {
+    return allow16th ? 'sixteenth' : 'eighth';
+  } else if (style === 'latin') {
+    if (allow16th && section === 'chorus' && rng.prob(0.3)) {
+      return 'sixteenth';
+    }
+    return 'eighth';
+  } else {
+    switch (section) {
+      case 'intro':
+        base = 'quarter';
+        break;
+      case 'outro':
+        base = 'eighth';
+        break;
+      case 'a':
+        base = rng.prob(0.3) ? 'quarter' : 'eighth';
+        break;
+      case 'b':
+        base = allow16th && rng.prob(0.25) ? 'sixteenth' : 'eighth';
+        break;
+      case 'chorus':
+        base = allow16th && rng.prob(0.35) ? 'sixteenth' : 'eighth';
+        break;
+      case 'bridge':
+        base = 'eighth';
+        break;
+    }
+  }
+
+  if (backingDensity === 'thin') {
+    base = sparser(base);
+  } else if (backingDensity === 'thick') {
+    base = denser(base);
+  }
+
+  if (!allow16th && base === 'sixteenth') {
+    base = 'eighth';
+  }
+  return base;
+}
+
+/** Metric velocity multiplier for a 16th position within a beat. */
+export function hiHatVelocityMultiplier(sixteenth: number, rng: DrumRng): number {
+  let baseValue: number;
+  switch (sixteenth) {
+    case 0:
+      baseValue = 0.95;
+      break;
+    case 2:
+      baseValue = 0.75;
+      break;
+    case 1:
+      baseValue = 0.55;
+      break;
+    default:
+      baseValue = 0.5;
+      break;
+  }
+  return baseValue * rng.float(0.95, 1.05);
+}
+
+/** Bars between dynamic open hi-hat accents (0 disables them). */
+export function openHiHatBarInterval(section: SectionType, style: DrumStyle): number {
+  if (style === 'sparse') {
+    return section === 'chorus' ? 4 : 0;
+  }
+  switch (section) {
+    case 'intro':
+      return style === 'fourOnFloor' ? 4 : 0;
+    case 'a':
+      return style === 'fourOnFloor' || style === 'upbeat' ? 2 : 4;
+    case 'b':
+      return 2;
+    case 'chorus':
+      return style === 'rock' || style === 'fourOnFloor' ? 1 : 2;
+    case 'bridge':
+      return 0;
+    case 'outro':
+      return 4;
+  }
+}
+
+/** Beat that receives the dynamic open hi-hat within a bar. */
+export function openHiHatBeat(section: SectionType, rng: DrumRng): number {
+  if (section === 'chorus') {
+    const choice = rng.range(0, 3);
+    if (choice < 2) {
+      return 3;
+    }
+    if (choice < 3) {
+      return 1;
+    }
+    return 2;
+  }
+  return 3;
+}
+
+/** Whether the section uses an independent foot hi-hat pulse. */
+export function shouldUseFootHiHat(section: SectionType, role: DrumRole): boolean {
+  if (role === 'fxOnly') {
+    return false;
+  }
+  switch (section) {
+    case 'intro':
+    case 'bridge':
+    case 'outro':
+      return true;
+    default:
+      return role === 'ambient' || role === 'minimal';
+  }
+}
+
+/** Primary hi-hat articulation for a section. */
+export function sectionHiHatType(section: SectionType, role: DrumRole): HiHatType {
+  if (role === 'ambient') {
+    return 'ride';
+  }
+  if (role === 'minimal') {
+    return 'pedal';
+  }
+  switch (section) {
+    case 'intro':
+    case 'a':
+      return 'pedal';
+    case 'b':
+      return 'closed';
+    case 'chorus':
+      return 'open';
+    case 'bridge':
+      return 'ride';
+    case 'outro':
+      return 'halfOpen';
+  }
+}
+
+/** GM note for a hi-hat articulation. */
+export function hiHatNote(type: HiHatType): number {
+  switch (type) {
+    case 'pedal':
+      return GM.FHH;
+    case 'open':
+      return GM.OHH;
+    case 'ride':
+      return GM.RIDE;
+    default:
+      return GM.CHH;
+  }
+}
+
+/** Velocity multiplier for a hi-hat articulation. */
+export function hiHatTypeVelocityMultiplier(type: HiHatType): number {
+  switch (type) {
+    case 'halfOpen':
+      return 0.75;
+    case 'pedal':
+      return 0.65;
+    case 'open':
+      return 1.0;
+    case 'ride':
+      return 0.9;
+    default:
+      return 0.85;
+  }
+}
+
+/** Whether to accent with an open hi-hat at a given beat. */
+export function shouldAddOpenHHAccent(
+  section: SectionType,
+  beat: number,
+  bar: number,
+  rng: DrumRng,
+): boolean {
+  if (section !== 'chorus' && section !== 'b') {
+    return false;
+  }
+  if (section === 'chorus') {
+    if (beat === 1 || beat === 3) {
+      return rng.prob(0.6);
+    }
+    return false;
+  }
+  if (beat === 3 && bar % 2 === 1) {
+    return rng.prob(0.4);
+  }
+  return false;
+}
+
+/** Foot hi-hat velocity with slight humanization. */
+export function footHiHatVelocity(rng: DrumRng): number {
+  return rng.range(FHH_VEL_MIN, FHH_VEL_MAX);
+}
+
+/** Whether the section uses a ride cymbal instead of hi-hats. */
+export function shouldUseRideForSection(section: SectionType, style: DrumStyle): boolean {
+  if (style === 'rock' && section === 'chorus') {
+    return true;
+  }
+  if (style === 'sparse') {
+    return false;
+  }
+  return section === 'bridge';
+}
+
+/** Whether a bridge beat is carried by a cross-stick instead of the hi-hat. */
+export function shouldUseBridgeCrossStick(section: SectionType, beat: number): boolean {
+  return section === 'bridge' && (beat === 1 || beat === 3);
+}

package/src/drums/hit.ts

@@ -0,0 +1,31 @@
+import { clampVel, GM } from './internal.js';
+
+/** A single percussion onset. */
+export type DrumHit = {
+  pitch: number;
+  startBeat: number;
+  durationBeat: number;
+  velocity: number;
+};
+
+/** Accumulator for drum onsets with velocity clamping and simple lookups. */
+export class HitList {
+  readonly hits: DrumHit[] = [];
+
+  /** Append a hit, clamping velocity and dropping non-positive positions. */
+  add(pitch: number, startBeat: number, durationBeat: number, velocity: number): void {
+    this.hits.push({
+      pitch,
+      startBeat: Math.max(0, startBeat),
+      durationBeat,
+      velocity: clampVel(velocity),
+    });
+  }
+
+  /** True when a crash already sits within a 16th of `startBeat`. */
+  hasCrashNear(startBeat: number): boolean {
+    return this.hits.some(
+      (h) => h.pitch === GM.CRASH && h.startBeat >= startBeat && h.startBeat < startBeat + 0.25,
+    );
+  }
+}

package/src/drums/index.ts

@@ -0,0 +1,211 @@
+import {
+  type BeatCtx,
+  generateGhostNotesForBeat,
+  generateHiHatForBeat,
+  generateKickForBeat,
+  generatePreChorusBuildup,
+  generateSnareForBeat,
+  type SectionCtx,
+} from './beat.js';
+import { type FillType, generateFill, getFillStartBeat, selectFillType } from './fills.js';
+import {
+  footHiHatVelocity,
+  getHiHatLevel,
+  openHiHatBarInterval,
+  openHiHatBeat,
+  shouldPlayHiHat,
+  shouldUseFootHiHat,
+  shouldUseRideForSection,
+} from './hihat.js';
+import { type DrumHit, HitList } from './hit.js';
+import {
+  calculateVelocity,
+  type DrumRole,
+  type Feel,
+  feelSwingAmount,
+  GM,
+  type GrooveStyle,
+  ghostMoodCategory,
+  mapDensity,
+  mapSection,
+  mapStyle,
+  type PublicSection,
+  percMoodCategory,
+  sectionDensityMultiplier,
+  sectionEnergy,
+} from './internal.js';
+import { getKickPattern, isInPreChorusLift, type KickPattern } from './kick.js';
+import { generateAuxPercussionForBar, getPercussionConfig } from './percussion.js';
+import { createRng } from './rng.js';
+
+export type { DrumHit } from './hit.js';
+export type GrooveFeel = Feel;
+export type { DrumRole, GrooveStyle } from './internal.js';
+
+/** Public section identifiers for {@link generateDrums}. */
+export type Section = PublicSection;
+
+/** Options controlling {@link generateDrums}. */
+export type DrumGenOptions = {
+  bars: number;
+  bpm: number;
+  style: GrooveStyle;
+  section: Section;
+  density: number;
+  fills?: boolean;
+  feel?: GrooveFeel;
+  role?: DrumRole;
+  seed?: number;
+};
+
+/**
+ * Generate a drum performance as a flat list of onsets.
+ *
+ * Every voice (kick, snare, ghost snares, closed/open/foot hi-hats, ride, toms,
+ * crash, and auxiliary percussion) is emitted as a {@link DrumHit} distinguished
+ * by its General MIDI pitch. Groove style selects an internal style and feel;
+ * `density` sets the backing-density level; `section` shapes kick, hi-hat, ghost,
+ * and percussion density. 16th-note hi-hats drop to 8ths at or above 150 BPM.
+ * When `fills` is true the final bar is replaced with a fill. Output is fully
+ * determined by the options plus `seed`.
+ *
+ * @param opts Generation options.
+ * @returns Percussion onsets in bar order.
+ */
+export function generateDrums(opts: DrumGenOptions): DrumHit[] {
+  const track = new HitList();
+  const rng = createRng(opts.seed ?? 0);
+  const mapping = mapStyle(opts.style);
+  const style = mapping.style;
+  const feel: Feel = opts.feel ?? mapping.feel;
+  const role: DrumRole = opts.role ?? 'full';
+  // fxOnly leaves only fx/aux voices: the main kick, snare, ghost, and fill
+  // voices are suppressed just as timekeeping hi-hats already are.
+  const playMainVoices = role !== 'fxOnly';
+  const section = mapSection(opts.section);
+  const backingDensity = mapDensity(opts.density);
+  const swingAmount = feelSwingAmount(feel);
+
+  let densityMult = sectionDensityMultiplier(section);
+  if (backingDensity === 'thin') {
+    densityMult *= 0.75;
+  } else if (backingDensity === 'thick') {
+    densityMult *= 1.15;
+  }
+
+  const sec: SectionCtx = {
+    style,
+    feel,
+    densityMult,
+    backingDensity,
+    hhLevel: getHiHatLevel(section, style, backingDensity, opts.bpm, rng),
+    useGhostNotes:
+      (section === 'b' || section === 'chorus' || section === 'bridge') && style !== 'sparse',
+    ghostBoost: mapping.ghostBoost,
+    useRide: shouldUseRideForSection(section, style),
+    useFootHh: shouldUseFootHiHat(section, role),
+    role,
+    ghostMood: ghostMoodCategory(style),
+    snareBeat3: mapping.snareBeat3,
+  };
+
+  const ohhBarInterval = openHiHatBarInterval(section, style);
+  const energy = sectionEnergy(section);
+  const fillStartBeat = getFillStartBeat(energy);
+  const percMood = percMoodCategory(style);
+
+  const reuseSectionKick = (section === 'b' || section === 'chorus') && style !== 'sparse';
+  let sectionKick: KickPattern | undefined;
+
+  for (let bar = 0; bar < opts.bars; bar += 1) {
+    const barStart = bar * 4;
+    const isLastBar = bar === opts.bars - 1;
+
+    if (bar === 0 && section === 'chorus') {
+      track.add(GM.CRASH, barStart, 0.5, 100 * densityMult);
+    }
+
+    let barHasOpenHh = false;
+    let openHhBeatIndex = 3;
+    if (ohhBarInterval > 0 && bar % ohhBarInterval === ohhBarInterval - 1) {
+      openHhBeatIndex = openHiHatBeat(section, rng);
+      barHasOpenHh = !track.hasCrashNear(barStart + openHhBeatIndex);
+    }
+
+    let kick: KickPattern;
+    if (reuseSectionKick) {
+      sectionKick ??= getKickPattern(section, style, 0, rng);
+      kick = sectionKick;
+    } else {
+      kick = getKickPattern(section, style, bar, rng);
+    }
+
+    const inLift = isInPreChorusLift(section, bar, opts.bars, section === 'b');
+    let currentFill: FillType = 'snareRoll';
+
+    for (let beat = 0; beat < 4; beat += 1) {
+      const beatTick = barStart + beat;
+      const velocity = calculateVelocity(section, beat);
+
+      if (opts.fills && isLastBar && !inLift && beat >= fillStartBeat) {
+        if (beat === fillStartBeat) {
+          currentFill = selectFillType(section, section, style, energy, rng);
+        }
+        if (playMainVoices) {
+          generateFill(track, beatTick, beat, currentFill, velocity);
+        }
+        continue;
+      }
+
+      const ctx: BeatCtx = {
+        track,
+        beatTick,
+        beat,
+        velocity,
+        section,
+        bpm: opts.bpm,
+        bar,
+        sectionBars: opts.bars,
+        inPrechorusLift: inLift,
+        swingAmount,
+        barHasOpenHh,
+        openHhBeat: openHhBeatIndex,
+        rng,
+      };
+
+      if (playMainVoices) {
+        if (inLift) {
+          generatePreChorusBuildup(ctx, sec, isLastBar);
+        }
+        generateKickForBeat(ctx, sec, kick);
+        generateSnareForBeat(ctx, sec, section === 'intro' && bar === 0);
+        if (sec.useGhostNotes && !inLift) {
+          generateGhostNotesForBeat(ctx, sec);
+        }
+      }
+      generateHiHatForBeat(ctx, sec);
+    }
+
+    if (sec.useFootHh && shouldPlayHiHat(role)) {
+      for (let fhhBeat = 0; fhhBeat < 4; fhhBeat += 2) {
+        const fhhTick = barStart + fhhBeat;
+        const occupied = track.hits.some((h) => h.pitch === GM.FHH && h.startBeat === fhhTick);
+        if (!occupied) {
+          track.add(GM.FHH, fhhTick, 0.5, footHiHatVelocity(rng));
+        }
+      }
+    }
+
+    generateAuxPercussionForBar(
+      track,
+      barStart,
+      getPercussionConfig(percMood, section),
+      role,
+      densityMult,
+      rng,
+      opts.bpm,
+    );
+  }
+
+  return track.hits;
+}