@libraz/libcantus 0.9.3 → 0.9.4

package/src/generate/drums/index.ts

@@ -1,361 +0,0 @@
-import {
-  assertGenerationBudget,
-  assertInteger,
-  assertPositiveInt,
-  assertRange,
-} from '../../core/validation/index.js';
-import {
-  type BeatCtx,
-  generateGhostNotesForBeat,
-  generateHiHatForBeat,
-  generateKickForBeat,
-  generatePreChorusBuildup,
-  generateSnareForBeat,
-  type SectionCtx,
-} from './beat.js';
-import { euclideanRhythm } from './euclid.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';
-
-/**
- * A single drum onset emitted by {@link generateDrums}.
- *
- * @category Composition
- */
-export type { DrumHit } from './hit.js';
-
-/**
- * Groove feel (the swing/straight rhythmic character) for {@link generateDrums}.
- *
- * @category Composition
- */
-export type GrooveFeel = Feel;
-
-/**
- * Drum voicing role and groove style identifiers for {@link generateDrums}.
- *
- * @category Composition
- */
-export type { DrumRole, GrooveStyle } from './internal.js';
-
-/**
- * Public section identifiers for {@link generateDrums}.
- *
- * @category Composition
- */
-export type Section = PublicSection;
-
-/**
- * A Euclidean (Bjorklund) kick pattern for {@link generateDrums}.
- *
- * @category Composition
- */
-export type EuclideanKick = {
-  /** Number of kick onsets, clamped to `[0, steps]`. */
-  pulses: number;
-  /**
-   * Total steps in the bar (1..16).
-   *
-   * @defaultValue 16
-   */
-  steps?: number;
-  /**
-   * Steps to rotate the onsets toward later positions.
-   *
-   * @defaultValue 0
-   */
-  rotation?: number;
-};
-
-/**
- * Options controlling {@link generateDrums}.
- *
- * @category Composition
- */
-export type DrumsOptions = {
-  bars: number;
-  bpm: number;
-  style: GrooveStyle;
-  section: Section;
-  density: number;
-  /**
-   * Replace the final bar with a fill.
-   *
-   * @defaultValue false
-   */
-  fills?: boolean;
-  feel?: GrooveFeel;
-  /**
-   * Voicing role; `'fxOnly'` suppresses the main kick/snare/ghost/fill voices.
-   *
-   * @defaultValue `'full'`
-   */
-  role?: DrumRole;
-  /**
-   * Seed for the deterministic PRNG.
-   *
-   * @defaultValue 0
-   */
-  seed?: number;
-  /**
-   * Section the final-bar fill leads into. Shapes which fill archetype is
-   * chosen (into-chorus and out-of-intro fills differ from generic ones).
-   * Defaults to `section`, i.e. a within-section fill.
-   */
-  nextSection?: Section;
-  /**
-   * When set, the kick follows this Euclidean rhythm instead of the
-   * style/section pattern, giving direct access to evenly spread onsets.
-   */
-  euclideanKick?: EuclideanKick;
-};
-
-/**
- * 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 whose archetype is
- * shaped by `nextSection`; a fill that would emit nothing on its beat falls back
- * to the normal groove so the phrase end is never silent. `euclideanKick`
- * overrides the kick with an evenly-spread Euclidean pattern. Output is fully
- * determined by the options plus `seed`.
- *
- * @param opts Generation options.
- * @returns Percussion onsets in bar order.
- *
- * @example
- * ```ts
- * import { generateDrums } from '@libraz/libcantus';
- * const hits = generateDrums({ bars: 4, bpm: 120, style: 'standard', section: 'chorus', density: 0.6, fills: true });
- * // Fully determined by the options plus seed (defaults to 0).
- * ```
- *
- * @category Composition
- */
-export function generateDrums(opts: DrumsOptions): DrumHit[] {
-  assertPositiveInt(opts.bars, 'drum bars');
-  assertRange(opts.bpm, Number.MIN_VALUE, 1000, 'drum bpm');
-  assertRange(opts.density, 0, 1, 'drum density');
-  assertGenerationBudget(opts.bars * 128, 'drum hits');
-  if (opts.euclideanKick) {
-    const steps = opts.euclideanKick.steps ?? 16;
-    assertInteger(steps, 'euclidean steps', 1, 16);
-    assertInteger(opts.euclideanKick.pulses, 'euclidean pulses');
-    assertInteger(opts.euclideanKick.rotation ?? 0, 'euclidean rotation');
-  }
-  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);
-
-  // The final-bar fill is shaped by the section it leads into. When no next
-  // section is given the fill is treated as within-section (from === to).
-  const nextSection = opts.nextSection ? mapSection(opts.nextSection) : section;
-  const nextEnergy = sectionEnergy(nextSection);
-
-  const euclidSteps = opts.euclideanKick?.steps ?? 16;
-  const euclidKick = opts.euclideanKick
-    ? euclideanRhythm(opts.euclideanKick.pulses, euclidSteps, opts.euclideanKick.rotation ?? 0)
-    : undefined;
-
-  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 | undefined;
-    if (!euclidKick && reuseSectionKick) {
-      sectionKick ??= getKickPattern(section, style, 0, rng);
-      kick = sectionKick;
-    } else if (!euclidKick) {
-      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, nextSection, style, nextEnergy, rng);
-        }
-        if (playMainVoices) {
-          const before = track.hits.length;
-          generateFill(track, beatTick, beat, currentFill, velocity);
-          if (track.hits.length > before) {
-            continue;
-          }
-          // Safety net: an archetype that contributes nothing on this beat would
-          // leave a silent phrase end, so fall through to the normal groove.
-        } else {
-          // fxOnly deliberately emits no main voices on the fill beats.
-          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);
-        }
-        if (euclidKick && !inLift) {
-          const stepLength = 4 / euclidSteps;
-          for (let step = 0; step < euclidKick.length; step += 1) {
-            const onset = step * stepLength;
-            if (euclidKick[step] && Math.floor(onset) === beat) {
-              const wholeBeat = Math.abs(onset - Math.round(onset)) < 1e-9;
-              track.add(
-                GM.BD,
-                barStart + onset,
-                Math.min(0.5, stepLength),
-                velocity * (wholeBeat ? 1 : 0.85),
-              );
-            }
-          }
-        } else if (kick) {
-          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));
-        }
-      }
-    }
-
-    let percussionConfig = getPercussionConfig(percMood, section);
-    if (
-      role === 'fxOnly' &&
-      !percussionConfig.tambourine &&
-      !percussionConfig.shaker &&
-      !percussionConfig.handclap
-    ) {
-      percussionConfig = {
-        tambourine: false,
-        shaker: true,
-        handclap: false,
-        shaker16th: false,
-      };
-    }
-    generateAuxPercussionForBar(
-      track,
-      barStart,
-      percussionConfig,
-      role,
-      densityMult,
-      rng,
-      opts.bpm,
-    );
-  }
-
-  return track.hits;
-}

