@kuralle-syrinx/core 2.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @kuralle-syrinx/core
+
+The Syrinx Kernel v2 — the framework-agnostic core of the voice engine: the `PipelineBus`, the `VoicePlugin` contract, the packet vocabulary (`stt.*` / `llm.*` / `tts.*` / `reasoning.*` …), turn-taking, observability, and the latency-hiding/barge-in primitives. STT/TTS/bridge/transport packages plug into this bus.
+
+This README documents the **`Reasoner` seam** added for the Reasoner-bridge generalization; the rest of the kernel surface is in `src/index.ts`.
+
+## The Reasoner seam
+
+A normalized pull-stream that lets one bridge ([`ReasoningBridge`](../aisdk/README.md)) drive **any** reasoning backend (Vercel AI SDK `ToolLoopAgent`/`streamText`, Mastra `Agent`, …) without changing the pipeline primitive. Defined in `src/reasoner.ts`:
+
+```ts
+export interface Reasoner {
+  // Drive one turn. The returned async-iterable IS the response.
+  // LATENCY INVARIANT: yield every part the instant the backend produces it —
+  // no buffering, no awaiting to completion, no batching.
+  stream(turn: ReasonerTurn): AsyncIterable<ReasoningPart>;
+}
+
+export interface ReasonerTurn {
+  readonly userText: string;                       // finalized transcript (from eos.turn_complete)
+  readonly messages: readonly ReasonerMessage[];   // prior context — the BRIDGE owns history
+  readonly signal: AbortSignal;                    // barge-in / supersede
+  readonly resume?: { readonly runId: string; readonly data: unknown };  // suspend/resume only
+}
+
+export type ReasoningPart =
+  | { type: "text-delta"; text: string }
+  | { type: "tool-call"; toolId: string; toolName: string; args: Record<string, unknown> }
+  | { type: "tool-result"; toolId: string; toolName: string; result: string }
+  | { type: "suspended"; runId: string; toolId?: string; prompt?: string; payload: unknown }  // terminal (HITL)
+  | { type: "error"; cause: Error; recoverable: boolean }                                       // terminal (→ retry)
+  | { type: "finish"; reason: "stop" | "tool" | "length"; text: string };
+```
+
+Frameworks become a `Reasoner` via **named adapters** (never auto-wrap / duck-typing):
+- AI SDK → `fromAiSdkAgent` / `fromStreamText` / `fromStreamFactory` (`@kuralle-syrinx/aisdk`)
+- Mastra → `fromMastraAgent` (`@kuralle-syrinx/mastra`)
+
+The bridge (a `VoicePlugin`) consumes the seam and pushes `llm.*` packets; the seam adds at most one microtask + a synchronous object remap per part. History, spoken-prefix barge-in, retry, and turn-superseding all stay in the bridge — the backend is stateless-per-turn.
+
+See `docs/rfc-reasoner-bridge.md` for the full design.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@kuralle-syrinx/core",
+  "version": "2.1.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./audio": "./src/audio/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.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/index.ts

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: MIT
+
+export { pcm16BytesToSamples, pcm16SamplesToBytes, bigEndianPcm16BytesToSamples, pcm16SamplesToBigEndianBytes } from "./pcm.js";
+export { decodeMuLawToPcm16, encodePcm16ToMuLaw } from "./mulaw.js";
+export { resamplePcm16, resamplePcm16Streaming, StreamingPcm16Resampler } from "./resample.js";

package/src/audio/mulaw.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: MIT
+
+const MULAW_BIAS = 0x84;
+const MULAW_CLIP = 32635;
+
+export function decodeMuLawToPcm16(input: Uint8Array): Int16Array {
+  const output = new Int16Array(input.byteLength);
+  for (let i = 0; i < input.byteLength; i += 1) {
+    const ulaw = (~input[i]!) & 0xff;
+    const sign = ulaw & 0x80;
+    const exponent = (ulaw >> 4) & 0x07;
+    const mantissa = ulaw & 0x0f;
+    let sample = ((mantissa << 3) + MULAW_BIAS) << exponent;
+    sample -= MULAW_BIAS;
+    output[i] = sign ? -sample : sample;
+  }
+  return output;
+}
+
+export function encodePcm16ToMuLaw(input: Int16Array): Uint8Array {
+  const output = new Uint8Array(input.length);
+  for (let i = 0; i < input.length; i += 1) {
+    output[i] = encodeSample(input[i]!);
+  }
+  return output;
+}
+
+function encodeSample(sample: number): number {
+  let sign = 0;
+  let magnitude = sample;
+  if (magnitude < 0) {
+    sign = 0x80;
+    magnitude = -magnitude;
+  }
+  magnitude = Math.min(magnitude, MULAW_CLIP) + MULAW_BIAS;
+  let exponent = 7;
+  for (let mask = 0x4000; (magnitude & mask) === 0 && exponent > 0; mask >>= 1) {
+    exponent -= 1;
+  }
+  const mantissa = (magnitude >> (exponent + 3)) & 0x0f;
+  return (~(sign | (exponent << 4) | mantissa)) & 0xff;
+}

