@kuralle-syrinx/core 4.4.0 → 4.5.0

package/src/audio/audio.test.ts

@@ -0,0 +1,285 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { pcm16BytesToSamples, pcm16SamplesToBytes, bigEndianPcm16BytesToSamples, pcm16SamplesToBigEndianBytes } from "./pcm.js";
+import { decodeMuLawToPcm16, encodePcm16ToMuLaw } from "./mulaw.js";
+import { resamplePcm16, StreamingPcm16Resampler } from "./resample.js";
+
+// ── PCM byte ↔ sample conversions ──────────────────────────────────────────
+
+describe("pcm16BytesToSamples (little-endian)", () => {
+  it("decodes a known LE byte sequence", () => {
+    // [0x01, 0x00] = 1 in LE;  [0xFF, 0x7F] = 32767;  [0x00, 0x80] = -32768
+    const bytes = new Uint8Array([0x01, 0x00, 0xff, 0x7f, 0x00, 0x80]);
+    const samples = pcm16BytesToSamples(bytes);
+    expect(samples[0]).toBe(1);
+    expect(samples[1]).toBe(32767);
+    expect(samples[2]).toBe(-32768);
+  });
+
+  it("throws on odd byte length", () => {
+    expect(() => pcm16BytesToSamples(new Uint8Array(3))).toThrow(/even/);
+  });
+
+  it("round-trips through pcm16SamplesToBytes", () => {
+    const original = new Int16Array([0, 1, -1, 32767, -32768, 1000, -1000]);
+    const bytes = pcm16SamplesToBytes(original);
+    const recovered = pcm16BytesToSamples(bytes);
+    expect(Array.from(recovered)).toEqual(Array.from(original));
+  });
+});
+
+describe("pcm16SamplesToBytes (little-endian)", () => {
+  it("encodes a known sample sequence to LE bytes", () => {
+    const samples = new Int16Array([1, 32767, -32768]);
+    const bytes = pcm16SamplesToBytes(samples);
+    expect(bytes[0]).toBe(0x01);
+    expect(bytes[1]).toBe(0x00);
+    expect(bytes[2]).toBe(0xff);
+    expect(bytes[3]).toBe(0x7f);
+    expect(bytes[4]).toBe(0x00);
+    expect(bytes[5]).toBe(0x80);
+  });
+});
+
+describe("bigEndianPcm16BytesToSamples", () => {
+  it("decodes a known BE byte sequence", () => {
+    // BE: [0x00, 0x01] = 1;  [0x7F, 0xFF] = 32767;  [0x80, 0x00] = -32768
+    const bytes = new Uint8Array([0x00, 0x01, 0x7f, 0xff, 0x80, 0x00]);
+    const samples = bigEndianPcm16BytesToSamples(bytes);
+    expect(samples[0]).toBe(1);
+    expect(samples[1]).toBe(32767);
+    expect(samples[2]).toBe(-32768);
+  });
+
+  it("throws on odd byte length", () => {
+    expect(() => bigEndianPcm16BytesToSamples(new Uint8Array(3))).toThrow(/even/);
+  });
+
+  it("round-trips through pcm16SamplesToBigEndianBytes", () => {
+    const original = new Int16Array([0, 1, -1, 32767, -32768, 1000]);
+    const bytes = pcm16SamplesToBigEndianBytes(original);
+    const recovered = bigEndianPcm16BytesToSamples(bytes);
+    expect(Array.from(recovered)).toEqual(Array.from(original));
+  });
+});
+
+describe("LE vs BE byte order", () => {
+  it("produces distinct byte sequences for the same samples", () => {
+    const samples = new Int16Array([256]); // LE: [0x00, 0x01], BE: [0x01, 0x00]
+    const le = pcm16SamplesToBytes(samples);
+    const be = pcm16SamplesToBigEndianBytes(samples);
+    expect(le[0]).not.toBe(be[0]);
+  });
+
+  it("LE bytes decoded as BE yield wrong values and vice versa", () => {
+    const samples = new Int16Array([1000, -500]);
+    const leBytes = pcm16SamplesToBytes(samples);
+    const beBytes = pcm16SamplesToBigEndianBytes(samples);
+    // Cross-decode: LE bytes read as BE should NOT equal original
+    const mismatch = bigEndianPcm16BytesToSamples(leBytes);
+    expect(mismatch[0]).not.toBe(1000);
+    // BE bytes read as LE should NOT equal original
+    const mismatch2 = pcm16BytesToSamples(beBytes);
+    expect(mismatch2[0]).not.toBe(1000);
+  });
+});
+
+// ── μ-law codec ─────────────────────────────────────────────────────────────
+
+describe("μ-law round-trip", () => {
+  it("round-trips silence exactly", () => {
+    const silence = new Int16Array(160);
+    const encoded = encodePcm16ToMuLaw(silence);
+    const decoded = decodeMuLawToPcm16(encoded);
+    for (let i = 0; i < decoded.length; i += 1) {
+      // silence encodes to the mid-code and decodes back to near-zero
+      expect(Math.abs(decoded[i]!)).toBeLessThanOrEqual(8);
+    }
+  });
+
+  it("round-trips a sine wave within μ-law quantization tolerance", () => {
+    const N = 160;
+    const input = new Int16Array(N);
+    for (let i = 0; i < N; i += 1) {
+      input[i] = Math.round(16000 * Math.sin((2 * Math.PI * 1000 * i) / 8000));
+    }
+    const encoded = encodePcm16ToMuLaw(input);
+    expect(encoded.length).toBe(N);
+    const decoded = decodeMuLawToPcm16(encoded);
+    // μ-law is lossy; allow ≤5% full-scale error (~1638 counts)
+    for (let i = 0; i < N; i += 1) {
+      expect(Math.abs(decoded[i]! - input[i]!)).toBeLessThanOrEqual(1638);
+    }
+  });
+
+  it("preserves sign correctly", () => {
+    const positive = new Int16Array([10000]);
+    const negative = new Int16Array([-10000]);
+    const decPos = decodeMuLawToPcm16(encodePcm16ToMuLaw(positive));
+    const decNeg = decodeMuLawToPcm16(encodePcm16ToMuLaw(negative));
+    expect(decPos[0]).toBeGreaterThan(0);
+    expect(decNeg[0]).toBeLessThan(0);
+  });
+});
+
+// ── Resampler ───────────────────────────────────────────────────────────────
+
+describe("resamplePcm16 — identity and length", () => {
+  it("returns the same reference when rates are equal", () => {
+    const input = new Int16Array([100, 200, 300]);
+    const output = resamplePcm16(input, 16000, 16000);
+    expect(output).toBe(input);
+  });
+
+  it("returns empty array for empty input", () => {
+    const output = resamplePcm16(new Int16Array(0), 16000, 8000);
+    expect(output.length).toBe(0);
+  });
+
+  it("produces correct output length for 2× upsample", () => {
+    const input = new Int16Array(80);
+    const output = resamplePcm16(input, 8000, 16000);
+    expect(output.length).toBe(160);
+  });
+
+  it("produces correct output length for 2× downsample", () => {
+    const input = new Int16Array(160);
+    const output = resamplePcm16(input, 16000, 8000);
+    expect(output.length).toBe(80);
+  });
+
+  it("produces correct output length for 3× downsample", () => {
+    const input = new Int16Array(240);
+    const output = resamplePcm16(input, 24000, 8000);
+    expect(output.length).toBe(80);
+  });
+
+  it("produces correct output length for 48k→16k (3× downsample)", () => {
+    const input = new Int16Array(480);
+    const output = resamplePcm16(input, 48000, 16000);
+    expect(output.length).toBe(160);
+  });
+});
+
+describe("resamplePcm16 — upsample fidelity", () => {
+  it("preserves a DC signal on upsample", () => {
+    // A constant signal should remain constant after upsampling.
+    const dc = 10000;
+    const input = new Int16Array(80).fill(dc);
+    const output = resamplePcm16(input, 8000, 16000);
+    for (let i = 0; i < output.length; i += 1) {
+      expect(output[i]).toBe(dc);
+    }
+  });
+});
+
+describe("resamplePcm16 — downsample fidelity", () => {
+  it("preserves a DC signal on downsample in the interior (no boundary effects)", () => {
+    // Use 640 input samples (40 ms @ 16 kHz) → 320 output samples @ 8 kHz.
+    // With a 127-tap centered FIR (halfTaps=63), both sides of the filter are
+    // fully populated for output indices m where:
+    //   n0 - halfTaps >= 0  → n0 >= 63 → m >= 32
+    //   n0 + halfTaps < 640 → n0 < 577 → m <= 288
+    // Check m=40..280 to leave a comfortable margin on both ends.
+    const dc = 10000;
+    const input = new Int16Array(640).fill(dc);
+    const output = resamplePcm16(input, 16000, 8000);
+    expect(output.length).toBe(320);
+    for (let i = 40; i <= 280; i += 1) {
+      expect(Math.abs(output[i]! - dc)).toBeLessThanOrEqual(10);
+    }
+  });
+});
+
+// ── Anti-alias spectral test (F3 regression lock) ───────────────────────────
+//
+// Strategy: synthesize a 7 kHz tone at 16 kHz. When decimated to 8 kHz without
+// a low-pass filter, 7 kHz aliases to 1 kHz (8000 − 7000). Compare the DFT
+// magnitude at 1 kHz between the naive linear-interp baseline and the
+// anti-aliased output. The spec requires ≥40 dB suppression of the alias.
+
+function dftMagnitudeAtBin(samples: Int16Array, binIndex: number): number {
+  // Compute a single DFT bin via direct evaluation (O(N)).
+  let re = 0;
+  let im = 0;
+  const N = samples.length;
+  for (let n = 0; n < N; n += 1) {
+    const angle = (2 * Math.PI * binIndex * n) / N;
+    re += samples[n]! * Math.cos(angle);
+    im -= samples[n]! * Math.sin(angle);
+  }
+  return Math.sqrt(re * re + im * im);
+}
+
+function naiveDecimate16kTo8k(input: Int16Array): Int16Array {
+  // Pure linear interpolation decimation — the pre-existing buggy baseline.
+  const outputLength = Math.max(1, Math.round((input.length * 8000) / 16000));
+  const output = new Int16Array(outputLength);
+  const ratio = 2.0;
+  for (let i = 0; i < outputLength; i += 1) {
+    const pos = i * ratio;
+    const lo = Math.floor(pos);
+    const hi = Math.min(input.length - 1, lo + 1);
+    const frac = pos - lo;
+    output[i] = Math.round(input[lo]! * (1 - frac) + input[hi]! * frac);
+  }
+  return output;
+}
+
+describe("StreamingPcm16Resampler — chunk continuity", () => {
+  it("preserves constant-amplitude PCM across successive 20ms chunks (stateless path rings)", () => {
+    const chunkSamples = 320;
+    const value = 10_000;
+    const chunks = 10;
+    const stateful = new StreamingPcm16Resampler(16_000, 8_000);
+
+    for (let i = 0; i < chunks; i += 1) {
+      const chunk = new Int16Array(chunkSamples).fill(value);
+      const statefulOut = stateful.process(chunk);
+      const statelessOut = resamplePcm16(chunk, 16_000, 8_000);
+      if (i === 0) continue;
+
+      const statefulSwing = Math.max(...statefulOut) - Math.min(...statefulOut);
+      expect(statefulSwing).toBeLessThan(700);
+
+      const statelessSwing = Math.max(...statelessOut) - Math.min(...statelessOut);
+      expect(statelessSwing).toBeGreaterThan(3000);
+      expect(Math.min(...statelessOut)).toBeLessThan(8000);
+      expect(Math.max(...statelessOut)).toBeGreaterThan(10_000);
+    }
+  });
+});
+
+describe("resamplePcm16 — anti-alias spectral test (F3)", () => {
+  it("attenuates 7 kHz alias by ≥40 dB compared to naive linear-interp", () => {
+    // 100 ms of 7 kHz tone at 16 kHz (amplitude 20000).
+    const N_IN = 1600;
+    const AMPLITUDE = 20000;
+    const FREQ_HZ = 7000;
+    const SRC_RATE = 16000;
+    const DST_RATE = 8000;
+
+    const input = new Int16Array(N_IN);
+    for (let n = 0; n < N_IN; n += 1) {
+      input[n] = Math.round(AMPLITUDE * Math.sin((2 * Math.PI * FREQ_HZ * n) / SRC_RATE));
+    }
+
+    const naiveOutput = naiveDecimate16kTo8k(input);
+    const aaOutput = resamplePcm16(input, SRC_RATE, DST_RATE);
+
+    // 7 kHz aliases to 1 kHz (8000 - 7000) in the 8 kHz output.
+    // DFT bin for 1 kHz with 800 output samples at 8 kHz: bin = 800 * 1000/8000 = 100.
+    const aliasBin = Math.round((naiveOutput.length * 1000) / DST_RATE);
+
+    const naiveMag = dftMagnitudeAtBin(naiveOutput, aliasBin);
+    const aaMag = dftMagnitudeAtBin(aaOutput, aliasBin);
+
+    // Guard: naive must actually have a strong alias (sanity-check the test itself).
+    expect(naiveMag).toBeGreaterThan(AMPLITUDE * 100); // should be ~amplitude*N/2
+
+    // Anti-aliased output alias must be ≥40 dB below the naive alias.
+    const ratioDb = 20 * Math.log10(naiveMag / Math.max(1, aaMag));
+    expect(ratioDb).toBeGreaterThanOrEqual(40);
+  });
+});

