@libraz/libcantus 0.9.0 → 0.9.1

package/src/detect/index.ts

@@ -6,10 +6,21 @@
 
 import type { Chord, ChordQuality } from '../chord/index.js';
 import { chordPitchClasses, chordQualities, makeChord } from '../chord/index.js';
-import { majorKey, minorKey } from '../scale/index.js';
+import {
+  HARMONIC_MINOR_MASK,
+  MAJOR_MASK,
+  MELODIC_MINOR_MASK,
+  majorKey,
+  minorKey,
+  NATURAL_MINOR_MASK,
+} from '../scale/index.js';
 import type { KeyScale } from '../types.js';
 
-/** A candidate chord interpretation of a pitch set. */
+/**
+ * A candidate chord interpretation of a pitch set.
+ *
+ * @category Recognition
+ */
 export type ChordMatch = {
   rootPc: number;
   quality: ChordQuality;
@@ -25,7 +36,11 @@ export type ChordMatch = {
   bassPc?: number;
 };
 
-/** A candidate key interpretation of a pitch-class set. */
+/**
+ * A candidate key interpretation of a pitch-class set.
+ *
+ * @category Recognition
+ */
 export type KeyMatch = {
   key: KeyScale;
   mode: 'major' | 'minor';
@@ -55,6 +70,13 @@ function uniquePitchClasses(pitches: number[]): number[] {
  *
  * @param pitches MIDI pitches or bare pitch classes (octave-agnostic).
  * @returns Ranked chord interpretations (may be empty).
+ * @example
+ * ```ts
+ * import { detectChord } from '@libraz/libcantus';
+ * const matches = detectChord([60, 64, 67]); // C E G
+ * matches[0]; // { rootPc: 0, quality: 'maj', exact: true, ... }
+ * ```
+ * @category Recognition
  */
 export function detectChord(pitches: number[]): ChordMatch[] {
   const input = uniquePitchClasses(pitches);
@@ -85,7 +107,7 @@ export function detectChord(pitches: number[]): ChordMatch[] {
         quality,
         missingPcs,
         extraPcs,
-        exact: extraPcs.length === 0,
+        exact: extraPcs.length === 0 && missingPcs.length === 0,
         inversion,
       };
       if (inversion > 0) {
@@ -117,6 +139,12 @@ export function detectChord(pitches: number[]): ChordMatch[] {
  *
  * @param pitches MIDI pitches or bare pitch classes.
  * @returns The top-ranked chord, or null when nothing matches.
+ * @example
+ * ```ts
+ * import { detectChordBest } from '@libraz/libcantus';
+ * detectChordBest([60, 64, 67]); // C major triad: { rootPc: 0, quality: 'maj', ... }
+ * ```
+ * @category Recognition
  */
 export function detectChordBest(pitches: number[]): Chord | null {
   const best = detectChord(pitches)[0];
@@ -126,47 +154,78 @@ export function detectChordBest(pitches: number[]): Chord | null {
   return makeChord(best.rootPc, best.quality, best.bassPc);
 }
 
+/**
+ * Minor-scale variants scored for each minor-key candidate. Scoring against all
+ * three lets the raised sixth and seventh (e.g. the leading tone G# in A minor)
+ * count toward their own tonic instead of only penalizing it.
+ */
+const MINOR_MASK_VARIANTS = [NATURAL_MINOR_MASK, HARMONIC_MINOR_MASK, MELODIC_MINOR_MASK];
+
 /**
  * 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.
+ * appears in the input is preferred. Minor candidates are scored against the
+ * natural, harmonic, and melodic minor variants and keep the best of the three,
+ * so a minor cadence containing the leading tone still resolves to its own
+ * tonic; the returned key is always the natural-minor scale. Returns all 24
+ * keys ranked best-first, or an empty array for an empty input (mirroring
+ * {@link detectChord}).
  *
  * @param pitches MIDI pitches or bare pitch classes.
- * @returns Ranked key interpretations.
+ * @returns Ranked key interpretations (empty for an empty input).
+ * @example
+ * ```ts
+ * import { detectKey } from '@libraz/libcantus';
+ * const keys = detectKey([60, 62, 64, 65, 67, 69, 71]); // C major scale
+ * keys[0].mode; // 'major', with keys[0].key.rootPc === 0
+ * ```
+ * @category Recognition
  */
 export function detectKey(pitches: number[]): KeyMatch[] {
   const input = uniquePitchClasses(pitches);
+  if (input.length === 0) {
+    return [];
+  }
   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 total = pitches.length;
   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);
+      const masks = mode === 'major' ? [MAJOR_MASK] : MINOR_MASK_VARIANTS;
+      // Score each scale variant and keep the best; ties keep the earlier
+      // (more diatonic) variant.
       let inScale = 0;
-      let weighted = 0;
-      for (const pc of input) {
-        const offset = (pc - tonic + 12) % 12;
-        if ((key.modeMask12 >> offset) & 1) {
-          inScale += 1;
+      let weighted = Number.NEGATIVE_INFINITY;
+      for (const mask of masks) {
+        let variantInScale = 0;
+        let variantWeighted = 0;
+        for (const pc of input) {
+          const offset = (pc - tonic + 12) % 12;
+          if ((mask >> offset) & 1) {
+            variantInScale += 1;
+          }
         }
-      }
-      for (const [pc, count] of counts) {
-        const offset = (pc - tonic + 12) % 12;
-        if ((key.modeMask12 >> offset) & 1) {
-          weighted += count;
+        for (const [pc, count] of counts) {
+          const offset = (pc - tonic + 12) % 12;
+          if ((mask >> offset) & 1) {
+            variantWeighted += count;
+          }
         }
-        if (pc === tonic) {
-          weighted += count * 0.5;
+        if (variantWeighted > weighted) {
+          weighted = variantWeighted;
+          inScale = variantInScale;
         }
       }
+      weighted += (counts.get(tonic) ?? 0) * 0.5;
       results.push({
         key,
         mode,
-        fit: input.length === 0 ? 0 : inScale / input.length,
+        fit: inScale / input.length,
         score: weighted / total,
       });
     }

package/src/drums/fills.ts

@@ -32,7 +32,19 @@ export function getFillStartBeat(energy: SectionEnergy): number {
   }
 }
 
-/** Pick a fill archetype from the transition context. */
+/**
+ * Pick a fill archetype for a section transition.
+ *
+ * The transition-specific archetypes (into a chorus, out of an intro) are
+ * checked before the generic energy fills so every variation stays reachable;
+ * with `from === to` the caller effectively asks for a within-section fill.
+ *
+ * @param from Section the fill leaves.
+ * @param to Section the fill leads into.
+ * @param style Internal drum style.
+ * @param nextEnergy Energy of the section the fill leads into.
+ * @param rng Deterministic PRNG.
+ */
 export function selectFillType(
   from: SectionType,
   to: SectionType,
@@ -44,6 +56,11 @@ export function selectFillType(
     return rng.range(0, 1) === 0 ? 'simpleCrash' : 'breakdownFill';
   }
 
+  const toChorus = to === 'chorus';
+  const fromIntro = from === 'intro';
+  const highEnergy = style === 'rock' || style === 'fourOnFloor';
+
+  // Dropping into a low-energy section: keep the phrase end gentle.
   if (nextEnergy === 'low') {
     switch (rng.range(0, 2)) {
       case 0:
@@ -55,25 +72,9 @@ export function selectFillType(
     }
   }
 
-  if (nextEnergy === 'peak') {
-    switch (rng.range(0, 3)) {
-      case 0:
-        return 'tomDescend';
-      case 1:
-        return 'snareRoll';
-      case 2:
-        return 'linearFill';
-      default:
-        return 'flamsAndDrags';
-    }
-  }
-
-  const toChorus = to === 'chorus';
-  const fromIntro = from === 'intro';
-  const highEnergy = style === 'rock' || style === 'fourOnFloor';
-  const choice = rng.range(0, 7);
-
+  // Big lead-ins to a chorus take precedence over the generic energy fills.
   if (toChorus) {
+    const choice = rng.range(0, 7);
     if (highEnergy) {
       switch (choice) {
         case 0:
@@ -110,8 +111,9 @@ export function selectFillType(
     }
   }
 
+  // Leaving the intro: lighter, building character.
   if (fromIntro) {
-    switch (choice) {
+    switch (rng.range(0, 5)) {
       case 0:
       case 1:
         return 'snareRoll';
@@ -126,6 +128,8 @@ export function selectFillType(
     }
   }
 
+  // Generic medium/high/peak fills, split by style energy.
+  const choice = rng.range(0, 7);
   if (highEnergy) {
     switch (choice) {
       case 0:
@@ -339,6 +343,13 @@ export function generateFill(
       if (beat === 2) {
         track.add(GM.SD, beatTick, 1, accentVel);
         track.add(GM.BD, beatTick, 1, fillVel);
+      } else if (beat === 3) {
+        // At low energy the fill spans only beat 3, so this branch keeps the
+        // phrase end from going silent: a broad half-time backbeat snare with a
+        // light pickup into the next section.
+        track.add(GM.SD, beatTick, EIGHTH, accentVel);
+        track.add(GM.SD, beatTick + E, S, fillVel * 0.6);
+        track.add(GM.SD, beatTick + E + S, S, accentVel);
       }
       break;
   }

package/src/drums/index.ts

@@ -7,6 +7,7 @@ import {
   generateSnareForBeat,
   type SectionCtx,
 } from './beat.js';
+import { euclideanRhythm, patternToMask } from './euclid.js';
 import { type FillType, generateFill, getFillStartBeat, selectFillType } from './fills.js';
 import {
   footHiHatVelocity,
@@ -34,28 +35,106 @@ import {
   sectionDensityMultiplier,
   sectionEnergy,
 } from './internal.js';
-import { getKickPattern, isInPreChorusLift, type KickPattern } from './kick.js';
+import {
+  euclideanToKickPattern,
+  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}. */
+/**
+ * Public section identifiers for {@link generateDrums}.
+ *
+ * @category Composition
+ */
 export type Section = PublicSection;
 
-/** Options controlling {@link generateDrums}. */
+/**
+ * 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 DrumGenOptions = {
   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;
 };
 
 /**
@@ -66,11 +145,23 @@ export type DrumGenOptions = {
  * 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
+ * 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: DrumGenOptions): DrumHit[] {
   const track = new HitList();
@@ -114,6 +205,23 @@ export function generateDrums(opts: DrumGenOptions): DrumHit[] {
   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 euclidKick: KickPattern | undefined = opts.euclideanKick
+    ? euclideanToKickPattern(
+        patternToMask(
+          euclideanRhythm(
+            opts.euclideanKick.pulses,
+            opts.euclideanKick.steps ?? 16,
+            opts.euclideanKick.rotation ?? 0,
+          ),
+        ),
+      )
+    : undefined;
+
   const reuseSectionKick = (section === 'b' || section === 'chorus') && style !== 'sparse';
   let sectionKick: KickPattern | undefined;
 
@@ -133,7 +241,9 @@ export function generateDrums(opts: DrumGenOptions): DrumHit[] {
     }
 
     let kick: KickPattern;
-    if (reuseSectionKick) {
+    if (euclidKick) {
+      kick = euclidKick;
+    } else if (reuseSectionKick) {
       sectionKick ??= getKickPattern(section, style, 0, rng);
       kick = sectionKick;
     } else {
@@ -149,12 +259,20 @@ export function generateDrums(opts: DrumGenOptions): DrumHit[] {
 
       if (opts.fills && isLastBar && !inLift && beat >= fillStartBeat) {
         if (beat === fillStartBeat) {
-          currentFill = selectFillType(section, section, style, energy, rng);
+          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;
         }
-        continue;
       }
 
       const ctx: BeatCtx = {

package/src/drums/internal.ts

@@ -67,7 +67,9 @@ export type GrooveStyle =
   | 'bossa'
   | 'trap'
   | 'halftime'
-  | 'breakbeat';
+  | 'breakbeat'
+  | 'house'
+  | 'synthpop';
 
 /** Public role identifiers gating which voices are present. */
 export type DrumRole = 'full' | 'ambient' | 'minimal' | 'fxOnly';
@@ -92,6 +94,10 @@ const STYLE_MAP: Record<GrooveStyle, StyleMapping> = {
   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. */

package/src/drums/swing.ts

@@ -53,8 +53,13 @@ export function quantizeSwing(
       return base + EIGHTH + DELTA_8 * clamped;
     }
     if (offset >= EIGHTH + HALF_16TH && offset < 3 * SIXTEENTH + HALF_16TH) {
-      const result = base + EIGHTH + DELTA_8 * clamped + SIXTEENTH + DELTA_16 * clamped;
-      return Math.min(result, base + 1 - 1 / 480);
+      // 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;
   }