package/src/audio/pcm.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+
+export function pcm16BytesToSamples(audio: Uint8Array): Int16Array {
+  if (audio.byteLength % 2 !== 0) {
+    throw new Error("PCM16 audio payload must contain an even number of bytes");
+  }
+  const view = new DataView(audio.buffer, audio.byteOffset, audio.byteLength);
+  const samples = new Int16Array(audio.byteLength / 2);
+  for (let i = 0; i < samples.length; i += 1) {
+    samples[i] = view.getInt16(i * 2, true);
+  }
+  return samples;
+}
+
+export function pcm16SamplesToBytes(samples: Int16Array): Uint8Array {
+  const bytes = new Uint8Array(samples.byteLength);
+  const view = new DataView(bytes.buffer);
+  for (let i = 0; i < samples.length; i += 1) {
+    view.setInt16(i * 2, samples[i]!, true);
+  }
+  return bytes;
+}
+
+export function bigEndianPcm16BytesToSamples(audio: Uint8Array): Int16Array {
+  if (audio.byteLength % 2 !== 0) {
+    throw new Error("L16 audio payload must contain an even number of bytes");
+  }
+  const view = new DataView(audio.buffer, audio.byteOffset, audio.byteLength);
+  const samples = new Int16Array(audio.byteLength / 2);
+  for (let i = 0; i < samples.length; i += 1) {
+    samples[i] = view.getInt16(i * 2, false);
+  }
+  return samples;
+}
+
+export function pcm16SamplesToBigEndianBytes(samples: Int16Array): Uint8Array {
+  const bytes = new Uint8Array(samples.byteLength);
+  const view = new DataView(bytes.buffer);
+  for (let i = 0; i < samples.length; i += 1) {
+    view.setInt16(i * 2, samples[i]!, false);
+  }
+  return bytes;
+}

