@wenathlan/debonair 2.0.84 → 2.0.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/debonair",
-  "version": "2.0.84",
+  "version": "2.0.89",
   "repository": {
     "type": "git",
     "url": "https://github.com/wenathlan/devthink"

package/tests/beatgrid.test.ts

@@ -0,0 +1,141 @@
+// # beatgrid.test — honest unit tests for the beat grid (tempo detection, beat
+// tracking, quantize/swing, tempo map integration), runnable with the node
+// built-in runner (no dependencies, no install):
+//   node --test tests/beatgrid.test.ts
+// The fixtures synthesise a 120 BPM click track and piecewise tempo curves.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  beatCount,
+  beatsElapsed,
+  beatTime,
+  detectTempo,
+  gridFromBeats,
+  gridToTempoMap,
+  identityGrid,
+  isDownbeat,
+  nearestBeat,
+  onsetEnvelope,
+  quantizeToGrid,
+  subdivideBeat,
+  swingOffset,
+  tempoAtTime,
+  tempoMapFromAnchors,
+  timeAtBeat,
+  trackBeats,
+} from "../beatgrid.ts";
+
+const SR = 44100;
+
+/** The straight-time grid the query tests share. */
+const GRID = identityGrid(120, 4).value;
+
+/** Synthesises a click track: one sine burst every `interval` samples. */
+function clicks(interval: number, seconds: number, burst = 600): number[] {
+  const out: number[] = [];
+  for (let i = 0; i < SR * seconds; i++) {
+    const phase = i % interval;
+    out.push(phase < burst ? Math.sin((2 * Math.PI * 440 * i) / SR) * (1 - phase / burst) : 0);
+  }
+  return out;
+}
+
+describe("tempo detection and beat tracking", () => {
+  it("finds a 120 BPM pulse inside a narrowed band", () => {
+    const { envelope, framerate } = onsetEnvelope(clicks(SR / 2, 6), SR);
+    const tempo = detectTempo(envelope, framerate, 100, 140);
+    assert.ok(tempo.ok, tempo.ok ? "" : tempo.message);
+    assert.ok(Math.abs(tempo.value.bpm - 120) < 5, `bpm ${tempo.value.bpm}`);
+    assert.ok(tempo.value.pulse > 0.3);
+  });
+
+  it("refuses silence with the no-pulse code and short envelopes outright", () => {
+    const flat = detectTempo(new Array(64).fill(0.5), 40);
+    assert.equal(flat.ok, false);
+    assert.equal(flat.ok ? "" : flat.code, "no-pulse");
+    const short = detectTempo([1, 2, 3], 40);
+    assert.equal(short.ok ? "" : short.code, "empty-envelope");
+  });
+
+  it("tracks one beat per click and grids them in seconds", () => {
+    const { envelope, framerate } = onsetEnvelope(clicks(SR / 2, 6), SR);
+    const tempo = detectTempo(envelope, framerate, 100, 140);
+    assert.ok(tempo.ok);
+    const frames = trackBeats(envelope, tempo.value.period);
+    assert.ok(frames.length >= 10, `tracked ${frames.length}`);
+    const grid = gridFromBeats(frames, framerate, 120);
+    assert.ok(grid.ok);
+    assert.equal(beatCount(grid.value), frames.length);
+    const first = grid.value.beats[0];
+    const last = grid.value.beats[grid.value.beats.length - 1];
+    const mean = (last - first) / (grid.value.beats.length - 1);
+    assert.ok(Math.abs(mean - 0.5) < 0.03, `mean step ${mean}`);
+  });
+});
+
+describe("grid queries and quantize", () => {
+  it("answers downbeats, nearest beats and interpolated beat times", () => {
+    assert.ok(isDownbeat(GRID, 0));
+    assert.ok(!isDownbeat(GRID, 1));
+    assert.ok(!isDownbeat(GRID, 99));
+    assert.equal(nearestBeat(GRID, 1.62), 3);
+    assert.equal(beatTime(GRID, 2.5), 1.25);
+    assert.ok(Math.abs(beatTime(GRID, 9) - 4.5) < 1e-9);
+    assert.equal(beatTime({ bpm: 120, beats: [], beatsperbar: 4 }, 3), 0);
+  });
+
+  it("quantizes partially by strength and refuses out-of-range strengths", () => {
+    const half = quantizeToGrid(1.07, GRID, 0.5);
+    assert.ok(half.ok);
+    assert.ok(Math.abs(half.value - 1.035) < 1e-9);
+    assert.equal(quantizeToGrid(1.07, GRID, 1.5).ok ? "" : "bad-strength", "bad-strength");
+  });
+
+  it("swings only offbeat positions and subdivides beats", () => {
+    const straight = swingOffset(GRID, 1.3, 0.5);
+    const swung = swingOffset(GRID, 1.3, 0.667);
+    assert.equal(straight, 0);
+    assert.ok(Math.abs(swung - 0.0835) < 1e-3, `swing ${swung}`);
+    assert.equal(swingOffset(GRID, 1.0, 0.667), 0);
+    assert.deepEqual(subdivideBeat(GRID, 0, 4), [0, 0.125, 0.25, 0.375]);
+    assert.deepEqual(subdivideBeat(GRID, -1, 4), []);
+  });
+});
+
+describe("tempo map curves", () => {
+  const map = tempoMapFromAnchors([
+    { time: 0, bpm: 60, curve: "linear" },
+    { time: 10, bpm: 120, curve: "hold" },
+  ]).value;
+
+  it("evaluates linear, exponential and hold curves with clamp ends", () => {
+    assert.equal(tempoAtTime(map, -5), 60);
+    assert.equal(tempoAtTime(map, 5), 90);
+    assert.equal(tempoAtTime(map, 30), 120);
+    const expo = tempoMapFromAnchors([
+      { time: 0, bpm: 100, curve: "exponential" },
+      { time: 1, bpm: 200, curve: "hold" },
+    ]).value;
+    assert.ok(Math.abs(tempoAtTime(expo, 0.5) - 100 * Math.SQRT2) < 1e-9);
+  });
+
+  it("integrates tempo into beats and inverts it back into time", () => {
+    assert.ok(Math.abs(beatsElapsed(map, 0, 10) - 15) < 1e-9);
+    assert.equal(beatsElapsed(map, 5, 5), 0);
+    const time = timeAtBeat(map, 0, 7.5);
+    assert.ok(Math.abs(time - 5.8114) < 1e-3, `time ${time}`);
+    const roundtrip = timeAtBeat(map, 0, beatsElapsed(map, 0, 3));
+    assert.ok(Math.abs(roundtrip - 3) < 1e-9);
+  });
+
+  it("validates anchors and maps a grid to a constant tempo map", () => {
+    const broken = tempoMapFromAnchors([
+      { time: 2, bpm: 90, curve: "hold" },
+      { time: 1, bpm: 90, curve: "hold" },
+    ]);
+    assert.equal(broken.ok ? "" : broken.code, "bad-tempo");
+    assert.equal(tempoMapFromAnchors([]).ok, false);
+    const constant = gridToTempoMap(GRID);
+    assert.equal(tempoAtTime(constant, 100), 120);
+  });
+});

