@wenathlan/cadria 2.0.93 → 2.0.117

package/tests/audiofeatures.test.ts

@@ -0,0 +1,271 @@
+// # audiofeatures.test — the descriptor contract of the cadria audio wave,
+// runnable with vitest:
+//   pnpm vitest run tests/audiofeatures.test.ts
+// The tests watch the three promises the module makes: the 32-dim vector is
+// total (right length, finite, clamped 0-1) no matter how damaged the input,
+// the answer is deterministic (same stats or same pcm → same descriptor and
+// seed, different audio → different seed), and the documented monotonic
+// mappings hold (louder dynamics range → higher contrast dim, faster bpm →
+// higher tempo dim) so the image-mapping wave can trust every dim by index.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import type { DescriptorStats } from "../audioattributes.ts";
+import {
+  audioSeed,
+  audioSeedFromStats,
+  DESCRIPTOR_DIMS,
+  DIM_ORDER,
+  descriptorSummary,
+  fuseDescriptor,
+  normalize01,
+  zcurve,
+} from "../audiofeatures.ts";
+
+/** one believable mid-tempo minor-key clip, all fields in documented units. */
+const baseStats: DescriptorStats = {
+  spectral: {
+    centroidMean: 2200,
+    centroidStd: 900,
+    rolloffMean: 7200,
+    flatnessMean: 0.12,
+    flatnessStd: 0.05,
+    fluxMean: 0.08,
+    fluxStd: 0.04,
+    bandBalance: [0.5, 0.6, 0.7, 0.6, 0.4, 0.2, 0.1],
+    brightnessIndex: 0.55,
+  },
+  rhythm: {
+    bpm: 124,
+    confidence: 0.82,
+    onsetsPerSecond: 3.4,
+    regularityIndex: 0.71,
+    swing: { ratio: 0.58, swung: true },
+    downbeatPeriodBeats: 4,
+  },
+  harmonic: {
+    key: { tonic: 9, mode: "minor", strength: 0.64 },
+    chromaEnergy: [0.3, 0.2, 0.5, 0.2, 0.4, 0.1, 0.2, 0.3, 0.9, 0.2, 0.3, 0.2],
+    harmonicChangeRate: 0.31,
+    dissonanceIndex: 0.22,
+  },
+  timbre: {
+    noisiness: 0.34,
+    warmth: 0.61,
+    dynamics: { rangeDb: 18.5, crestFactor: 8.2 },
+    brightness: 0.58,
+    slopeMean: -5.5,
+    zcrMean: 0.11,
+  },
+  structure: {
+    durationMs: 213000,
+    peakSectionMs: 24000,
+    repetitionIndex: 0.42,
+    narrativeShape: "arch",
+    sectionCount: 6,
+  },
+};
+
+/** every field broken at once — NaN, infinities, wrong literals, short arrays. */
+const damagedStats = {
+  spectral: {
+    centroidMean: NaN,
+    centroidStd: Infinity,
+    rolloffMean: NaN,
+    flatnessMean: NaN,
+    flatnessStd: NaN,
+    fluxMean: -5,
+    fluxStd: 99,
+    bandBalance: [NaN, NaN, NaN],
+    brightnessIndex: NaN,
+  },
+  rhythm: {
+    bpm: NaN,
+    confidence: NaN,
+    onsetsPerSecond: NaN,
+    regularityIndex: NaN,
+    swing: { ratio: NaN, swung: "yes" },
+    downbeatPeriodBeats: NaN,
+  },
+  harmonic: {
+    key: { tonic: NaN, mode: "dorian", strength: NaN },
+    chromaEnergy: [NaN],
+    harmonicChangeRate: NaN,
+    dissonanceIndex: NaN,
+  },
+  timbre: {
+    noisiness: NaN,
+    warmth: NaN,
+    dynamics: { rangeDb: NaN, crestFactor: NaN },
+    brightness: NaN,
+    slopeMean: NaN,
+    zcrMean: NaN,
+  },
+  structure: {
+    durationMs: NaN,
+    peakSectionMs: NaN,
+    repetitionIndex: NaN,
+    narrativeShape: "crescendo",
+    sectionCount: NaN,
+  },
+} as unknown as DescriptorStats;
+
+/** 0.1 s of 440 hz sine at 44.1 khz — stable deterministic fixture. */
+function sine440(): Float32Array {
+  const out = new Float32Array(8820);
+  for (let i = 0; i < out.length; i += 1) out[i] = 0.5 * Math.sin((2 * Math.PI * 440 * i) / 44100);
+  return out;
+}
+
+/** 0.1 s of lcg noise — clearly different bits from the sine fixture. */
+function noiseburst(): Float32Array {
+  const out = new Float32Array(8820);
+  let state = 123456789;
+  for (let i = 0; i < out.length; i += 1) {
+    state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+    out[i] = (state / 2147483648 - 1) * 0.5;
+  }
+  return out;
+}
+
+describe("audiofeatures vector", () => {
+  it("fuses exactly 32 dims in the documented order", () => {
+    const d = fuseDescriptor(baseStats);
+    assert.equal(DIM_ORDER.length, DESCRIPTOR_DIMS);
+    assert.equal(d.vector.length, DESCRIPTOR_DIMS);
+    assert.equal(d.version, 1);
+    // spot-check the documented order at the group edges
+    assert.equal(d.vector[0], normalize01(2200, 0, 8000)); // spectral centroid
+    assert.equal(d.vector[6], 0.55); // brightness passes through
+    assert.equal(d.vector[7], zcurve(124, 110, 40)); // tempo
+    assert.equal(d.vector[21], normalize01(18.5, 0, 60)); // dynamics contrast
+    assert.equal(d.vector[31], 0.64); // mood shadow = key strength × minor
+  });
+  it("keeps every dim finite and clamped to 0-1", () => {
+    const d = fuseDescriptor(baseStats);
+    for (const v of d.vector) {
+      assert.ok(Number.isFinite(v));
+      assert.ok(v >= 0 && v <= 1);
+    }
+  });
+  it("folds the band balance into the cross dims", () => {
+    const low = fuseDescriptor({
+      ...baseStats,
+      spectral: { ...baseStats.spectral, bandBalance: [1, 0.9, 0.2, 0.1, 0, 0, 0] },
+    });
+    const high = fuseDescriptor({
+      ...baseStats,
+      spectral: { ...baseStats.spectral, bandBalance: [0, 0, 0, 0.1, 0.2, 0.9, 1] },
+    });
+    assert.ok(low.vector[30] > 0.5); // band tilt leans dark
+    assert.ok(high.vector[30] < 0.5); // band tilt leans bright
+  });
+  it("marks the mood shadow only on a minor key", () => {
+    const minor = fuseDescriptor(baseStats);
+    const major = fuseDescriptor({
+      ...baseStats,
+      harmonic: { ...baseStats.harmonic, key: { ...baseStats.harmonic.key, mode: "major" } },
+    });
+    assert.equal(minor.scalar.minor, 1);
+    assert.ok(minor.vector[31] > 0);
+    assert.equal(major.vector[31], 0);
+  });
+});
+
+describe("audiofeatures determinism", () => {
+  it("answers a deep-equal descriptor for the same stats twice", () => {
+    assert.deepEqual(fuseDescriptor(baseStats), fuseDescriptor(baseStats));
+    assert.equal(fuseDescriptor(baseStats).seed, audioSeedFromStats(baseStats));
+  });
+  it("stays stable and frozen at version 1", () => {
+    const d = fuseDescriptor(baseStats);
+    assert.equal(d.version, 1);
+    assert.ok(Object.isFrozen(d));
+    assert.ok(Object.isFrozen(d.vector));
+    assert.ok(Object.isFrozen(d.scalar));
+  });
+  it("seeds identically from the same pcm fixture", () => {
+    assert.equal(audioSeed(sine440()), audioSeed(sine440()));
+    assert.match(audioSeed(sine440()), /^[0-9a-f]{16}$/);
+  });
+  it("seeds differently for clearly different pcm fixtures", () => {
+    assert.notEqual(audioSeed(sine440()), audioSeed(noiseburst()));
+  });
+  it("seeds differently for different stats and never for identical ones", () => {
+    const a = audioSeedFromStats(baseStats);
+    const b = audioSeedFromStats({ ...baseStats, rhythm: { ...baseStats.rhythm, bpm: 126 } });
+    assert.equal(a, audioSeedFromStats(baseStats));
+    assert.notEqual(a, b);
+    assert.match(b, /^[0-9a-f]{16}$/);
+  });
+  it("survives empty, tiny and non-pcm input with a stable seed", () => {
+    const empty = audioSeed(new Float32Array(0));
+    assert.match(empty, /^[0-9a-f]{16}$/);
+    assert.equal(empty, audioSeed(new Float32Array(0)));
+    assert.notEqual(empty, audioSeed(new Float32Array(1))); // length folds in
+    assert.equal(audioSeed(undefined as unknown as Float32Array), empty);
+  });
+});
+
+describe("audiofeatures monotonic mappings", () => {
+  it("maps a wider dynamics range to a higher contrast dim (21)", () => {
+    const loud = fuseDescriptor({
+      ...baseStats,
+      timbre: { ...baseStats.timbre, dynamics: { rangeDb: 50, crestFactor: 8.2 } },
+    });
+    const quiet = fuseDescriptor({
+      ...baseStats,
+      timbre: { ...baseStats.timbre, dynamics: { rangeDb: 10, crestFactor: 8.2 } },
+    });
+    assert.ok(loud.vector[21] > quiet.vector[21]);
+  });
+  it("maps a faster bpm to a higher tempo dim (7)", () => {
+    const fast = fuseDescriptor({ ...baseStats, rhythm: { ...baseStats.rhythm, bpm: 140 } });
+    const slow = fuseDescriptor({ ...baseStats, rhythm: { ...baseStats.rhythm, bpm: 90 } });
+    assert.ok(fast.vector[7] > slow.vector[7]);
+  });
+  it("keeps zcurve monotonic across the tempo field", () => {
+    const a = zcurve(60, 110, 40);
+    const b = zcurve(110, 110, 40);
+    const c = zcurve(200, 110, 40);
+    assert.ok(a < b && b < c);
+  });
+});
+
+describe("audiofeatures helpers", () => {
+  it("clamps normalize01 on both edges, degenerate ranges and NaN", () => {
+    assert.equal(normalize01(-1, 0, 1), 0);
+    assert.equal(normalize01(2, 0, 1), 1);
+    assert.equal(normalize01(5, 0, 10), 0.5);
+    assert.equal(normalize01(NaN, 0, 1), 0);
+    assert.equal(normalize01(0.5, 1, 0), 0);
+  });
+  it("answers a lowercase summary that names key and bpm", () => {
+    const text = descriptorSummary(fuseDescriptor(baseStats));
+    assert.ok(text.includes("key"));
+    assert.ok(text.includes("bpm"));
+    assert.ok(text.includes("arch"));
+    assert.equal(text, text.toLowerCase());
+  });
+});
+
+describe("audiofeatures damage control", () => {
+  it("coerces NaN-riddled stats without emitting NaN anywhere", () => {
+    const d = fuseDescriptor(damagedStats);
+    assert.equal(d.vector.length, DESCRIPTOR_DIMS);
+    for (const v of d.vector) {
+      assert.ok(Number.isFinite(v));
+      assert.ok(v >= 0 && v <= 1);
+    }
+    for (const v of Object.values(d.scalar)) {
+      assert.ok(Number.isFinite(v));
+      assert.ok(v >= 0 && v <= 1);
+    }
+    assert.match(d.seed, /^[0-9a-f]{16}$/);
+    assert.match(descriptorSummary(d), /^[a-z]/); // still readable, lowercase
+  });
+  it("honors an explicit pcm seed override when the audio is at hand", () => {
+    const d = fuseDescriptor(baseStats, audioSeed(sine440()));
+    assert.equal(d.seed, audioSeed(sine440()));
+    assert.match(d.seed, /^[0-9a-f]{16}$/);
+  });
+});