package/src/audio/g722.test.ts

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+//
+// G.722 tests — round-trip SNR + known-answer smoke.
+// NOT ITU-vector-certified (no embedded ITU G.722 Appendix test vectors).
+
+import { describe, expect, it } from "vitest";
+import {
+  createG722DecoderState,
+  createG722EncoderState,
+  decodeG722,
+  encodeG722,
+  G722_SAMPLE_RATE_HZ,
+} from "./g722.js";
+
+/**
+ * SNR with QMF group-delay alignment: recovered lags original by `delay` samples
+ * (recovered[i + delay] ≈ original[i]).
+ */
+function snrDb(original: Int16Array, recovered: Int16Array, delay = 0): number {
+  let signal = 0;
+  let noise = 0;
+  const start = 320;
+  const end = Math.min(original.length, recovered.length - delay) - 8;
+  for (let i = start; i < end; i += 1) {
+    const o = original[i]!;
+    const r = recovered[i + delay]!;
+    const e = o - r;
+    signal += o * o;
+    noise += e * e;
+  }
+  if (noise === 0) return Infinity;
+  if (signal === 0) return 0;
+  return 10 * Math.log10(signal / noise);
+}
+
+/** Empirical QMF analysis+synthesis group delay for this implementation (samples). */
+const QMF_GROUP_DELAY = 22;
+
+function sine(hz: number, seconds: number, amp = 8000): Int16Array {
+  const n = Math.round(G722_SAMPLE_RATE_HZ * seconds);
+  // even length for clean pairing
+  const len = n & ~1;
+  const out = new Int16Array(len);
+  for (let i = 0; i < len; i += 1) {
+    out[i] = Math.round(amp * Math.sin((2 * Math.PI * hz * i) / G722_SAMPLE_RATE_HZ));
+  }
+  return out;
+}
+
+describe("G.722 API shape", () => {
+  it("exports sample rate constant 16000", () => {
+    expect(G722_SAMPLE_RATE_HZ).toBe(16_000);
+  });
+
+  it("encoder produces half the sample count in bytes", () => {
+    const enc = createG722EncoderState();
+    const pcm = new Int16Array(320); // 20 ms @ 16 kHz
+    const bytes = encodeG722(enc, pcm);
+    expect(bytes.length).toBe(160);
+  });
+
+  it("decoder produces 2 samples per G.722 byte", () => {
+    const enc = createG722EncoderState();
+    const dec = createG722DecoderState();
+    const pcm = sine(1000, 0.02);
+    const bytes = encodeG722(enc, pcm);
+    const out = decodeG722(dec, bytes);
+    expect(out.length).toBe(bytes.length * 2);
+  });
+
+  it("holds an odd trailing sample for the next encode call", () => {
+    const enc = createG722EncoderState();
+    const a = encodeG722(enc, new Int16Array([100, 200, 300]));
+    expect(a.length).toBe(1); // one pair; 300 pending
+    const b = encodeG722(enc, new Int16Array([400]));
+    expect(b.length).toBe(1); // pending 300 + 400
+  });
+});
+
+describe("G.722 round-trip (spec-implemented, NOT ITU-vector-certified)", () => {
+  it("round-trips silence near zero after QMF settle", () => {
+    const enc = createG722EncoderState();
+    const dec = createG722DecoderState();
+    // Warm-up: QMF needs history before settling
+    const warm = new Int16Array(480);
+    decodeG722(dec, encodeG722(enc, warm));
+    const silence = new Int16Array(320);
+    const recovered = decodeG722(dec, encodeG722(enc, silence));
+    for (let i = 0; i < recovered.length; i += 1) {
+      expect(Math.abs(recovered[i]!)).toBeLessThanOrEqual(64);
+    }
+  });
+
+  it("round-trips 1 kHz tone with SNR ≥ 20 dB (after settle + QMF delay)", () => {
+    const enc = createG722EncoderState();
+    const dec = createG722DecoderState();
+    const pcm = sine(1000, 0.25, 10000);
+    const recovered = decodeG722(dec, encodeG722(enc, pcm));
+    const snr = snrDb(pcm, recovered, QMF_GROUP_DELAY);
+    expect(snr).toBeGreaterThanOrEqual(20);
+  });
+
+  it("round-trips multi-tone speech-like signal with SNR ≥ 18 dB", () => {
+    const enc = createG722EncoderState();
+    const dec = createG722DecoderState();
+    const n = 1600; // 100 ms
+    const pcm = new Int16Array(n);
+    for (let i = 0; i < n; i += 1) {
+      const t = i / G722_SAMPLE_RATE_HZ;
+      pcm[i] = Math.round(
+        6000 * Math.sin(2 * Math.PI * 300 * t) +
+          4000 * Math.sin(2 * Math.PI * 900 * t) +
+          2500 * Math.sin(2 * Math.PI * 1800 * t) +
+          1500 * Math.sin(2 * Math.PI * 3200 * t),
+      );
+    }
+    const recovered = decodeG722(dec, encodeG722(enc, pcm));
+    const snr = snrDb(pcm, recovered, QMF_GROUP_DELAY);
+    expect(snr).toBeGreaterThanOrEqual(18);
+  });
+
+  it("preserves sign of a positive then negative burst (aligned by QMF delay)", () => {
+    const enc = createG722EncoderState();
+    const dec = createG722DecoderState();
+    decodeG722(dec, encodeG722(enc, new Int16Array(640)));
+    const pos = new Int16Array(320).fill(8000);
+    const neg = new Int16Array(320).fill(-8000);
+    const rPos = decodeG722(dec, encodeG722(enc, pos));
+    const rNeg = decodeG722(dec, encodeG722(enc, neg));
+    // recovered[i + delay] ≈ input[i]; probe mid-burst after delay
+    const mid = 160;
+    expect(rPos[mid + QMF_GROUP_DELAY]!).toBeGreaterThan(0);
+    expect(rNeg[mid + QMF_GROUP_DELAY]!).toBeLessThan(0);
+  });
+
+  it("known-answer: encoder is deterministic for a fixed impulse train", () => {
+    const enc = createG722EncoderState();
+    const pcm = new Int16Array(64);
+    pcm[0] = 10000;
+    pcm[1] = -10000;
+    pcm[16] = 5000;
+    const a = encodeG722(enc, pcm);
+    const enc2 = createG722EncoderState();
+    const b = encodeG722(enc2, pcm);
+    expect(Array.from(a)).toEqual(Array.from(b));
+    // non-trivial: not all zeros after impulse
+    expect(a.some((v) => v !== 0)).toBe(true);
+  });
+});