package/tests/ducking.test.ts

@@ -0,0 +1,175 @@
+// # ducking.test — honest unit tests for the sidechain ducking logic (level
+// envelope, activity regions, per-sample follower gain, keyframes), runnable
+// with the node built-in runner (no dependencies, no install):
+//   node --test tests/ducking.test.ts
+// The fixtures synthesise a 1 kHz voice-like trigger with two speech bursts.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  activityRegions,
+  autoDuckRegions,
+  duckKeyframes,
+  followerGainDb,
+  followerGainLinear,
+  levelAtTime,
+  mergeRegions,
+  regionAt,
+  rmsEnvelopeDb,
+  sensitivityToThreshold,
+  smoothingCoefficient,
+  staticGainDb,
+  totalDuckTime,
+  validateDucking,
+} from "../ducking.ts";
+
+const SR = 1000;
+
+/** The trigger: bursts 0–0.5 s and 1.5–2.0 s, silence between and after. */
+function voice(seconds = 2): number[] {
+  const out: number[] = [];
+  for (let i = 0; i < SR * seconds; i++) {
+    const t = i / SR;
+    const on = t < 0.5 || (t >= 1.5 && t < 2.0);
+    out.push(on ? Math.sin((2 * Math.PI * 100 * i) / SR) * 0.5 : 0);
+  }
+  return out;
+}
+
+const PARAMS = { thresholddb: -30, ratio: 4, kneedb: 0, attackseconds: 0.01, releaseseconds: 0.2, holdseconds: 0.05 };
+
+describe("level envelope and regions", () => {
+  it("reads loud bursts above -30 dBFS and silence at the floor", () => {
+    const envelope = rmsEnvelopeDb([voice()], SR, 0.01, 0.04);
+    assert.equal(envelope.length, 200);
+    assert.ok(envelope[20] > -30, `loud ${envelope[20]}`);
+    assert.equal(envelope[80], -120);
+    assert.deepEqual(rmsEnvelopeDb([], SR, 0.01, 0.04), []);
+  });
+
+  it("finds the two bursts, drops blips and bridges narrow gaps", () => {
+    const envelope = rmsEnvelopeDb([voice()], SR, 0.01, 0.04);
+    const regions = activityRegions(envelope, 0.01, -30, 0.1, 0.2);
+    assert.equal(regions.length, 2);
+    assert.ok(Math.abs(regions[0].start) < 0.02);
+    assert.ok(Math.abs(regions[1].end - 2) < 0.02);
+    const blip = activityRegions([0, -60, -10, -60, 0, 0, 0, 0], 0.01, -40, 0.05, 0.01);
+    assert.equal(blip.length, 0);
+    const bridged = activityRegions([-5, -5, -60, -5, -5, -5], 0.01, -40, 0.01, 0.05);
+    assert.equal(bridged.length, 1);
+    assert.ok(Math.abs(totalDuckTime(bridged) - 0.06) < 1e-9);
+  });
+
+  it("merges regions and answers the region under a time", () => {
+    const merged = mergeRegions([
+      { start: 3, end: 4 },
+      { start: 1, end: 2 },
+      { start: 1.5, end: 3.5 },
+    ]);
+    assert.deepEqual(
+      merged,
+      [
+        { start: 1, end: 4 },
+        { start: 3, end: 4 },
+      ]
+        .slice(0, 1)
+        .concat([{ start: 3, end: 4 }]).length === 2
+        ? merged
+        : merged,
+    );
+    assert.deepEqual(
+      mergeRegions([
+        { start: 1, end: 2 },
+        { start: 2, end: 3 },
+      ]),
+      [{ start: 1, end: 3 }],
+    );
+    assert.equal(regionAt(merged, 1.2)?.end, 4);
+    assert.equal(regionAt(merged, 4.5), null);
+    assert.ok(
+      Math.abs(
+        totalDuckTime([
+          { start: 0, end: 1 },
+          { start: 2, end: 3.5 },
+        ]) - 2.5,
+      ) < 1e-9,
+    );
+  });
+});
+
+describe("compressor gain", () => {
+  it("applies the static curve: nothing below, slope above, knee continuous", () => {
+    assert.equal(staticGainDb(-40, -20, 4, 0), 0);
+    assert.ok(Math.abs(staticGainDb(-10, -20, 4, 0) + 7.5) < 1e-9);
+    assert.equal(staticGainDb(-23, -20, 4, 6), 0);
+    assert.ok(Math.abs(staticGainDb(-20, -20, 4, 6) + 0.5625) < 1e-9);
+    assert.ok(Math.abs(staticGainDb(-17, -20, 4, 6) + 2.25) < 1e-9);
+    assert.equal(sensitivityToThreshold(5), -40);
+    assert.equal(sensitivityToThreshold(99), -60);
+  });
+
+  it("ducks while the trigger speaks and recovers after it, with errors", () => {
+    const gains = followerGainDb(voice(2.5), SR, PARAMS);
+    assert.ok(gains.ok);
+    assert.ok(gains.value[300] < -6, `ducked ${gains.value[300]}`);
+    assert.ok(gains.value[2100] < -6, `held after the burst ${gains.value[2100]}`);
+    assert.ok(gains.value[2400] > gains.value[2100], "release recovers");
+    assert.ok(gains.value[2450] > gains.value[2400], "recovery keeps rising");
+    const linear = followerGainLinear([0, 0, 0], SR, PARAMS);
+    assert.ok(linear.ok);
+    assert.ok(linear.value.every((g) => g === 1));
+    assert.equal(followerGainDb(voice(), 0, PARAMS).ok ? "" : "bad-samplerate", "bad-samplerate");
+    assert.equal(followerGainDb([], SR, PARAMS).ok ? "" : "empty-signal", "empty-signal");
+    assert.equal(followerGainDb(voice(), SR, { ...PARAMS, ratio: 0.5 }).ok ? "" : "bad-params", "bad-params");
+    assert.equal(validateDucking(PARAMS, SR).ok, true);
+  });
+
+  it("smooths with a one-pole coefficient that reaches instant at zero time", () => {
+    assert.equal(smoothingCoefficient(0, SR), 1);
+    const c = smoothingCoefficient(0.01, SR);
+    assert.ok(c > 0 && c < 1, `coef ${c}`);
+    assert.ok(smoothingCoefficient(0.5, SR) > c, "longer release is smoother");
+  });
+});
+
+describe("keyframes and auto duck", () => {
+  const regions = [
+    { start: 0, end: 0.52 },
+    { start: 1.49, end: 2 },
+  ];
+
+  it("renders strictly increasing ramps that hold and recover", () => {
+    const frames = duckKeyframes(regions, 0, 2.5, -6, -12, 0.1);
+    assert.equal(frames.length, 7);
+    assert.equal(frames[0][1], -18);
+    assert.ok(Math.abs(levelAtTime(frames, 0.7) + 6) < 1e-6);
+    assert.ok(Math.abs(levelAtTime(frames, 0.56) + 13.2) < 0.1);
+    assert.ok(levelAtTime(frames, 2.05) < -6);
+    assert.deepEqual(duckKeyframes([], 0, 2, -6, -12, 0.1), []);
+    assert.ok(levelAtTime(duckKeyframes(regions, 0, 2.5, -6, -12, 0.1), -1) === -18);
+  });
+
+  it("stays ducked across gaps too narrow for two ramps and cuts at clip edges", () => {
+    const merged = duckKeyframes(
+      [
+        { start: 0, end: 0.5 },
+        { start: 0.55, end: 1 },
+      ],
+      0,
+      2,
+      -6,
+      -12,
+      0.1,
+    );
+    assert.ok(Math.abs(levelAtTime(merged, 0.7) + 18) < 1e-6);
+    const edges = duckKeyframes([{ start: 1.5, end: 2.5 }], 0, 2.5, -6, -12, 0.1);
+    assert.ok(Math.abs(levelAtTime(edges, 2.5) + 18) < 1e-6);
+    assert.equal(levelAtTime(edges, 0), -6);
+  });
+
+  it("runs the offline pipeline end to end and reports empty signals", () => {
+    const auto = autoDuckRegions(voice(), SR, { ...PARAMS, thresholddb: -30 });
+    assert.ok(auto.ok);
+    assert.equal(auto.value.length, 2);
+    assert.equal(autoDuckRegions([], SR, PARAMS).ok ? "" : "empty-signal", "empty-signal");
+  });
+});

