@libraz/libcantus 0.9.2 → 0.9.4

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)));
-}

package/src/generate/drums/kick.ts

@@ -1,160 +0,0 @@
-import { hasHit } from './euclid.js';
-import type { DrumStyle, SectionType } from './internal.js';
-import type { DrumRng } from './rng.js';
-
-/** Kick presence flags across the eight 8th-note slots of a bar. */
-export type KickPattern = {
-  beat1: boolean;
-  beat1and: boolean;
-  beat2: boolean;
-  beat2and: boolean;
-  beat3: boolean;
-  beat3and: boolean;
-  beat4: boolean;
-  beat4and: boolean;
-};
-
-const EMPTY: KickPattern = {
-  beat1: false,
-  beat1and: false,
-  beat2: false,
-  beat2and: false,
-  beat3: false,
-  beat3and: false,
-  beat4: false,
-  beat4and: false,
-};
-
-/**
- * Whether a pre-chorus bar sits in the two-bar lift into the chorus.
- *
- * @param section Current section.
- * @param bar Bar index within the section.
- * @param sectionBars Total bars in the section.
- * @param nextIsChorus Whether the following section is a chorus.
- */
-export function isInPreChorusLift(
-  section: SectionType,
-  bar: number,
-  sectionBars: number,
-  nextIsChorus: boolean,
-): boolean {
-  if (section !== 'b' || !nextIsChorus || sectionBars < 3) {
-    return false;
-  }
-  return bar >= sectionBars - 2;
-}
-
-/** Convert a 16-step euclidean bitmask into an 8th-slot kick pattern. */
-export function euclideanToKickPattern(mask: number): KickPattern {
-  const slot = (step: number) => hasHit(mask, step) || hasHit(mask, (step + 15) % 16);
-  return {
-    beat1: slot(0),
-    beat1and: slot(2),
-    beat2: slot(4),
-    beat2and: slot(6),
-    beat3: slot(8),
-    beat3and: slot(10),
-    beat4: slot(12),
-    beat4and: slot(14),
-  };
-}
-
-/**
- * Build a section- and style-aware kick pattern.
- *
- * @param section Current section.
- * @param style Internal drum style.
- * @param bar Bar index (drives variation for a few styles).
- * @param rng Deterministic PRNG for probabilistic accents.
- */
-export function getKickPattern(
-  section: SectionType,
-  style: DrumStyle,
-  bar: number,
-  rng: DrumRng,
-): KickPattern {
-  const p: KickPattern = { ...EMPTY };
-
-  if (section === 'outro') {
-    p.beat1 = true;
-    p.beat3 = true;
-    return p;
-  }
-
-  switch (style) {
-    case 'sparse':
-      p.beat1 = true;
-      if (section === 'chorus' && bar % 2 === 1) {
-        p.beat3 = true;
-      }
-      break;
-
-    case 'fourOnFloor':
-      p.beat1 = p.beat2 = p.beat3 = p.beat4 = true;
-      if (section === 'chorus' && rng.prob(0.2)) {
-        p.beat2and = true;
-      }
-      break;
-
-    case 'upbeat':
-      p.beat1 = true;
-      p.beat3 = true;
-      if (section === 'b' || section === 'chorus') {
-        p.beat2and = rng.prob(0.7);
-      }
-      if (section === 'chorus') {
-        p.beat4and = rng.prob(0.6);
-      }
-      break;
-
-    case 'rock':
-      p.beat1 = true;
-      p.beat3 = true;
-      if (section === 'chorus') {
-        p.beat2and = rng.prob(0.65);
-        p.beat4and = rng.prob(0.4);
-      } else if (section === 'b') {
-        p.beat2and = rng.prob(0.3);
-      }
-      break;
-
-    case 'synth':
-      p.beat1 = true;
-      p.beat3 = true;
-      if (section === 'b' || section === 'chorus') {
-        p.beat2and = rng.prob(0.75);
-      }
-      if (section === 'chorus') {
-        p.beat4and = rng.prob(0.65);
-      }
-      break;
-
-    case 'trap':
-      p.beat1 = true;
-      p.beat2and = rng.prob(0.8);
-      p.beat3 = rng.prob(0.3);
-      p.beat4and = rng.prob(0.7);
-      break;
-
-    case 'latin':
-      p.beat1 = true;
-      p.beat2and = true;
-      p.beat3 = true;
-      p.beat4and = rng.prob(0.5);
-      break;
-
-    default:
-      p.beat1 = true;
-      p.beat3 = true;
-      if (section === 'b') {
-        p.beat2and = rng.prob(0.5);
-      } else if (section === 'chorus') {
-        p.beat2and = rng.prob(0.55);
-        p.beat4and = rng.prob(0.35);
-      }
-      break;
-  }
-
-  return p;
-}