package/src/audio/loudness.test.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { createLoudnessState, normalizeLoudness, type LoudnessConfig } from "./loudness.js";
+
+function rms(pcm: Int16Array): number {
+  let sumSquares = 0;
+  for (const sample of pcm) sumSquares += sample * sample;
+  return Math.sqrt(sumSquares / pcm.length);
+}
+
+function constantPcm(value: number, length = 320): Int16Array {
+  return new Int16Array(length).fill(value);
+}
+
+describe("normalizeLoudness", () => {
+  it("raises quiet PCM and lowers loud PCM toward the target", () => {
+    const config: LoudnessConfig = { targetRms: 8000 };
+    const quiet = normalizeLoudness(constantPcm(1000), createLoudnessState(), config);
+    const loud = normalizeLoudness(constantPcm(24000), createLoudnessState(), config);
+
+    expect(rms(quiet)).toBeGreaterThan(1000);
+    expect(rms(loud)).toBeLessThan(24000);
+    expect(Math.max(...quiet)).toBeLessThanOrEqual(32767);
+    expect(Math.min(...quiet)).toBeGreaterThanOrEqual(-32768);
+    expect(Math.max(...loud)).toBeLessThanOrEqual(32767);
+    expect(Math.min(...loud)).toBeGreaterThanOrEqual(-32768);
+  });
+
+  it("converges different input levels into the same output band", () => {
+    const config: LoudnessConfig = { targetRms: 8000 };
+    const quietState = createLoudnessState();
+    const loudState = createLoudnessState();
+    let quietRms = 0;
+    let loudRms = 0;
+
+    for (let i = 0; i < 12; i += 1) {
+      quietRms = rms(normalizeLoudness(constantPcm(2000), quietState, config));
+      loudRms = rms(normalizeLoudness(constantPcm(24000), loudState, config));
+    }
+
+    expect(Math.abs(quietRms - loudRms)).toBeLessThanOrEqual(100);
+    expect(Math.abs(quietRms - config.targetRms)).toBeLessThanOrEqual(100);
+  });
+
+  it("uses a soft ceiling for full-scale input without clipping or wrapping", () => {
+    const output = normalizeLoudness(
+      new Int16Array([32767, -32768, 32767, -32768]),
+      createLoudnessState(),
+      { targetRms: 32767 },
+    );
+
+    expect(Math.max(...output)).toBeLessThan(32767);
+    expect(Math.min(...output)).toBeGreaterThan(-32768);
+    expect(Math.max(...output)).toBeGreaterThan(0);
+    expect(Math.min(...output)).toBeLessThan(0);
+  });
+});