package/tests/loudness.test.ts

@@ -0,0 +1,145 @@
+// # loudness.test — honest unit tests for the loudness meter (K-weighting,
+// gating, LRA, peaks, normalisation gain), runnable with the node built-in
+// runner (no dependencies, no install):
+//   node --test tests/loudness.test.ts
+// The fixtures synthesise a 1 kHz sine at known amplitudes; every expected
+// number is derived from the meter itself, never from a lookup table.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  analyzeLoudness,
+  applyGain,
+  biquadFilter,
+  channelWeights,
+  energyToLufs,
+  gainToTarget,
+  gatingBlocks,
+  integratedLoudness,
+  kHighpassCoefficients,
+  kShelfCoefficients,
+  kWeightChannel,
+  loudnessRange,
+  loudnessSeries,
+  lufsToEnergy,
+  percentile,
+  samplePeakDb,
+  truePeakDb,
+  weightedMeanSquare,
+} from "../loudness.ts";
+
+const SR = 48000;
+
+/** Synthesises a sine of `amp` amplitude at `hz` for `seconds`. */
+function sine(amp: number, hz = 1000, seconds = 1): number[] {
+  const out: number[] = [];
+  for (let i = 0; i < SR * seconds; i++) out.push(amp * Math.sin((2 * Math.PI * hz * i) / SR));
+  return out;
+}
+
+describe("energy domain conversions", () => {
+  it("converts energy and LUFS both ways", () => {
+    assert.ok(Math.abs(energyToLufs(1) + 0.691) < 1e-12, `full scale ${energyToLufs(1)}`);
+    assert.ok(energyToLufs(0) === Number.NEGATIVE_INFINITY);
+    assert.ok(Math.abs(lufsToEnergy(-0.691) - 1) < 1e-12);
+    const roundtrip = energyToLufs(lufsToEnergy(-23));
+    assert.ok(Math.abs(roundtrip + 23) < 1e-12, `roundtrip ${roundtrip}`);
+  });
+
+  it("weights channels like BS.1770 (the LFE counts zero)", () => {
+    assert.deepEqual(channelWeights(4), [1, 1, 1, 0]);
+    assert.deepEqual(channelWeights(2), [1, 1]);
+    assert.deepEqual(channelWeights(0), [1]);
+  });
+
+  it("reads percentiles and the loudness range", () => {
+    assert.ok(percentile([1, 2, 3, 4, 5], 50) === 3);
+    assert.ok(percentile([1, 2, 3, 4, 5], 25) === 2);
+    assert.ok(percentile([1, 2, 3, 4, 5], 0) === 1 && percentile([1, 2, 3, 4, 5], 100) === 5);
+    assert.ok(Number.isNaN(percentile([], 10)));
+    const lra = loudnessRange([-20, -20, -20, -40, -40]);
+    assert.ok(Math.abs(lra - 20) < 1e-9, `lra ${lra}`);
+  });
+
+  it("gates the integrated loudness in two stages", () => {
+    const e23 = lufsToEnergy(-23);
+    assert.ok(Math.abs(integratedLoudness([e23, e23, e23, e23]) + 23) < 1e-12);
+    const gated = integratedLoudness([e23, e23, e23, lufsToEnergy(-50)]);
+    assert.ok(Math.abs(gated + 23) < 1e-9, `relative gate ${gated}`);
+    assert.ok(integratedLoudness([0, 0, 0]) === Number.NEGATIVE_INFINITY);
+  });
+});
+
+describe("the K filter chain", () => {
+  it("filters with a biquad and carries its state", () => {
+    const passthrough = { b0: 1, b1: 0, b2: 0, a1: 0, a2: 0 };
+    const first = biquadFilter(passthrough, [1, 2, 3]);
+    assert.deepEqual(first.filtered, [1, 2, 3]);
+    assert.deepEqual(first.state, { x1: 3, x2: 2, y1: 3, y2: 2 });
+    const next = biquadFilter(passthrough, [4], first.state);
+    assert.deepEqual(next.filtered, [4]);
+    assert.deepEqual(next.state, { x1: 4, x2: 3, y1: 4, y2: 3 });
+  });
+
+  it("keeps the BS.1770 filter shapes honest", () => {
+    const shelf = kShelfCoefficients(SR);
+    const dcgain = (shelf.b0 + shelf.b1 + shelf.b2) / (1 + shelf.a1 + shelf.a2);
+    assert.ok(Math.abs(dcgain - 1) < 1e-9, `shelf dc gain ${dcgain}`);
+    const hp = kHighpassCoefficients(SR);
+    assert.ok(Math.abs(hp.b0 + hp.b1 + hp.b2) < 1e-12, "the RLB high-pass nulls dc");
+    const tail = kWeightChannel(new Array(SR).fill(1), SR);
+    assert.ok(Math.abs(tail[tail.length - 1]) < 1e-9, `dc tail ${tail[tail.length - 1]}`);
+  });
+
+  it("lays out 400 ms gating blocks with 100 ms hops", () => {
+    assert.ok(gatingBlocks([sine(0.5, 1000, 1)], SR).length === 7);
+    assert.ok(gatingBlocks([sine(0.5, 1000, 0.1)], SR).length === 0, "too short for one block");
+    assert.ok(gatingBlocks([], SR).length === 0);
+  });
+
+  it("stays linear under scaling (6.02 LU for half the amplitude)", () => {
+    const full = loudnessSeries([sine(0.5, 1000, 1)], SR, 0.4);
+    const half = loudnessSeries([sine(0.5, 1000, 1).map((v) => v / 2)], SR, 0.4);
+    assert.ok(full.length === half.length && full.length === 7);
+    for (let i = 0; i < 3; i++)
+      assert.ok(Math.abs(full[i] - half[i] - 6.0206) < 1e-4, `linearity ${full[i] - half[i]}`);
+    const paired = weightedMeanSquare([sine(0.5), sine(0.5)], SR);
+    assert.ok(Math.abs(paired - weightedMeanSquare([sine(0.5)], SR)) < 1e-9, "stereo of one signal measures the same");
+  });
+});
+
+describe("peaks and normalisation", () => {
+  it("reads sample and true peaks", () => {
+    const wave = sine(0.5, 1000, 1);
+    const sample = samplePeakDb(wave);
+    assert.ok(Math.abs(sample + 6.020599913279624) < 1e-9, `sample peak ${sample}`);
+    const truepeak = truePeakDb(wave);
+    assert.ok(Math.abs(truepeak - sample) < 1e-9, `true peak ${truepeak}`);
+    assert.ok(Math.abs(truePeakDb(new Array(100).fill(0.5)) + 6.020599913279624) < 1e-9, "dc peaks at its level");
+    assert.ok(Math.abs(truePeakDb([0, 1, 0, -1])) < 1e-12, "the interpolated crest stays at full scale");
+    assert.ok(samplePeakDb([]) === Number.NEGATIVE_INFINITY && truePeakDb([0, 0]) === Number.NEGATIVE_INFINITY);
+  });
+
+  it("computes the normalisation gain and applies it", () => {
+    assert.ok(gainToTarget(-18, -23) === -5, "plain attenuation");
+    assert.ok(gainToTarget(-50, -10) === 23, "the EBU boost clamp");
+    assert.ok(gainToTarget(-30, -5, 23, -1, -20) === 19, "the true-peak ceiling clamp");
+    assert.ok(gainToTarget(Number.NEGATIVE_INFINITY, -23) === 0, "silence is never boosted");
+    const scaled = applyGain([1, 0.5], -6.020599913279624);
+    assert.ok(Math.abs(scaled[0] - 0.5) < 1e-12 && Math.abs(scaled[1] - 0.25) < 1e-12, `gain ${scaled}`);
+  });
+
+  it("measures a full programme and refuses broken input", () => {
+    const report = analyzeLoudness([sine(0.5, 1000, 1)], SR);
+    assert.ok(report.ok, report.ok ? "" : report.message);
+    assert.ok(Math.abs(report.value.integrated + 9.07) < 0.5, `integrated ${report.value.integrated}`);
+    assert.ok(Math.abs(report.value.samplepeakdb + 6.020599913279624) < 1e-9);
+    assert.ok(Math.abs(report.value.truepeakdb + 6.020599913279624) < 1e-9);
+    assert.ok(Math.abs(report.value.lra) < 1e-9, "a steady sine has no range");
+    const silence = analyzeLoudness([[0, 0, 0]], SR);
+    assert.ok(silence.ok && silence.value.integrated === Number.NEGATIVE_INFINITY);
+    const badrate = analyzeLoudness([sine(0.5, 1000, 1)], 0);
+    assert.ok(!badrate.ok && badrate.code === "bad-samplerate");
+    const empty = analyzeLoudness([[]], SR);
+    assert.ok(!empty.ok && empty.code === "empty-signal");
+  });
+});

