@hum2music/expression 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@hum2music/expression",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Deterministic, seeded Humanization/expression engine for Hum2Music (swing, timing jitter, velocity, vibrato).",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/hum2music/hum2music",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hum2music/hum2music.git",
+    "directory": "packages/expression"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": ["src"],
+  "dependencies": {
+    "@hum2music/core": "0.1.0"
+  }
+}

package/src/drum-humanization.ts

@@ -0,0 +1,31 @@
+import type { InstrumentHumanizeParams } from "./humanize-params";
+
+/** A realized set of humanization values for a single drum hit (PRD §10.5). */
+export interface DrumHumanization {
+  timingOffsetMs: number;
+  velocityOffset: number;
+  swingAmount: number;
+  ghostNoteProbability: number;
+}
+
+/**
+ * Computes one drum hit's humanization. Not yet wired into a drum
+ * arranger (that's future arrangement work), but implemented and tested
+ * standalone now. `beatPositionInBar` damps the random range on downbeats,
+ * same rule-dependent approach as melody timing/velocity humanization.
+ */
+export function computeDrumHumanization(
+  params: InstrumentHumanizeParams,
+  beatPositionInBar: number,
+  random: () => number,
+): DrumHumanization {
+  const isDownbeat = Math.abs(beatPositionInBar % 4) < 1e-6;
+  const positionalScale = isDownbeat ? 0.3 : 1;
+
+  return {
+    timingOffsetMs: (random() * 2 - 1) * params.timingJitterMs * positionalScale,
+    velocityOffset: (random() * 2 - 1) * params.velocityJitterAmount * positionalScale,
+    swingAmount: params.swingAmount,
+    ghostNoteProbability: params.ghostNoteProbability,
+  };
+}

package/src/dynamics.ts

@@ -0,0 +1,53 @@
+import type { NoteEvent } from "@hum2music/core";
+import type { InstrumentHumanizeParams } from "./humanize-params";
+
+const BEATS_PER_BAR = 4;
+const POSITION_EPSILON_BEATS = 1e-6;
+
+/**
+ * Accents downbeats (start of each bar) and adds a smaller, seeded
+ * velocity variation elsewhere — the accent is a deterministic rule on
+ * metrical position, with randomness only filling in the remaining
+ * natural variation, damped on strong beats (PRD §11.2 Velocity Accent).
+ */
+export function applyVelocityHumanization(
+  notes: NoteEvent[],
+  params: InstrumentHumanizeParams,
+  random: () => number,
+): NoteEvent[] {
+  if (params.velocityJitterAmount <= 0) return notes;
+
+  return notes.map((note) => {
+    const positionInBar = note.startBeat % BEATS_PER_BAR;
+    const isDownbeat = Math.abs(positionInBar) < POSITION_EPSILON_BEATS;
+    const accent = isDownbeat ? params.velocityJitterAmount : 0;
+    const jitterScale = isDownbeat ? 0.3 : 1;
+    const jitter = (random() * 2 - 1) * params.velocityJitterAmount * 0.5 * jitterScale;
+
+    return { ...note, velocity: clampVelocity(note.velocity + accent + jitter) };
+  });
+}
+
+/**
+ * Applies a single swell (crescendo into decrescendo) across the given
+ * notes, as a simplified stand-in for phrase-level dynamics until
+ * phrase-boundary detection exists.
+ */
+export function applyDynamicArc(notes: NoteEvent[], amount: number): NoteEvent[] {
+  if (notes.length < 2 || amount <= 0) return notes;
+
+  const firstBeat = notes[0].startBeat;
+  const lastBeat = notes[notes.length - 1].startBeat;
+  const span = lastBeat - firstBeat || 1;
+  const maxArcVelocity = 10 * amount;
+
+  return notes.map((note) => {
+    const progress = (note.startBeat - firstBeat) / span;
+    const arcOffset = Math.sin(progress * Math.PI) * maxArcVelocity;
+    return { ...note, velocity: clampVelocity(note.velocity + arcOffset) };
+  });
+}
+
+function clampVelocity(velocity: number): number {
+  return Math.min(127, Math.max(1, Math.round(velocity)));
+}

package/src/groove.ts