package/src/generate/drums/percussion.ts

@@ -1,121 +0,0 @@
-import { HH_16TH_BPM_THRESHOLD } from './hihat.js';
-import type { HitList } from './hit.js';
-import type { DrumRole, SectionType } from './internal.js';
-import { EIGHTH, GM, PercMoodCategory, SIXTEENTH, sectionIndex } from './internal.js';
-import type { DrumRng } from './rng.js';
-
-/** Enabled auxiliary percussion voices for a section. */
-export type PercussionConfig = {
-  tambourine: boolean;
-  shaker: boolean;
-  handclap: boolean;
-  shaker16th: boolean;
-};
-
-type PercActivation = [tambourine: boolean, shaker: boolean, handclap: boolean];
-
-// Percussion activation per [mood category][section index]. Columns:
-// intro, a, b, chorus, bridge, interlude, outro, chant, mixbreak.
-const F: PercActivation = [false, false, false];
-const PERC_TABLE: PercActivation[][] = [
-  /* calm */ [F, F, F, F, F, F, F, F, F],
-  /* std  */ [F, F, [false, true, false], [true, false, true], F, F, F, F, [true, false, true]],
-  /* ener */ [
-    F,
-    [false, true, false],
-    [false, true, false],
-    [true, true, true],
-    F,
-    F,
-    F,
-    F,
-    [true, true, true],
-  ],
-  /* idol */ [
-    F,
-    [false, true, false],
-    [false, true, false],
-    [true, true, true],
-    F,
-    F,
-    F,
-    F,
-    [true, true, true],
-  ],
-  /* rock */ [F, F, F, [false, false, true], F, F, F, F, [false, false, true]],
-];
-
-/** Resolve which auxiliary percussion voices play for a section. */
-export function getPercussionConfig(
-  mood: PercMoodCategory,
-  section: SectionType,
-): PercussionConfig {
-  const row = PERC_TABLE[mood] ?? PERC_TABLE[PercMoodCategory.Standard];
-  const act = row?.[sectionIndex(section)] ?? F;
-  return {
-    tambourine: act[0],
-    shaker: act[1],
-    handclap: act[2],
-    shaker16th: act[1],
-  };
-}
-
-/** Emit one bar of auxiliary percussion (tambourine/shaker/handclap). */
-export function generateAuxPercussionForBar(
-  track: HitList,
-  barStart: number,
-  config: PercussionConfig,
-  role: DrumRole,
-  densityMult: number,
-  rng: DrumRng,
-  bpm: number,
-): void {
-  if (role === 'minimal' || role === 'fxOnly') {
-    return;
-  }
-
-  if (config.tambourine) {
-    for (let beat = 1; beat <= 3; beat += 2) {
-      const raw = 70 * densityMult * rng.float(0.9, 1.1);
-      track.add(GM.TAMBOURINE, barStart + beat, EIGHTH, Math.max(40, Math.min(90, raw)));
-    }
-  }
-
-  if (config.shaker) {
-    const use16th = config.shaker16th && bpm < HH_16TH_BPM_THRESHOLD;
-    if (use16th) {
-      const velCurve = [0.75, 0.45, 0.6, 0.45];
-      for (let beat = 0; beat < 4; beat += 1) {
-        for (let sub = 0; sub < 4; sub += 1) {
-          const raw = 80 * (velCurve[sub] ?? 0.5) * densityMult * rng.float(0.9, 1.1);
-          track.add(
-            GM.SHAKER,
-            barStart + beat + sub * SIXTEENTH,
-            SIXTEENTH,
-            Math.max(25, Math.min(85, raw)),
-          );
-        }
-      }
-    } else {
-      const velCurve = [0.75, 0.55];
-      for (let beat = 0; beat < 4; beat += 1) {
-        for (let sub = 0; sub < 2; sub += 1) {
-          const raw = 80 * (velCurve[sub] ?? 0.6) * densityMult * rng.float(0.9, 1.1);
-          track.add(
-            GM.SHAKER,
-            barStart + beat + sub * EIGHTH,
-            EIGHTH,
-            Math.max(25, Math.min(85, raw)),
-          );
-        }
-      }
-    }
-  }
-
-  if (config.handclap) {
-    for (let beat = 1; beat <= 3; beat += 2) {
-      const raw = 85 * densityMult * rng.float(0.9, 1.1);
-      track.add(GM.HANDCLAP, barStart + beat, EIGHTH, Math.max(50, Math.min(100, raw)));
-    }
-  }
-}