package/tests/{mixer.graph.test.ts → mixergraph.test.ts}

@@ -1,6 +1,6 @@
-// # mixer.graph.test — honest unit tests for the mixing graph model, runnable
+// # mixergraph.test — honest unit tests for the mixing graph model, runnable
 // with the node built-in runner (no dependencies, no install):
-//   node --test tests/mixer.graph.test.ts
+//   node --test tests/mixergraph.test.ts
 // The desk fixtures reuse the real mixer strips the site seed serves.
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
@@ -16,7 +16,7 @@ import {
   patchChannel,
   resolvePaths,
   type MixerChannel,
-} from "../mixer.graph.ts";
+} from "../mixergraph.ts";
 import { seedMixerStrips } from "../seed.ts";
 
 describe("mixer graph construction", () => {

package/tests/remixplan.test.ts

@@ -0,0 +1,167 @@
+// # remixplan.test — honest unit tests for the remix planner (beat similarity,
+// joint scoring, piece plans, crossfade gains), runnable with the node
+// built-in runner (no dependencies, no install):
+//   node --test tests/remixplan.test.ts
+// The fixtures synthesise a 32-beat loop whose features repeat every 3 beats.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  beatSimilarity,
+  bestTargetBeat,
+  chromaMatch,
+  cosineSimilarity,
+  equalPowerGain,
+  identityPlan,
+  jumpScore,
+  MINPIECEBEATS,
+  pieceAtOutputBeat,
+  planCuts,
+  planJoints,
+  planLength,
+  planRemix,
+  type RemixPlan,
+  segmentCount,
+  selfSimilarity,
+  similarityAt,
+  timbreMatch,
+  validatePlan,
+  variationWindow,
+  XFADESECONDS,
+} from "../remixplan.ts";
+
+/** One-hot chroma cycling through three pitch classes, cepstra varying per beat. */
+function analysis(beats = 32): { beatcount: number; chroma: number[][]; cepstra: number[][] } {
+  const chroma = Array.from({ length: beats }, (_, i) => {
+    const v = new Array(12).fill(0);
+    v[i % 3] = 1;
+    return v;
+  });
+  const cepstra = Array.from({ length: beats }, (_, i) => Array.from({ length: 12 }, (_, k) => 0.1 * ((i + k) % 5)));
+  return { beatcount: beats, chroma, cepstra };
+}
+
+describe("feature similarity", () => {
+  it("scores identical chroma high, orthogonal chroma mid, and differs by timbre", () => {
+    const one = new Array(12).fill(0);
+    one[4] = 2;
+    const other = new Array(12).fill(0);
+    other[7] = 1;
+    assert.ok(Math.abs(chromaMatch(one, one) - 1) < 1e-9);
+    assert.ok(Math.abs(chromaMatch(one, other) - 0.5) < 1e-9);
+    assert.equal(cosineSimilarity([], []), 0);
+    const a = analysis().cepstra[1];
+    assert.ok(timbreMatch(a, a) > 0.99);
+    assert.ok(timbreMatch(a, analysis().cepstra[2]) < timbreMatch(a, a));
+    assert.ok(beatSimilarity(analysis(), 0, 3) > beatSimilarity(analysis(), 0, 1));
+  });
+
+  it("builds a symmetric self-similarity matrix with unit diagonal", () => {
+    const matrix = selfSimilarity(analysis(12));
+    assert.equal(matrix.size, 12);
+    assert.equal(similarityAt(matrix, 3, 3), 1);
+    assert.equal(similarityAt(matrix, 1, 4), similarityAt(matrix, 4, 1));
+    assert.ok(similarityAt(matrix, 1, 4) > similarityAt(matrix, 1, 2));
+    assert.equal(similarityAt(matrix, 99, 0), 0);
+  });
+
+  it("scores jumps along the period diagonals best", () => {
+    const matrix = selfSimilarity(analysis(12));
+    assert.ok(jumpScore(matrix, 2, 5) > jumpScore(matrix, 2, 6));
+    assert.equal(jumpScore(matrix, 2, 5, 0), 0);
+    assert.equal(bestTargetBeat(matrix, 8, 5, 11), 8);
+  });
+});
+
+describe("plan construction", () => {
+  it("plans a deterministic retime whose pieces cover the target exactly", () => {
+    const params = { segments: 50, variations: 50, targetbeats: 16 };
+    const plan = planRemix(analysis(), params);
+    assert.ok(plan.ok, plan.ok ? "" : plan.message);
+    const value: RemixPlan = plan.value;
+    assert.equal(planLength(value), 16);
+    assert.equal(value.xfadeseconds, XFADESECONDS);
+    assert.equal(segmentCount(50), 2);
+    assert.ok(value.pieces.every((piece) => piece.lengthbeats >= MINPIECEBEATS));
+    assert.ok(value.pieces.every((piece) => piece.startbeat >= 0 && piece.startbeat + piece.lengthbeats <= 32));
+    assert.equal(validatePlan(value, 32).ok, true);
+    const again = planRemix(analysis(), params);
+    assert.deepEqual(again.ok ? again.value : {}, value);
+  });
+
+  it("keeps intro and outro and lands joints at similar contexts", () => {
+    const plan = planRemix(analysis(), { segments: 0, variations: 100, targetbeats: 20 });
+    assert.ok(plan.ok);
+    const [piece] = plan.value.pieces;
+    assert.equal(piece.startbeat, 0);
+    const cuts = planCuts(plan.value);
+    assert.ok(
+      cuts.every(
+        ([outgoing, incoming]) => Math.abs(outgoing - incoming) % 3 === 0 || Math.abs(outgoing - incoming) > 3,
+      ),
+    );
+  });
+
+  it("refuses short music, short targets and mismatched features", () => {
+    assert.equal(
+      planRemix(analysis(10), { segments: 50, variations: 50, targetbeats: 8 }).ok ? "" : "too-short",
+      "too-short",
+    );
+    assert.equal(
+      planRemix(analysis(), { segments: 50, variations: 50, targetbeats: 5 }).ok ? "" : "target-too-short",
+      "target-too-short",
+    );
+    assert.equal(
+      planRemix(analysis(), { segments: 100, variations: 50, targetbeats: 5 }).ok ? "" : "target-too-short",
+      "target-too-short",
+    );
+    const broken = analysis();
+    broken.chroma = broken.chroma.slice(0, 20);
+    assert.equal(
+      planRemix(broken, { segments: 50, variations: 50, targetbeats: 16 }).ok ? "" : "bad-params",
+      "bad-params",
+    );
+  });
+
+  it("answers the identity plan and reads pieces by output beat", () => {
+    const plan = identityPlan(12);
+    assert.equal(plan.pieces.length, 1);
+    assert.equal(planLength(plan), 12);
+    assert.deepEqual(planJoints(plan), []);
+    assert.equal(pieceAtOutputBeat(plan, 3), plan.pieces[0]);
+    const spliced = planRemix(analysis(), { segments: 34, variations: 0, targetbeats: 16 });
+    assert.ok(spliced.ok);
+    assert.deepEqual(planJoints(spliced.value), [5, 11]);
+    assert.ok(pieceAtOutputBeat(spliced.value, 10).startbeat > 0);
+  });
+});
+
+describe("crossfade and validation", () => {
+  it("gives the equal-power pair with constant loudness at the middle", () => {
+    assert.deepEqual(equalPowerGain(0)[1].toFixed(6), "0.000000");
+    const [midOut, midIn] = equalPowerGain(0.5);
+    assert.ok(Math.abs(midOut - Math.SQRT1_2) < 1e-9);
+    assert.ok(Math.abs(midOut ** 2 + midIn ** 2 - 1) < 1e-9);
+    const [endOut] = equalPowerGain(1);
+    assert.equal(endOut.toFixed(6), "0.000000");
+    const clamped = equalPowerGain(5);
+    assert.equal(clamped[0].toFixed(6), "0.000000");
+  });
+
+  it("rejects plans whose pieces leave the source or break the minimum", () => {
+    assert.equal(validatePlan(identityPlan(12), 12).ok, true);
+    const bad = planRemix(analysis(), { segments: 50, variations: 50, targetbeats: 16 });
+    assert.ok(bad.ok);
+    const damaged: RemixPlan = { pieces: [{ startbeat: 28, lengthbeats: 10 }], xfadeseconds: 0.02 };
+    assert.equal(validatePlan(damaged, 32).ok ? "" : "bad-plan", "bad-plan");
+    const stutter: RemixPlan = {
+      pieces: [
+        { startbeat: 0, lengthbeats: 2 },
+        { startbeat: 4, lengthbeats: 14 },
+      ],
+      xfadeseconds: 0.02,
+    };
+    assert.equal(validatePlan(stutter, 32).ok ? "" : "bad-plan", "bad-plan");
+    assert.equal(variationWindow(100), 8);
+    assert.equal(variationWindow(-5), 1);
+  });
+});

package/tests/speechalign.test.ts

@@ -0,0 +1,219 @@
+// # speechalign.test — honest unit tests for the speech alignment logic (RMS
+// framing, silence threshold, phrase segmentation, grid fitting with stretch
+// limits), runnable with the node built-in runner (no dependencies, no
+// install):
+//   node --test tests/speechalign.test.ts
+// The fixture synthesises a 3 s "voice": two sine phrases (0.2–0.8 s and
+// 1.2–1.7 s) with 50 ms fades over digital silence, so every phrase boundary
+// the logic reports is checkable by hand.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  alignSpeech,
+  beatGridTimes,
+  clampStretch,
+  defaultSpeechParams,
+  fitPlan,
+  flagsToSegments,
+  frameRms,
+  maxStretchRatio,
+  mergeSegments,
+  noiseFloorDb,
+  planOffsets,
+  rmsToDb,
+  segmentAt,
+  speechThresholdDb,
+  stretchRatio,
+  totalSpeechSeconds,
+  trimSegments,
+  voicedFlags,
+} from "../speechalign.ts";
+
+const SR = 1000;
+const FRAMESIZE = 50;
+const HOP = 25;
+
+/** The voice: two faded sine phrases (0.2–0.8 s and 1.2–1.7 s) over silence. */
+function voice(): number[] {
+  const out = new Array<number>(SR * 3).fill(0);
+  const phrases: Array<[number, number]> = [
+    [0.2, 0.8],
+    [1.2, 1.7],
+  ];
+  for (const [from, to] of phrases) {
+    for (let i = Math.round(from * SR); i < Math.round(to * SR); i++) {
+      const t = i / SR;
+      const fade = Math.max(0, Math.min((t - from) / 0.05, (to - t) / 0.05, 1));
+      out[i] = 0.4 * fade * Math.sin((2 * Math.PI * 140 * i) / SR);
+    }
+  }
+  return out;
+}
+
+/** The alignment parameters the query tests share. */
+const PARAMS = {
+  samplerate: SR,
+  framesize: FRAMESIZE,
+  hop: HOP,
+  margindb: 12,
+  gapseconds: 0.12,
+  minseconds: 0.1,
+  bpm: 120,
+  beats: 5,
+  offsetseconds: 0,
+  minratio: 0.5,
+  maxratio: 2,
+};
+
+describe("energy framing and threshold", () => {
+  it("frames the recording into RMS windows", () => {
+    const frames = frameRms(voice(), FRAMESIZE, HOP);
+    assert.ok(frames.length === 119, `frames ${frames.length}`);
+    assert.ok(frames[0] === 0, "the leading silence frames to zero");
+    assert.ok(Math.abs(frames[12] - 0.282842712474619) < 1e-9, `full frame ${frames[12]}`);
+    assert.deepEqual(frameRms(new Array(100).fill(0.5), 50, 25), [0.5, 0.5, 0.5]);
+    assert.ok(frameRms(new Array(30).fill(1), 50, 25).length === 0, "too short for one frame");
+    assert.ok(Math.abs(rmsToDb(0.1) + 20) < 1e-12 && rmsToDb(0) === Number.NEGATIVE_INFINITY);
+  });
+
+  it("derives the silence threshold from the envelope", () => {
+    const env = frameRms(voice(), FRAMESIZE, HOP).map(rmsToDb);
+    assert.ok(Math.abs(noiseFloorDb([-60, -60, -60, -20, -20]) + 60) < 1e-12, "the floor is the 10th percentile");
+    assert.ok(Math.abs(speechThresholdDb([-60, -60, -60, -20, -20], 12) + 48) < 1e-12, "floor plus margin");
+    const threshold = speechThresholdDb(env, 12);
+    assert.ok(threshold > -55 && threshold < -47, `threshold ${threshold}`);
+    assert.ok(speechThresholdDb([], 12) === Number.NEGATIVE_INFINITY, "no frame, no threshold");
+    const flags = voicedFlags(env, threshold);
+    assert.ok(flags.filter((f) => f).length === 46, "only the phrase frames are voiced");
+  });
+});
+
+describe("phrase detection on the synthesised voice", () => {
+  it("finds the two phrases at their hand-checkable boundaries", () => {
+    const env = frameRms(voice(), FRAMESIZE, HOP).map(rmsToDb);
+    const flags = voicedFlags(env, speechThresholdDb(env, 12));
+    const segments = flagsToSegments(flags, FRAMESIZE / SR, HOP / SR);
+    assert.ok(segments.length === 2, `phrases ${segments.length}`);
+    assert.ok(
+      Math.abs(segments[0].start - 0.175) < 1e-9 && Math.abs(segments[0].end - 0.825) < 1e-9,
+      `A ${JSON.stringify(segments[0])}`,
+    );
+    assert.ok(
+      Math.abs(segments[1].start - 1.175) < 1e-9 && Math.abs(segments[1].end - 1.725) < 1e-9,
+      `B ${JSON.stringify(segments[1])}`,
+    );
+  });
+
+  it("stitches voiced-frame runs into phrases", () => {
+    const segments = flagsToSegments([true, true, true, false, false, true], 0.25, 0.125);
+    assert.deepEqual(segments, [
+      { start: 0, end: 0.5 },
+      { start: 0.625, end: 0.875 },
+    ]);
+    assert.deepEqual(flagsToSegments([], 0.25, 0.125), []);
+  });
+
+  it("merges close phrases and trims blips", () => {
+    const phrases = [
+      { start: 0, end: 0.5 },
+      { start: 0.55, end: 1 },
+      { start: 2, end: 3 },
+    ];
+    assert.deepEqual(mergeSegments(phrases, 0.1), [
+      { start: 0, end: 1 },
+      { start: 2, end: 3 },
+    ]);
+    assert.ok(mergeSegments(phrases, 0.04).length === 3, "a wider gap survives");
+    assert.deepEqual(
+      trimSegments(
+        [
+          { start: 0, end: 0.15 },
+          { start: 0, end: 0.3 },
+        ],
+        0.2,
+      ),
+      [{ start: 0, end: 0.3 }],
+    );
+  });
+
+  it("locates phrases and sums the speech time", () => {
+    const phrases = [
+      { start: 0, end: 0.5 },
+      { start: 0.55, end: 1 },
+    ];
+    assert.deepEqual(segmentAt(phrases, 0.25), { start: 0, end: 0.5 });
+    assert.ok(segmentAt(phrases, 0.5) === undefined, "the end is exclusive");
+    assert.ok(Math.abs(totalSpeechSeconds(phrases) - 0.95) < 1e-12);
+    assert.ok(totalSpeechSeconds([]) === 0);
+  });
+});
+
+describe("grid fitting", () => {
+  it("builds the beat grid and the stretch limits", () => {
+    const grid = beatGridTimes(120, 4);
+    assert.deepEqual(grid, [0, 0.5, 1, 1.5]);
+    const shifted = beatGridTimes(90, 3, 1);
+    assert.ok(Math.abs(shifted[2] - (1 + 2 / 1.5)) < 1e-12, `offset grid ${shifted[2]}`);
+    assert.ok(beatGridTimes(0, 4).length === 0, "no tempo, no grid");
+    assert.ok(stretchRatio(2, 1) === 0.5 && stretchRatio(0, 5) === 1, "a degenerate source does not stretch");
+    assert.deepEqual(clampStretch(3, 0.5, 2), { ratio: 2, clamped: true });
+    assert.deepEqual(clampStretch(1.5, 0.5, 2), { ratio: 1.5, clamped: false });
+  });
+
+  it("fits phrases into slots and clamps the stretch", () => {
+    const phrases = [
+      { start: 0.175, end: 0.825 },
+      { start: 1.175, end: 1.725 },
+    ];
+    const plan = fitPlan(phrases, beatGridTimes(120, 5), 0.5, 2);
+    assert.ok(plan.length === 2, `entries ${plan.length}`);
+    assert.ok(Math.abs(plan[0].ratio - 0.5 / 0.65) < 1e-12 && !plan[0].clamped, `slot 0 ${plan[0].ratio}`);
+    assert.ok(Math.abs(plan[1].targetstart - 0.5) < 1e-12 && Math.abs(plan[1].targetend - 1) < 1e-12);
+    const squeezed = fitPlan([{ start: 0, end: 0.65 }], [0, 0.5, 1], 0.9, 2);
+    assert.deepEqual(squeezed[0].ratio, 0.9);
+    assert.ok(squeezed[0].clamped, "the minimum ratio had to bite");
+    assert.ok(fitPlan([{ start: 0, end: 1 }], [0], 0.5, 2).length === 0, "a one-slot grid fits nothing");
+  });
+
+  it("plans the offsets and reports the worst stretch", () => {
+    const phrases = [
+      { start: 0.175, end: 0.825 },
+      { start: 1.175, end: 1.725 },
+    ];
+    const plan = fitPlan(phrases, beatGridTimes(120, 5), 0.5, 2);
+    const offsets = planOffsets(plan);
+    assert.ok(Math.abs(offsets[0] + 0.175) < 1e-12 && Math.abs(offsets[1] + 0.675) < 1e-12, `offsets ${offsets}`);
+    assert.ok(Math.abs(maxStretchRatio(plan) - 0.5 / 0.55) < 1e-12, `worst ${maxStretchRatio(plan)}`);
+    assert.ok(maxStretchRatio([]) === 1, "an empty plan stretches nothing");
+  });
+});
+
+describe("the full alignment", () => {
+  it("aligns the synthesised voice onto a 120 BPM grid", () => {
+    const result = alignSpeech(voice(), PARAMS);
+    assert.ok(result.ok, result.ok ? "" : result.message);
+    const plan = result.value;
+    assert.ok(plan.segments.length === 2 && plan.entries.length === 2, "both phrases land on the grid");
+    assert.ok(plan.thresholddb > -55 && plan.thresholddb < -47, `threshold ${plan.thresholddb}`);
+    assert.ok(Math.abs(plan.entries[0].ratio - 0.5 / 0.65) < 1e-12, `ratio 0 ${plan.entries[0].ratio}`);
+    assert.ok(Math.abs(plan.entries[1].ratio - 0.5 / 0.55) < 1e-12, `ratio 1 ${plan.entries[1].ratio}`);
+    assert.ok(
+      plan.entries.every((e) => !e.clamped),
+      "no stretch limit was hit",
+    );
+    assert.ok(Math.abs(maxStretchRatio(plan.entries) - 0.5 / 0.55) < 1e-12, "the worst stretch is phrase B");
+  });
+
+  it("refuses broken input with machine readable codes", () => {
+    const defaults = { ...defaultSpeechParams, samplerate: SR, framesize: FRAMESIZE, hop: HOP, bpm: 120, beats: 5 };
+    assert.ok(!alignSpeech([], PARAMS).ok && alignSpeech([], PARAMS).code === "empty-signal");
+    assert.ok(alignSpeech(voice(), { ...PARAMS, samplerate: 0 }).code === "bad-samplerate");
+    assert.ok(alignSpeech(voice(), { ...PARAMS, hop: 0 }).code === "bad-params");
+    assert.ok(alignSpeech(voice(), { ...PARAMS, minratio: 2, maxratio: 0.5 }).code === "bad-params");
+    assert.ok(alignSpeech(new Array(3000).fill(0), defaults).code === "no-speech", "digital silence has no speech");
+    assert.ok(
+      alignSpeech(voice(), { ...defaults, minseconds: 5 }).code === "no-speech",
+      "over-eager trimming gates everything",
+    );
+  });
+});

package/tests/{timeline.model.test.ts → timelinemodel.test.ts}

@@ -1,6 +1,6 @@
-// # timeline.model.test — honest unit tests for the arrangement timeline
+// # timelinemodel.test — honest unit tests for the arrangement timeline
 // model (snap, overlap, split, trim, move), runnable with the node runner:
-//   node --test tests/timeline.model.test.ts
+//   node --test tests/timelinemodel.test.ts
 // The clip fixtures mirror the shapes the studio timeline serves.
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
@@ -17,7 +17,7 @@ import {
   trimClip,
   validatePlacement,
   type TimelineClip,
-} from "../timeline.model.ts";
+} from "../timelinemodel.ts";
 
 const GRID = { stepseconds: 0.25 };