@@ -0,0 +1,23 @@
+import type { SongSection } from "@hum2music/core";
+
+const REPEAT_INTENSITY_BOOST = 0.15;
+
+/**
+ * Looks up which song section a bar falls in and, if that section's label
+ * has occurred earlier (a repeated cycle — e.g. the second time through a
+ * chorus), nudges the humanize intensity up a little rather than leaving
+ * every repeat identically flat. A simple, rule-based "advanced groove"
+ * variation driven by song structure rather than randomness.
+ */
+export function deriveSectionalHumanizeAmount(baseAmount: number, sections: SongSection[], barIndex: number): number {
+  const sectionIndex = sections.findIndex(
+    (section) => barIndex >= section.startBarIndex && barIndex < section.startBarIndex + section.barCount,
+  );
+  if (sectionIndex === -1) return baseAmount;
+
+  const label = sections[sectionIndex].label;
+  const isRepeat = sections.slice(0, sectionIndex).some((section) => section.label === label);
+  if (!isRepeat) return baseAmount;
+
+  return Math.min(1, baseAmount + REPEAT_INTENSITY_BOOST);
+}

package/src/humanize-params.ts

@@ -0,0 +1,32 @@
+export interface InstrumentHumanizeParams {
+  timingJitterMs: number;
+  velocityJitterAmount: number;
+  swingAmount: number;
+  ghostNoteProbability: number;
+}
+
+/**
+ * Baseline (fully-humanized, `--humanize 1`) parameters per instrument.
+ * A single `--humanize` value maps to different concrete ranges per
+ * instrument rather than one shared random multiplier (PRD §11.3) —
+ * e.g. drums tolerate more timing/velocity variation than a sustained
+ * melody. Proposed values, to be tuned against real recordings.
+ */
+const INSTRUMENT_BASELINES: Record<string, InstrumentHumanizeParams> = {
+  melody: { timingJitterMs: 8, velocityJitterAmount: 6, swingAmount: 0.1, ghostNoteProbability: 0 },
+  piano: { timingJitterMs: 10, velocityJitterAmount: 10, swingAmount: 0.1, ghostNoteProbability: 0.05 },
+  bass: { timingJitterMs: 6, velocityJitterAmount: 8, swingAmount: 0.1, ghostNoteProbability: 0 },
+  drums: { timingJitterMs: 15, velocityJitterAmount: 12, swingAmount: 0.2, ghostNoteProbability: 0.15 },
+};
+
+export function deriveHumanizeParams(humanizeAmount: number, instrument: string): InstrumentHumanizeParams {
+  const baseline = INSTRUMENT_BASELINES[instrument] ?? INSTRUMENT_BASELINES.melody;
+  const amount = Math.min(1, Math.max(0, humanizeAmount));
+
+  return {
+    timingJitterMs: baseline.timingJitterMs * amount,
+    velocityJitterAmount: baseline.velocityJitterAmount * amount,
+    swingAmount: baseline.swingAmount * amount,
+    ghostNoteProbability: baseline.ghostNoteProbability * amount,
+  };
+}

package/src/humanize.ts