package/tests/audiopipeline.test.ts

@@ -0,0 +1,193 @@
+// # audiopipeline.test — deterministic end-to-end tests for the wave-1
+// orchestrator, runnable with vitest:
+//   pnpm vitest run tests/audiopipeline.test.ts
+// The fixture synthesizes a 4-second 4-phase song (saw intro, hats, c-major
+// triad, decaying pad) straight into pcm — no binary files on disk.
+
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { decodeWav } from "../audiodecode.ts";
+import { analyzePcm, analyzeWavBytes, PipelineError, reportDigest } from "../audiopipeline.ts";
+
+const SAMPLE_RATE = 48000;
+
+/** appends a sine/saw tone with the given gain envelope into the track. */
+function tone(
+  track: Float32Array,
+  sampleRate: number,
+  startMs: number,
+  durationMs: number,
+  hz: number,
+  gain = 0.6,
+  kind: "sine" | "saw" = "sine",
+): void {
+  const start = Math.round((startMs / 1000) * sampleRate);
+  const length = Math.round((durationMs / 1000) * sampleRate);
+  for (let i = 0; i < length && start + i < track.length; i++) {
+    const phase = (hz * i) / sampleRate;
+    const value = kind === "saw" ? 2 * (phase - Math.floor(phase + 0.5)) : Math.sin(2 * Math.PI * phase);
+    const fade = i < length * 0.1 ? i / (length * 0.1) : i > length * 0.85 ? (length - i) / (length * 0.15) : 1;
+    track[start + i] += gain * value * fade;
+  }
+}
+
+/** the shared 4-second song fixture: a steady 120bpm kick spine under an
+ * intro saw, hats, triad and falling pad — the kick keeps the tempo band
+ * decisive for both the pcm and the quantized wav path. */
+function songFixture(): Float32Array {
+  const track = new Float32Array(4 * SAMPLE_RATE);
+  for (let t = 0; t < 4000; t += 500) tone(track, SAMPLE_RATE, t, 120, 60, 0.7);
+  tone(track, SAMPLE_RATE, 0, 1000, 110, 0.5, "saw");
+  for (const hz of [261.63, 329.63, 392.0]) tone(track, SAMPLE_RATE, 2000, 1000, hz, 0.4);
+  for (const [i, hz] of [220, 196, 174.61].entries())
+    tone(track, SAMPLE_RATE, 2000 + i * 120, 1000 - i * 120, hz, 0.45 - i * 0.12);
+  return track;
+}
+
+/** wraps pcm into a minimal 16-bit mono wav byte buffer (RIFF header). */
+function wavBytes(samples: Float32Array, sampleRate: number): Uint8Array {
+  const pcm = new Int16Array(samples.length);
+  for (let i = 0; i < samples.length; i++) {
+    const clamped = Math.max(-1, Math.min(1, samples[i]));
+    pcm[i] = Math.round(clamped * 32767);
+  }
+  const bytes = new Uint8Array(44 + pcm.length * 2);
+  const view = new DataView(bytes.buffer);
+  const text = (offset: number, value: string): void => {
+    for (let i = 0; i < value.length; i++) view.setUint8(offset + i, value.charCodeAt(i));
+  };
+  text(0, "RIFF");
+  view.setUint32(4, 36 + pcm.length * 2, true);
+  text(8, "WAVE");
+  text(12, "fmt ");
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, 1, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * 2, true);
+  view.setUint16(32, 2, true);
+  view.setUint16(34, 16, true);
+  text(36, "data");
+  view.setUint32(40, pcm.length * 2, true);
+  bytes.set(new Uint8Array(pcm.buffer), 44);
+  return bytes;
+}
+
+describe("analysis report", () => {
+  const song = songFixture();
+  const report = analyzePcm(song, SAMPLE_RATE);
+
+  it("carries schemaVersion 1 and a sane source block", () => {
+    assert.equal(report.schemaVersion, 1);
+    assert.equal(report.source.kind, "pcm");
+    assert.equal(report.source.channels, 1);
+    assert.ok(Math.abs(report.source.durationMs - 4000) < 60, `duration ${report.source.durationMs}`);
+    assert.equal(report.source.sampleRate, 22050);
+  });
+  it("answers every analysis block", () => {
+    for (const block of ["spectrum", "rhythm", "harmonic", "timbre", "structure", "descriptor"] as const) {
+      assert.ok(report[block] != null, `missing block ${block}`);
+    }
+  });
+  it("reads a sane tempo band", () => {
+    assert.ok(report.rhythm.rawBpm >= 100 && report.rhythm.rawBpm <= 145, `bpm ${report.rhythm.rawBpm}`);
+    assert.ok(report.rhythm.confidence > 0.1, `confidence ${report.rhythm.confidence}`);
+  });
+  it("keys the triad section with strength", () => {
+    assert.ok(report.harmonic.key.strength > 0, `strength ${report.harmonic.key.strength}`);
+    assert.ok(report.harmonic.key.tonic >= 0 && report.harmonic.key.tonic <= 11);
+  });
+  it("fuses a 32-dim descriptor clamped to 0-1", () => {
+    assert.equal(report.descriptor.vector.length, 32);
+    for (const dim of report.descriptor.vector) assert.ok(Number.isFinite(dim) && dim >= 0 && dim <= 1, `dim ${dim}`);
+    assert.equal(report.descriptor.version, 1);
+  });
+  it("sections the four-phase fixture in order", () => {
+    assert.ok(report.structure.sectionCount >= 2, `sections ${report.structure.sectionCount}`);
+    assert.ok(
+      report.structure.durationMs > 0 && Math.abs(report.structure.durationMs - report.source.durationMs) < 120,
+      `structure duration ${report.structure.durationMs} vs source ${report.source.durationMs}`,
+    );
+    assert.ok(["arch", "rise", "fall", "wave", "flat"].includes(report.structure.narrativeShape));
+  });
+  it("is deterministic apart from the timings", () => {
+    const again = analyzePcm(song, SAMPLE_RATE);
+    const strip = (r: typeof report): Omit<typeof r, "timings"> => {
+      const { timings: _timings, ...rest } = r;
+      return rest;
+    };
+    assert.deepEqual(strip(again), strip(report));
+  });
+  it("survives a json round trip with the same shape", () => {
+    const restored = JSON.parse(JSON.stringify(report));
+    assert.equal(restored.schemaVersion, 1);
+    assert.equal(restored.descriptor.vector.length, 32);
+    assert.equal(restored.structure.sectionCount, report.structure.sectionCount);
+  });
+});
+
+describe("wav path", () => {
+  const song = songFixture();
+  it("agrees with the pcm path modulo container quantization", () => {
+    const fromBytes = analyzeWavBytes(wavBytes(song, SAMPLE_RATE), { analysisSampleRate: 22050 });
+    const fromPcm = analyzePcm(song, SAMPLE_RATE, 1, { analysisSampleRate: 22050 });
+    // the wav container quantizes to 16 bits: each path stays bit-deterministic
+    // on its own input (covered by the determinism test), and across paths the
+    // stable stats agree — tempo within two bpm — while onset-sensitive dims
+    // (swing, regularity) may flip under the quantization staircase, so the
+    // whole vector only needs to stay close on average.
+    assert.ok(
+      Math.abs(fromBytes.rhythm.rawBpm - fromPcm.rhythm.rawBpm) < 2,
+      `bpm ${fromBytes.rhythm.rawBpm} vs ${fromPcm.rhythm.rawBpm}`,
+    );
+    let sum = 0;
+    for (let i = 0; i < fromPcm.descriptor.vector.length; i++)
+      sum += Math.abs(fromBytes.descriptor.vector[i] - fromPcm.descriptor.vector[i]);
+    const meanDiff = sum / fromPcm.descriptor.vector.length;
+    assert.ok(meanDiff < 0.15, `mean dim diff ${meanDiff.toFixed(4)} too high`);
+    assert.equal(fromBytes.source.kind, "wav");
+  });
+  it("round trips through the decode layer first", () => {
+    const bytes = wavBytes(song, SAMPLE_RATE);
+    const decoded = decodeWav(bytes, { targetSampleRate: 22050, mono: true });
+    assert.ok(decoded.length > 0);
+    assert.equal(decoded.channels, 1);
+  });
+});
+
+describe("error taxonomy", () => {
+  it("refuses an empty slice", () => {
+    assert.throws(
+      () => analyzePcm(new Float32Array(0), 48000),
+      (error: unknown) => error instanceof PipelineError && error.code === "pipeline-empty-samples",
+    );
+  });
+  it("refuses a slice shorter than one second", () => {
+    assert.throws(
+      () => analyzePcm(new Float32Array(22050 / 2), 22050),
+      (error: unknown) => error instanceof PipelineError && error.code === "pipeline-too-short",
+    );
+  });
+  it("refuses a non-finite sample rate", () => {
+    assert.throws(
+      () => analyzePcm(new Float32Array(48000), NaN),
+      (error: unknown) => error instanceof PipelineError && error.code === "pipeline-unsupported-sample-rate",
+    );
+  });
+  it("refuses empty wav bytes", () => {
+    assert.throws(
+      () => analyzeWavBytes(new Uint8Array(0)),
+      (error: unknown) => error instanceof PipelineError && error.code === "pipeline-empty-samples",
+    );
+  });
+});
+
+describe("report digest", () => {
+  it("names bpm, key, shape and seed in lowercase", () => {
+    const digest = reportDigest(analyzePcm(songFixture(), SAMPLE_RATE));
+    assert.match(digest, /bpm \d+/);
+    assert.match(digest, / (major|minor) /);
+    assert.match(digest, /seed [0-9a-f]+/);
+    assert.equal(digest, digest.toLowerCase());
+  });
+});