package/src/generate/drums/rng.ts

@@ -1,7 +0,0 @@
-/**
- * The drum engine's PRNG, re-exported from the shared {@link ../random} module.
- * `DrumRng` is retained as the drum-facing name of the shared {@link Rng} type.
- */
-
-export type { Rng as DrumRng } from '../../core/random/index.js';
-export { createRng } from '../../core/random/index.js';

package/src/generate/drums/swing.ts

@@ -1,71 +0,0 @@
-import type { Feel } from './internal.js';
-
-const SIXTEENTH = 0.25;
-const EIGHTH = 0.5;
-const HALF_16TH = 0.125;
-/** Delay of an off-beat 16th at full swing (triplet minus straight), in beats. */
-const DELTA_16 = 1 / 3 - 1 / 4; // 0.08333...
-/** Delay of an off-beat 8th at full swing, in beats. */
-const DELTA_8 = (2 / 3 - 1 / 2) / 2 + (2 / 3 - 1 / 2) / 2; // 0.16667...
-
-/** Grid resolution for swing quantization. */
-export type SwingResolution = 'eighth' | 'sixteenth';
-
-/** Effective swing after applying the groove feel to a base swing amount. */
-export function effectiveSwing(feel: Feel, swingAmount: number): number {
-  if (feel === 'straight') {
-    return 0;
-  }
-  if (feel === 'shuffle') {
-    return Math.min(1, swingAmount * 1.5);
-  }
-  return swingAmount;
-}
-
-/**
- * Push an off-beat position toward its triplet placement.
- *
- * On-beat positions are returned unchanged; off-beat 8ths and 16ths are delayed
- * proportionally to the swing amount.
- *
- * @param startBeat Absolute position in beats.
- * @param swing Swing amount in [0, 1] (already feel-adjusted).
- * @param resolution Whether to swing the 16th or only the 8th grid.
- * @returns The swung position in beats.
- */
-export function quantizeSwing(
-  startBeat: number,
-  swing: number,
-  resolution: SwingResolution,
-): number {
-  const clamped = Math.max(0, Math.min(1, swing));
-  if (clamped <= 0) {
-    return startBeat;
-  }
-  const base = Math.floor(startBeat);
-  const offset = startBeat - base;
-
-  if (resolution === 'sixteenth') {
-    if (offset >= HALF_16TH && offset < SIXTEENTH + HALF_16TH) {
-      return base + SIXTEENTH + DELTA_16 * clamped;
-    }
-    if (offset >= SIXTEENTH + HALF_16TH && offset < EIGHTH + HALF_16TH) {
-      return base + EIGHTH + DELTA_8 * clamped;
-    }
-    if (offset >= EIGHTH + HALF_16TH && offset < 3 * SIXTEENTH + HALF_16TH) {
-      // The "a" 16th is the midpoint of the compressed second half of the beat
-      // (between the swung "and" and the next downbeat), mirroring the "e" 16th
-      // in the first half. Because DELTA_8 = 2 * DELTA_16, that midpoint reduces
-      // to a single DELTA_16 delay off the straight position, so the "a" never
-      // overshoots the downbeat and needs no clamp. At the default shuffle feel
-      // (swing 0.75) this lands near 0.8125 rather than the doubly-swung 0.9375.
-      return base + 3 * SIXTEENTH + DELTA_16 * clamped;
-    }
-    return startBeat;
-  }
-
-  if (offset >= SIXTEENTH && offset < 3 * SIXTEENTH) {
-    return base + EIGHTH + DELTA_8 * clamped;
-  }
-  return startBeat;
-}