package/src/generate/drums/internal.ts

@@ -1,257 +0,0 @@
-/** General MIDI percussion note numbers used across the drum engine. */
-export const GM = {
-  BD: 36,
-  SD: 38,
-  SIDESTICK: 37,
-  HANDCLAP: 39,
-  CHH: 42,
-  FHH: 44,
-  OHH: 46,
-  CRASH: 49,
-  RIDE: 51,
-  TAMBOURINE: 54,
-  TOM_H: 50,
-  TOM_M: 47,
-  TOM_L: 45,
-  SHAKER: 82,
-} as const;
-
-/** One beat and one sixteenth expressed as fractions of a beat. */
-export const EIGHTH = 0.5;
-export const SIXTEENTH = 0.25;
-
-/** Internal drum style selected by the public groove style. */
-export type DrumStyle =
-  | 'sparse'
-  | 'standard'
-  | 'fourOnFloor'
-  | 'upbeat'
-  | 'rock'
-  | 'synth'
-  | 'trap'
-  | 'latin';
-
-/** Groove feel controlling off-beat swing. */
-export type Feel = 'straight' | 'swing' | 'shuffle';
-
-/** Reduced section set the engine reasons about. */
-export type SectionType = 'intro' | 'a' | 'b' | 'chorus' | 'bridge' | 'outro';
-
-/** Backing density bucket derived from the public density knob. */
-export type BackingDensity = 'thin' | 'normal' | 'thick';
-
-/** Section energy level, used to shape fills. */
-export type SectionEnergy = 'low' | 'medium' | 'high' | 'peak';
-
-/** Ghost-note mood category for the density table. */
-export enum MoodCategory {
-  Calm = 0,
-  Standard = 1,
-  Energetic = 2,
-}
-
-/** Percussion mood category for the activation table. */
-export enum PercMoodCategory {
-  Calm = 0,
-  Standard = 1,
-  Energetic = 2,
-  Idol = 3,
-  RockDark = 4,
-}
-
-/** Public groove style identifiers. */
-export type GrooveStyle =
-  | 'standard'
-  | 'funk'
-  | 'shuffle'
-  | 'bossa'
-  | 'trap'
-  | 'halftime'
-  | 'breakbeat'
-  | 'house'
-  | 'synthpop';
-
-/** Public role identifiers gating which voices are present. */
-export type DrumRole = 'full' | 'ambient' | 'minimal' | 'fxOnly';
-
-/** Public section identifiers. */
-export type PublicSection = 'intro' | 'verse' | 'prechorus' | 'chorus' | 'bridge' | 'outro';
-
-/** Resolved internal parameters for a public groove style. */
-export type StyleMapping = {
-  style: DrumStyle;
-  feel: Feel;
-  ghostBoost: boolean;
-  snareBeat3: boolean;
-};
-
-const STYLE_MAP: Record<GrooveStyle, StyleMapping> = {
-  // Standard pop pulse: kick on beats 1 and 3, backbeat snare on 2 and 4.
-  standard: { style: 'standard', feel: 'straight', ghostBoost: false, snareBeat3: false },
-  funk: { style: 'upbeat', feel: 'straight', ghostBoost: true, snareBeat3: false },
-  shuffle: { style: 'standard', feel: 'shuffle', ghostBoost: false, snareBeat3: false },
-  bossa: { style: 'latin', feel: 'straight', ghostBoost: false, snareBeat3: false },
-  trap: { style: 'trap', feel: 'straight', ghostBoost: false, snareBeat3: true },
-  halftime: { style: 'sparse', feel: 'straight', ghostBoost: false, snareBeat3: true },
-  breakbeat: { style: 'rock', feel: 'straight', ghostBoost: false, snareBeat3: false },
-  // Four-on-the-floor dance kick with idol-style auxiliary percussion.
-  house: { style: 'fourOnFloor', feel: 'straight', ghostBoost: false, snareBeat3: false },
-  // Synth-pop pulse with denser 16th hi-hats and busy kick syncopation.
-  synthpop: { style: 'synth', feel: 'straight', ghostBoost: true, snareBeat3: false },
-};
-
-/** Resolve the internal style/feel parameters for a public groove style. */
-export function mapStyle(style: GrooveStyle): StyleMapping {
-  return STYLE_MAP[style];
-}
-
-/** Map a public section to the internal section type. */
-export function mapSection(section: PublicSection): SectionType {
-  switch (section) {
-    case 'intro':
-      return 'intro';
-    case 'verse':
-      return 'a';
-    case 'prechorus':
-      return 'b';
-    case 'chorus':
-      return 'chorus';
-    case 'bridge':
-      return 'bridge';
-    case 'outro':
-      return 'outro';
-  }
-}
-
-/** Bucket the 0..1 density knob into a backing-density level. */
-export function mapDensity(density: number): BackingDensity {
-  if (density < 0.34) {
-    return 'thin';
-  }
-  if (density < 0.67) {
-    return 'normal';
-  }
-  return 'thick';
-}
-
-/** Swing amount (0..1) implied by a groove feel. */
-export function feelSwingAmount(feel: Feel): number {
-  if (feel === 'swing') {
-    return 0.33;
-  }
-  if (feel === 'shuffle') {
-    return 0.5;
-  }
-  return 0;
-}
-
-/** Ghost-note mood category derived from the internal style. */
-export function ghostMoodCategory(style: DrumStyle): MoodCategory {
-  if (style === 'sparse') {
-    return MoodCategory.Calm;
-  }
-  if (style === 'trap' || style === 'upbeat') {
-    return MoodCategory.Energetic;
-  }
-  return MoodCategory.Standard;
-}
-
-/** Percussion mood category derived from the internal style. */
-export function percMoodCategory(style: DrumStyle): PercMoodCategory {
-  switch (style) {
-    case 'sparse':
-      return PercMoodCategory.Calm;
-    case 'upbeat':
-    case 'latin':
-      return PercMoodCategory.Energetic;
-    case 'fourOnFloor':
-      return PercMoodCategory.Idol;
-    case 'trap':
-    case 'rock':
-      return PercMoodCategory.RockDark;
-    default:
-      return PercMoodCategory.Standard;
-  }
-}
-
-/** Zero-based section index shared by the ghost and percussion tables. */
-export function sectionIndex(section: SectionType): number {
-  switch (section) {
-    case 'intro':
-      return 0;
-    case 'a':
-      return 1;
-    case 'b':
-      return 2;
-    case 'chorus':
-      return 3;
-    case 'bridge':
-      return 4;
-    case 'outro':
-      return 6;
-  }
-}
-
-/** Section energy used to size fills. */
-export function sectionEnergy(section: SectionType): SectionEnergy {
-  switch (section) {
-    case 'intro':
-    case 'outro':
-      return 'low';
-    case 'a':
-    case 'bridge':
-      return 'medium';
-    case 'b':
-      return 'high';
-    case 'chorus':
-      return 'peak';
-  }
-}
-
-/** Section velocity multiplier applied to the base drum velocity. */
-export function sectionVelocityMultiplier(section: SectionType): number {
-  switch (section) {
-    case 'intro':
-    case 'outro':
-      return 0.8;
-    case 'a':
-      return 0.9;
-    case 'b':
-      return 1.0;
-    case 'chorus':
-      return 1.1;
-    case 'bridge':
-      return 0.85;
-  }
-}
-
-/** Section density multiplier before backing-density scaling. */
-export function sectionDensityMultiplier(section: SectionType): number {
-  switch (section) {
-    case 'intro':
-      return 0.5;
-    case 'a':
-      return 0.7;
-    case 'b':
-      return 0.85;
-    case 'chorus':
-      return 1.0;
-    case 'bridge':
-      return 0.6;
-    case 'outro':
-      return 0.6;
-  }
-}
-
-/** Base drum velocity for a section beat (downbeats accented). */
-export function calculateVelocity(section: SectionType, beat: number): number {
-  const base = 80;
-  const beatAdj = beat === 0 ? 10 : beat === 2 ? 5 : 0;
-  const velocity = (base + beatAdj) * sectionVelocityMultiplier(section);
-  return clampVel(velocity);
-}
-
-/** Round and clamp a velocity into the valid MIDI range. */
-export function clampVel(velocity: number): number {
-  return Math.max(1, Math.min(127, Math.round(velocity)));
-}