package/tests/audiorhythm.test.ts

@@ -0,0 +1,172 @@
+// # audiorhythm.test — deterministic unit tests for the cadria rhythm layer,
+// runnable with vitest:
+//   pnpm vitest run tests/audiorhythm.test.ts
+// Fixtures synthesize click tracks, swings and jitter straight into PCM —
+// no binary files, no randomness.
+
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { onsetEnvelope, onsetPeaks, rhythmStats } from "../audiorhythm.ts";
+import { canonicalTempo, RhythmError } from "../audiorhythmbeat.ts";
+
+/** builds a mono sine burst at hz for ms on a track at sampleRate. */
+function burst(
+  track: Float32Array,
+  sampleRate: number,
+  startMs: number,
+  durationMs: number,
+  hz: number,
+  gain = 0.8,
+): void {
+  const start = Math.round((startMs / 1000) * sampleRate);
+  const length = Math.round((durationMs / 1000) * sampleRate);
+  for (let i = 0; i < length && start + i < track.length; i++) {
+    track[start + i] += gain * Math.sin((2 * Math.PI * hz * i) / sampleRate);
+  }
+}
+
+/** synthesizes a click track: short 1200Hz bursts every `periodMs`. */
+function clickTrack(sampleRate: number, durationMs: number, periodMs: number, clickMs = 18): Float32Array {
+  const track = new Float32Array(Math.round((durationMs / 1000) * sampleRate));
+  for (let t = 0; t < durationMs; t += periodMs) burst(track, sampleRate, t, clickMs, 1200);
+  return track;
+}
+
+describe("onset envelope", () => {
+  const sampleRate = 22050;
+  it("answers zero flux for silence", () => {
+    const { envelope } = onsetEnvelope(new Float32Array(sampleRate * 2), sampleRate);
+    let max = 0;
+    for (const v of envelope) if (v > max) max = v;
+    assert.ok(max === 0, `silence flux must be 0, got ${max}`);
+  });
+  it("fires peaks on a click track and stays near zero between", () => {
+    const track = clickTrack(sampleRate, 4000, 500);
+    const { envelope, frameMs } = onsetEnvelope(track, sampleRate);
+    assert.ok(frameMs > 0);
+    let peaks = 0;
+    for (let i = 1; i < envelope.length - 1; i++)
+      if (envelope[i] > envelope[i - 1] && envelope[i] >= envelope[i + 1] && envelope[i] > 0.05) peaks++;
+    assert.ok(peaks >= 6, `expected at least 6 flux peaks for 7 clicks, got ${peaks}`);
+  });
+  it("keeps frameMs tied to the hop and sample rate", () => {
+    const { frameMs } = onsetEnvelope(clickTrack(sampleRate, 1000, 250), sampleRate, { size: 1024, hop: 256 });
+    assert.ok(Math.abs(frameMs - (256 / sampleRate) * 1000) < 1e-9);
+  });
+  it("throws RhythmError for a bad sample rate", () => {
+    assert.throws(() => onsetEnvelope(new Float32Array(1024), 0), RhythmError);
+  });
+  it("is deterministic", () => {
+    const track = clickTrack(sampleRate, 2000, 333);
+    const a = onsetEnvelope(track, sampleRate);
+    const b = onsetEnvelope(track, sampleRate);
+    assert.deepEqual([...b.envelope], [...a.envelope]);
+  });
+});
+
+describe("onset peaks", () => {
+  const sampleRate = 22050;
+  it("finds near-exact counts on an impulse track", () => {
+    const track = clickTrack(sampleRate, 4000, 500);
+    const { envelope, frameMs } = onsetEnvelope(track, sampleRate);
+    const onsets = onsetPeaks(envelope, frameMs);
+    // the t=0 click sits inside the first stft frame — spectral flux has no
+    // previous frame to diff against, so detection starts at the second click.
+    assert.ok(onsets.length >= 5 && onsets.length <= 7, `expected 5-7 onsets, got ${onsets.length}`);
+    assert.ok(Math.abs(onsets[0] - 500) < 80, `first detected onset near 500ms, got ${onsets[0]}`);
+  });
+  it("answers no peaks on silence", () => {
+    const { envelope, frameMs } = onsetEnvelope(new Float32Array(sampleRate), sampleRate);
+    assert.equal(onsetPeaks(envelope, frameMs).length, 0);
+  });
+  it("respects the minimum gap", () => {
+    const track = clickTrack(sampleRate, 2000, 90);
+    const { envelope, frameMs } = onsetEnvelope(track, sampleRate);
+    const onsets = onsetPeaks(envelope, frameMs, { minGapMs: 200 });
+    for (let i = 1; i < onsets.length; i++)
+      assert.ok(onsets[i] - onsets[i - 1] >= 200 - 1e-9, `gap ${onsets[i] - onsets[i - 1]} below minGapMs`);
+  });
+  it("returns ascending times", () => {
+    const track = clickTrack(sampleRate, 3000, 400);
+    const { envelope, frameMs } = onsetEnvelope(track, sampleRate);
+    const onsets = onsetPeaks(envelope, frameMs);
+    for (let i = 1; i < onsets.length; i++) assert.ok(onsets[i] > onsets[i - 1]);
+  });
+});
+
+describe("tempo estimate via stats", () => {
+  const sampleRate = 22050;
+  it("reads a 120 bpm click track at 118-122", () => {
+    const stats = rhythmStats(clickTrack(sampleRate, 8000, 500), sampleRate);
+    assert.ok(stats.rawBpm >= 118 && stats.rawBpm <= 122, `bpm ${stats.rawBpm} outside 118-122`);
+    assert.equal(stats.multiplier, 1);
+    assert.ok(stats.regularityIndex > 0.6, `regularity ${stats.regularityIndex} too low`);
+  });
+  it("canonicalizes 180 bpm into the 70-160 fold", () => {
+    const folded = canonicalTempo(180);
+    assert.equal(folded.bpm, 90);
+    assert.equal(folded.multiplier, 0.5);
+  });
+  it("reads a 90 bpm track near 90", () => {
+    const stats = rhythmStats(clickTrack(sampleRate, 8000, 666.6667), sampleRate);
+    assert.ok(stats.bpm >= 86 && stats.bpm <= 94, `bpm ${stats.bpm} outside 86-94`);
+  });
+  it("answers the zero band for silence without throwing", () => {
+    const stats = rhythmStats(new Float32Array(sampleRate * 3), sampleRate);
+    assert.equal(stats.bpm, 0);
+    assert.equal(stats.confidence, 0);
+    assert.equal(stats.onsetsPerSecond, 0);
+    assert.deepEqual(stats.swing, { ratio: 0.5, swung: false });
+  });
+  it("keeps regularity of a metronome above a jittered track", () => {
+    const clean = rhythmStats(clickTrack(sampleRate, 6000, 500), sampleRate);
+    const jittered = clickTrack(sampleRate, 6000, 500);
+    for (let t = 0, k = 0; t < 6000; t += 500, k++) {
+      const drift = (k % 2 === 0 ? 28 : -31) * (1 + (k % 3) / 4);
+      burst(jittered, sampleRate, Math.max(0, t + drift), 18, 1200, 0.5);
+    }
+    const rough = rhythmStats(jittered, sampleRate);
+    assert.ok(
+      clean.regularityIndex > rough.regularityIndex,
+      `clean ${clean.regularityIndex} must beat jitter ${rough.regularityIndex}`,
+    );
+  });
+  it("reports a swung track as swung", () => {
+    const sampleRate2 = 22050;
+    const track = new Float32Array(Math.round(4 * sampleRate2));
+    for (let beat = 0; beat < 8; beat++) {
+      const base = beat * 500;
+      burst(track, sampleRate2, base, 15, 1200);
+      burst(track, sampleRate2, base + 340, 12, 900, 0.5);
+    }
+    const stats = rhythmStats(track, sampleRate2);
+    assert.ok(stats.swing.ratio > 0.58, `ratio ${stats.swing.ratio} below the swing threshold`);
+    assert.equal(stats.swing.swung, true);
+  });
+});
+
+describe("stats hygiene", () => {
+  const sampleRate = 22050;
+  it("is deterministic end to end", () => {
+    const track = clickTrack(sampleRate, 5000, 428.57);
+    assert.deepEqual(rhythmStats(track, sampleRate), rhythmStats(track, sampleRate));
+  });
+  it("carries only finite numbers", () => {
+    const stats = rhythmStats(clickTrack(sampleRate, 4000, 500), sampleRate);
+    const walk = (value: unknown): void => {
+      if (typeof value === "number") assert.ok(Number.isFinite(value), `non-finite ${value}`);
+      else if (value !== null && typeof value === "object") for (const child of Object.values(value)) walk(child);
+    };
+    walk(stats);
+  });
+  it("clamps onsetsPerSecond to a sane band", () => {
+    const stats = rhythmStats(clickTrack(sampleRate, 4000, 500), sampleRate);
+    assert.ok(
+      stats.onsetsPerSecond > 0 && stats.onsetsPerSecond < 20,
+      `onsets/s ${stats.onsetsPerSecond} outside sanity`,
+    );
+  });
+  it("throws for a non-finite sample rate", () => {
+    assert.throws(() => rhythmStats(new Float32Array(1024), NaN), RhythmError);
+  });
+});