@@ -0,0 +1,35 @@
+import type { NoteEvent } from "@hum2music/core";
+import { applyDynamicArc, applyVelocityHumanization } from "./dynamics";
+import { deriveHumanizeParams } from "./humanize-params";
+import { applyVibrato } from "./pitch";
+import { createSeededRandom, deriveSeed } from "./rng";
+import { applySwing, applyTimingJitter } from "./timing";
+
+export interface HumanizeOptions {
+  seed: number;
+  humanizeAmount: number;
+  bpm: number;
+  instrument?: string;
+}
+
+const VIBRATO_DEPTH_CENTS_AT_FULL_HUMANIZE = 20;
+
+/**
+ * Applies the full expression/humanization pipeline to a quantized melody:
+ * swing, seeded timing/velocity variation, a phrase-level dynamic arc, and
+ * vibrato on sustained notes. Each layer is independently seeded from the
+ * same top-level seed so results are fully reproducible (PRD §15.1).
+ */
+export function humanizeMelody(notes: NoteEvent[], options: HumanizeOptions): NoteEvent[] {
+  const instrument = options.instrument ?? "melody";
+  const params = deriveHumanizeParams(options.humanizeAmount, instrument);
+  const random = createSeededRandom(deriveSeed(options.seed, instrument));
+
+  let result = notes;
+  result = applySwing(result, params.swingAmount);
+  result = applyTimingJitter(result, params, random);
+  result = applyVelocityHumanization(result, params, random);
+  result = applyDynamicArc(result, options.humanizeAmount);
+  result = applyVibrato(result, VIBRATO_DEPTH_CENTS_AT_FULL_HUMANIZE * options.humanizeAmount, options.bpm);
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./rng";
+export * from "./humanize-params";
+export * from "./timing";
+export * from "./dynamics";
+export * from "./pitch";
+export * from "./drum-humanization";
+export * from "./groove";
+export * from "./humanize";

package/src/pitch.ts

@@ -0,0 +1,28 @@
+import type { NoteEvent, PitchCurveSample } from "@hum2music/core";
+
+const MIN_DURATION_BEATS_FOR_VIBRATO = 1;
+const VIBRATO_RATE_HZ = 5.5;
+const SAMPLE_INTERVAL_MS = 20;
+
+/**
+ * Synthesizes vibrato as a sampled pitch-deviation curve (cents over time)
+ * on sustained notes, for MIDI export to turn into pitch bend. Short notes
+ * are left alone — vibrato needs enough duration to be perceptible.
+ */
+export function applyVibrato(notes: NoteEvent[], depthCents: number, bpm: number): NoteEvent[] {
+  if (depthCents <= 0) return notes;
+  const msPerBeat = 60000 / bpm;
+
+  return notes.map((note) => {
+    if (note.durationBeats < MIN_DURATION_BEATS_FOR_VIBRATO) return note;
+
+    const durationMs = note.durationBeats * msPerBeat;
+    const pitchCurve: PitchCurveSample[] = [];
+    for (let offsetMs = 0; offsetMs <= durationMs; offsetMs += SAMPLE_INTERVAL_MS) {
+      const phase = (2 * Math.PI * VIBRATO_RATE_HZ * offsetMs) / 1000;
+      pitchCurve.push({ offsetMs, cents: Math.sin(phase) * depthCents });
+    }
+
+    return { ...note, expression: { ...note.expression, pitchCurve } };
+  });
+}

package/src/rng.ts

@@ -0,0 +1,26 @@
+/** Deterministic PRNG (mulberry32): same seed always produces the same sequence. */
+export function createSeededRandom(seed: number): () => number {
+  let state = seed >>> 0;
+  return function random(): number {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * Derives a sub-seed from a top-level seed and any number of identifying
+ * parts (e.g. track name, bar index), so different tracks/bars get
+ * independent-looking but still fully reproducible randomness from one
+ * `--seed` value.
+ */
+export function deriveSeed(seed: number, ...parts: Array<string | number>): number {
+  let hash = seed >>> 0;
+  const text = parts.join("|");
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}

package/src/timing.ts

@@ -0,0 +1,49 @@
+import type { NoteEvent } from "@hum2music/core";
+import type { InstrumentHumanizeParams } from "./humanize-params";
+
+const EIGHTH_NOTE_BEATS = 0.5;
+/** At full swingAmount, an upbeat eighth note is delayed by half an eighth note (a sixteenth). */
+const SWING_DELAY_FRACTION_OF_EIGHTH = 0.5;
+const POSITION_EPSILON_BEATS = 1e-6;
+
+/** Delays upbeat eighth notes to create a swing feel; on-the-beat notes are untouched. */
+export function applySwing(notes: NoteEvent[], swingAmount: number): NoteEvent[] {
+  if (swingAmount <= 0) return notes;
+
+  return notes.map((note) => {
+    const positionInBeat = note.startBeat % 1;
+    const isUpbeatEighth = Math.abs(positionInBeat - 0.5) < POSITION_EPSILON_BEATS;
+    if (!isUpbeatEighth) return note;
+
+    const delayBeats = swingAmount * EIGHTH_NOTE_BEATS * SWING_DELAY_FRACTION_OF_EIGHTH;
+    return { ...note, startBeat: note.startBeat + delayBeats };
+  });
+}
+
+/**
+ * Adds small, seeded timing deviations, layered on top of any existing
+ * `timingOffsetMs` (e.g. the original humming's micro-timing preserved
+ * from quantization) rather than overwriting it. Deviations are scaled
+ * down on strong metrical positions (on the beat) versus weak ones (off
+ * the beat) — the jitter's *range* is rule-based, not an unconditional
+ * flat random shift applied everywhere (PRD §10.5, §11.3).
+ */
+export function applyTimingJitter(
+  notes: NoteEvent[],
+  params: InstrumentHumanizeParams,
+  random: () => number,
+): NoteEvent[] {
+  if (params.timingJitterMs <= 0) return notes;
+
+  return notes.map((note) => {
+    const isOnBeat = Math.abs(note.startBeat % 1) < POSITION_EPSILON_BEATS;
+    const positionalScale = isOnBeat ? 0.4 : 1;
+    const jitterMs = (random() * 2 - 1) * params.timingJitterMs * positionalScale;
+    const existingOffsetMs = note.expression?.timingOffsetMs ?? 0;
+
+    return {
+      ...note,
+      expression: { ...note.expression, timingOffsetMs: existingOffsetMs + jitterMs },
+    };
+  });
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.