package/src/audio-envelope.test.ts

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import {
+  SYRINX_AUDIO_ENVELOPE_MAGIC,
+  assertAudioFormat,
+  assertAudioPayload,
+  decodeSyrinxAudioEnvelope,
+  encodeSyrinxAudioEnvelope,
+  hasSyrinxAudioEnvelope,
+} from "./audio-envelope.js";
+import type { SyrinxAudioEnvelopeHeader } from "./audio-envelope.js";
+import type { AudioFormat } from "./packets.js";
+
+describe("Syrinx binary audio envelope", () => {
+  it("round-trips audio metadata and payload", () => {
+    const encoded = encodeSyrinxAudioEnvelope({
+      type: "audio",
+      contextId: "turn-1",
+      sampleRateHz: 16000,
+      sequence: 3,
+      encoding: "pcm_s16le",
+      channels: 1,
+      byteLength: 4,
+      durationMs: 1,
+    }, new Uint8Array([1, 2, 3, 4]));
+
+    expect(hasSyrinxAudioEnvelope(encoded)).toBe(true);
+    expect(decodeSyrinxAudioEnvelope(encoded)).toEqual({
+      header: {
+        type: "audio",
+        contextId: "turn-1",
+        sampleRateHz: 16000,
+        sequence: 3,
+        encoding: "pcm_s16le",
+        channels: 1,
+        byteLength: 4,
+        durationMs: 1,
+      },
+      audio: new Uint8Array([1, 2, 3, 4]),
+    });
+  });
+
+  it("rejects envelopes whose declared byte length does not match the payload", () => {
+    const encoded = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      byteLength: 5,
+    }, new Uint8Array([1, 2, 3, 4]));
+
+    expect(() => decodeSyrinxAudioEnvelope(encoded)).toThrow(/byteLength/);
+  });
+
+  it("rejects odd-byte PCM16 payloads and inconsistent duration metadata", () => {
+    const oddPayload = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      byteLength: 3,
+    }, new Uint8Array([1, 2, 3]));
+    const wrongDuration = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      byteLength: 640,
+      durationMs: 200,
+    }, new Uint8Array(640));
+
+    expect(() => decodeSyrinxAudioEnvelope(oddPayload)).toThrow(/PCM16/);
+    expect(() => decodeSyrinxAudioEnvelope(wrongDuration)).toThrow(/durationMs/);
+  });
+
+  it("rejects envelopes without a valid sample rate", () => {
+    const missingSampleRate = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      byteLength: 4,
+    }, new Uint8Array([1, 2, 3, 4]));
+    const invalidSampleRate = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 0,
+      byteLength: 4,
+    }, new Uint8Array([1, 2, 3, 4]));
+
+    expect(() => decodeSyrinxAudioEnvelope(missingSampleRate)).toThrow(/sampleRateHz/);
+    expect(() => decodeSyrinxAudioEnvelope(invalidSampleRate)).toThrow(/sampleRateHz/);
+  });
+
+  it("rejects malformed numeric metadata instead of silently defaulting", () => {
+    const invalidSequence = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      sequence: -1,
+      byteLength: 4,
+    }, new Uint8Array([1, 2, 3, 4]));
+    const invalidDuration = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      durationMs: 1.5,
+      byteLength: 4,
+    }, new Uint8Array([1, 2, 3, 4]));
+
+    expect(() => decodeSyrinxAudioEnvelope(invalidSequence)).toThrow(/sequence/);
+    expect(() => decodeSyrinxAudioEnvelope(invalidDuration)).toThrow(/durationMs/);
+  });
+
+  it("round-trips opus-encoded envelopes without PCM16 byte alignment", () => {
+    const encoded = encodeSyrinxAudioEnvelope({
+      type: "audio",
+      contextId: "turn-opus",
+      sampleRateHz: 16000,
+      sequence: 1,
+      encoding: "opus",
+      channels: 1,
+      byteLength: 37,
+      durationMs: 20,
+    }, new Uint8Array(37));
+
+    expect(decodeSyrinxAudioEnvelope(encoded).header.encoding).toBe("opus");
+  });
+
+  it("assertAudioPayload rejects odd-byte PCM16 and empty opus/mulaw", () => {
+    const pcmFormat: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: 16000, channels: 1 };
+    expect(() => assertAudioPayload(pcmFormat, new Uint8Array([1, 2, 3]))).toThrow(/even number of bytes/);
+    expect(() => assertAudioPayload(pcmFormat, new Uint8Array())).not.toThrow();
+
+    const opusFormat: AudioFormat = { encoding: "opus", sampleRateHz: 16000, channels: 1 };
+    expect(() => assertAudioPayload(opusFormat, new Uint8Array())).toThrow(/must not be empty/);
+    expect(() => assertAudioPayload(opusFormat, new Uint8Array([1]))).not.toThrow();
+
+    const mulawFormat: AudioFormat = { encoding: "mulaw", sampleRateHz: 8000, channels: 1 };
+    expect(() => assertAudioPayload(mulawFormat, new Uint8Array())).toThrow(/must not be empty/);
+    expect(() => assertAudioPayload(mulawFormat, new Uint8Array([1, 2, 3]))).not.toThrow();
+  });
+
+  it("assertAudioFormat rejects non-mono and invalid sample rates", () => {
+    expect(() => assertAudioFormat({ encoding: "pcm_s16le", sampleRateHz: 16000, channels: 2 as 1 })).toThrow(/mono/);
+    expect(() => assertAudioFormat({ encoding: "pcm_s16le", sampleRateHz: 0, channels: 1 })).toThrow(/sampleRateHz/);
+    expect(() => assertAudioFormat({ encoding: "pcm_s16le", sampleRateHz: 1.5, channels: 1 })).toThrow(/sampleRateHz/);
+  });
+
+  it("rejects invalid envelopes before encoding them", () => {
+    expect(() => encodeSyrinxAudioEnvelope({
+      type: "audio",
+      byteLength: 4,
+    } as SyrinxAudioEnvelopeHeader, new Uint8Array([1, 2, 3, 4]))).toThrow(/sampleRateHz/);
+    expect(() => encodeSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      sequence: -1,
+      byteLength: 4,
+    }, new Uint8Array([1, 2, 3, 4]))).toThrow(/sequence/);
+    expect(() => encodeSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      byteLength: 5,
+    }, new Uint8Array([1, 2, 3, 4]))).toThrow(/byteLength/);
+  });
+});
+
+function encodeMalformedSyrinxAudioEnvelope(header: Record<string, unknown>, audio: Uint8Array): Uint8Array {
+  const headerBytes = new TextEncoder().encode(JSON.stringify(header));
+  const output = new Uint8Array(SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength + 4 + headerBytes.byteLength + audio.byteLength);
+  output.set(SYRINX_AUDIO_ENVELOPE_MAGIC, 0);
+  new DataView(output.buffer, output.byteOffset, output.byteLength)
+    .setUint32(SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength, headerBytes.byteLength, true);
+  output.set(headerBytes, SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength + 4);
+  output.set(audio, SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength + 4 + headerBytes.byteLength);
+  return output;
+}

package/src/confidence-to-wait.test.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+
+import { confidenceToWaitMs } from "./confidence-to-wait.js";
+
+describe("confidenceToWaitMs", () => {
+  it("maps high confidence to 150ms and low confidence to 2000ms", () => {
+    expect(confidenceToWaitMs(1)).toBe(150);
+    expect(confidenceToWaitMs(0)).toBe(2000);
+    expect(confidenceToWaitMs(2)).toBe(150);
+    expect(confidenceToWaitMs(-1)).toBe(2000);
+  });
+
+  it("is monotonic and supports a bounded custom range", () => {
+    const waits = [0, 0.25, 0.5, 0.75, 1].map((confidence) => confidenceToWaitMs(confidence));
+    expect(waits).toEqual([...waits].sort((a, b) => b - a));
+    expect(confidenceToWaitMs(0.5, { minWaitMs: 100, maxWaitMs: 1100 })).toBe(600);
+    expect(() => confidenceToWaitMs(0.5, { minWaitMs: 500, maxWaitMs: 100 })).toThrow(/must be >=/);
+  });
+});