package/src/audio/resample.ts

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: MIT
+
+// Windowed-sinc FIR low-pass filter for anti-alias downsampling.
+// Hann window, 127 taps — gives ~44 dB min stopband attenuation, sufficient for
+// the ≥40 dB alias-suppression requirement (F3). A polyphase structure would be
+// faster but this direct-form is simpler to audit and correct for our frame sizes.
+const FIR_TAPS = 127;
+
+function buildLowPassFir(cutoffNormalized: number): Float64Array {
+  // cutoffNormalized: fraction of the source sample rate (0 = DC, 0.5 = Nyquist).
+  const M = FIR_TAPS - 1; // filter order (126 for 127 taps)
+  const h = new Float64Array(FIR_TAPS);
+  let sum = 0;
+  for (let n = 0; n < FIR_TAPS; n += 1) {
+    const delay = n - M / 2; // centered delay: -63..0..63
+    const sinc =
+      delay === 0
+        ? 2 * cutoffNormalized
+        : Math.sin(2 * Math.PI * cutoffNormalized * delay) / (Math.PI * delay);
+    const hann = 0.5 - 0.5 * Math.cos((2 * Math.PI * n) / M);
+    h[n] = sinc * hann;
+    sum += h[n]!;
+  }
+  // Normalize for unity DC gain.
+  for (let n = 0; n < FIR_TAPS; n += 1) {
+    h[n]! /= sum;
+  }
+  return h;
+}
+
+// The FIR depends only on the (source,target) rate pair via its cutoff, which is
+// constant per connection. resamplePcm16 runs per audio chunk in the hot path, so
+// cache the kernel instead of rebuilding 127 sinc·Hann taps on every call. Bounded:
+// real deployments use a handful of distinct rate pairs (24k/16k→8k, 48k→16k, …).
+const firCache = new Map<number, Float64Array>();
+
+function getLowPassFir(cutoffNormalized: number): Float64Array {
+  const key = Math.round(cutoffNormalized * 1e6);
+  let fir = firCache.get(key);
+  if (fir === undefined) {
+    fir = buildLowPassFir(cutoffNormalized);
+    firCache.set(key, fir);
+  }
+  return fir;
+}
+
+// Evaluate the symmetric FIR centered at each decimated output position.
+// Using the symmetric (zero-delay) formula avoids a group-delay shift at the
+// cost of needing halfTaps future samples — which are available because we
+// process a complete chunk at once.  Edge samples (first / last halfTaps/ratio
+// output samples) use only the available taps; their amplitude tapers due to
+// the missing context, which is the accepted trade-off for stateless chunk
+// processing.
+function firDecimate(input: Int16Array, outputLength: number, ratio: number, fir: Float64Array): Int16Array {
+  const M = fir.length;
+  const halfTaps = Math.floor(M / 2); // 63 for 127-tap filter
+  const output = new Int16Array(outputLength);
+  for (let m = 0; m < outputLength; m += 1) {
+    const n0 = Math.round(m * ratio); // nearest source position for output m
+    let acc = 0;
+    // Centered: h[0] multiplies x[n0+halfTaps], h[halfTaps] multiplies x[n0],
+    // h[M-1] multiplies x[n0-halfTaps].
+    for (let k = 0; k < M; k += 1) {
+      const srcIdx = n0 - k + halfTaps;
+      if (srcIdx >= 0 && srcIdx < input.length) {
+        acc += fir[k]! * input[srcIdx]!;
+      }
+    }
+    // Clamp to Int16 range; FIR sum can slightly exceed due to rounding.
+    output[m] = Math.max(-32768, Math.min(32767, Math.round(acc)));
+  }
+  return output;
+}
+
+function linearInterpolate(input: Int16Array, outputLength: number, ratio: number): Int16Array {
+  const output = new Int16Array(outputLength);
+  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;
+}
+
+function outputLengthFor(inputLength: number, sourceSampleRateHz: number, targetSampleRateHz: number): number {
+  return Math.max(1, Math.round((inputLength * targetSampleRateHz) / sourceSampleRateHz));
+}
+
+export function resamplePcm16(
+  input: Int16Array,
+  sourceSampleRateHz: number,
+  targetSampleRateHz: number,
+): Int16Array {
+  if (input.length === 0) return new Int16Array(0);
+  if (sourceSampleRateHz === targetSampleRateHz) return input;
+
+  const outputLength = outputLengthFor(input.length, sourceSampleRateHz, targetSampleRateHz);
+  const ratio = sourceSampleRateHz / targetSampleRateHz;
+
+  if (ratio <= 1) {
+    return linearInterpolate(input, outputLength, ratio);
+  }
+
+  const cutoffNormalized = (0.45 * targetSampleRateHz) / sourceSampleRateHz;
+  const fir = getLowPassFir(cutoffNormalized);
+  return firDecimate(input, outputLength, ratio, fir);
+}
+
+export class StreamingPcm16Resampler {
+  private history = new Int16Array(0);
+  private readonly ratio: number;
+  private readonly fir: Float64Array | null;
+  private readonly sourceSampleRateHz: number;
+  private readonly targetSampleRateHz: number;
+
+  constructor(sourceSampleRateHz: number, targetSampleRateHz: number) {
+    this.sourceSampleRateHz = sourceSampleRateHz;
+    this.targetSampleRateHz = targetSampleRateHz;
+    this.ratio = sourceSampleRateHz / targetSampleRateHz;
+    if (this.ratio > 1) {
+      const cutoffNormalized = (0.45 * targetSampleRateHz) / sourceSampleRateHz;
+      this.fir = getLowPassFir(cutoffNormalized);
+    } else {
+      this.fir = null;
+    }
+  }
+
+  process(input: Int16Array): Int16Array {
+    if (input.length === 0) return new Int16Array(0);
+    if (this.sourceSampleRateHz === this.targetSampleRateHz) return input;
+
+    if (this.ratio <= 1 || this.fir === null) {
+      const outputLength = outputLengthFor(input.length, this.sourceSampleRateHz, this.targetSampleRateHz);
+      return linearInterpolate(input, outputLength, this.ratio);
+    }
+
+    const historyLength = this.history.length;
+    const combined = new Int16Array(historyLength + input.length);
+    combined.set(this.history, 0);
+    combined.set(input, historyLength);
+
+    const fullOutputLength = outputLengthFor(combined.length, this.sourceSampleRateHz, this.targetSampleRateHz);
+    const fullOutput = firDecimate(combined, fullOutputLength, this.ratio, this.fir);
+    let firstNewOutput = 0;
+    if (historyLength > 0) {
+      while (firstNewOutput < fullOutput.length) {
+        const centerInputIndex = Math.round(firstNewOutput * this.ratio);
+        if (centerInputIndex >= historyLength) break;
+        firstNewOutput += 1;
+      }
+    }
+    const output = fullOutput.subarray(firstNewOutput);
+
+    const keepHistory = Math.min(FIR_TAPS - 1, combined.length);
+    this.history = combined.subarray(combined.length - keepHistory);
+    return output;
+  }
+}
+
+export function resamplePcm16Streaming(
+  resamplers: Map<string, StreamingPcm16Resampler>,
+  input: Int16Array,
+  sourceSampleRateHz: number,
+  targetSampleRateHz: number,
+): Int16Array {
+  if (input.length === 0) return new Int16Array(0);
+  if (sourceSampleRateHz === targetSampleRateHz) return input;
+  const key = `${String(sourceSampleRateHz)}->${String(targetSampleRateHz)}`;
+  let resampler = resamplers.get(key);
+  if (!resampler) {
+    resampler = new StreamingPcm16Resampler(sourceSampleRateHz, targetSampleRateHz);
+    resamplers.set(key, resampler);
+  }
+  return resampler.process(input);
+}