@moxxy/plugin-stt-local 0.28.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@moxxy/plugin-stt-local",
+  "version": "0.28.0",
+  "description": "Fully local, on-device speech-to-text Transcriber for moxxy. Runs multilingual Whisper (English + Polish) via sherpa-onnx in a forked sidecar process; models download once on first use from sherpa-onnx's pinned releases (sha256-verified). No API key, no network at transcription time. Plugs into the session TranscriberRegistry — the TUI and channel voice notes consume it transparently.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "stt",
+    "speech-to-text",
+    "whisper",
+    "offline",
+    "on-device",
+    "sherpa-onnx",
+    "transcriber"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-stt-local"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "transcriber"
+    }
+  },
+  "dependencies": {
+    "sherpa-onnx-node": "^1.13.3",
+    "@moxxy/model-fetch": "0.1.0",
+    "@moxxy/sdk": "0.28.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/audio.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  downmixToMono,
+  isRiffWave,
+  parseWav,
+  pcm16ToFloat32,
+  resampleLinear,
+} from './audio.js';
+
+/** Build a canonical PCM16 WAV buffer from interleaved int16 samples. */
+function buildWav(
+  int16: number[],
+  opts: { channels?: number; sampleRate?: number; audioFormat?: number; bitsPerSample?: number } = {},
+): Uint8Array {
+  const channels = opts.channels ?? 1;
+  const sampleRate = opts.sampleRate ?? 16_000;
+  const audioFormat = opts.audioFormat ?? 1;
+  const bitsPerSample = opts.bitsPerSample ?? 16;
+  const bytesPerSample = bitsPerSample / 8;
+  const dataSize = int16.length * bytesPerSample;
+  const buf = new Uint8Array(44 + dataSize);
+  const view = new DataView(buf.buffer);
+  const ascii = (o: number, s: string): void => {
+    for (let i = 0; i < s.length; i += 1) buf[o + i] = s.charCodeAt(i);
+  };
+  ascii(0, 'RIFF');
+  view.setUint32(4, 36 + dataSize, true);
+  ascii(8, 'WAVE');
+  ascii(12, 'fmt ');
+  view.setUint32(16, 16, true);
+  view.setUint16(20, audioFormat, true);
+  view.setUint16(22, channels, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * channels * bytesPerSample, true);
+  view.setUint16(32, channels * bytesPerSample, true);
+  view.setUint16(34, bitsPerSample, true);
+  ascii(36, 'data');
+  view.setUint32(40, dataSize, true);
+  let off = 44;
+  for (const s of int16) {
+    if (bitsPerSample === 16) view.setInt16(off, s, true);
+    else view.setUint8(off, s & 0xff);
+    off += bytesPerSample;
+  }
+  return buf;
+}
+
+describe('pcm16ToFloat32', () => {
+  it('maps int16 range edges to ~[-1, 1) and 0 to 0', () => {
+    const bytes = new Uint8Array(6);
+    const v = new DataView(bytes.buffer);
+    v.setInt16(0, 0, true);
+    v.setInt16(2, 32767, true);
+    v.setInt16(4, -32768, true);
+    const f = pcm16ToFloat32(bytes);
+    expect(f[0]).toBe(0);
+    expect(f[1]).toBeCloseTo(0.99997, 4);
+    expect(f[2]).toBe(-1); // -32768 / 32768
+  });
+
+  it('drops a trailing odd byte instead of misreading it', () => {
+    const bytes = new Uint8Array([0, 0, 0, 0, 7]); // 2 samples + 1 stray byte
+    expect(pcm16ToFloat32(bytes)).toHaveLength(2);
+  });
+
+  it('works on a non-2-aligned subarray view', () => {
+    const backing = new Uint8Array(5);
+    const v = new DataView(backing.buffer);
+    v.setInt16(1, 16384, true); // write at offset 1 (odd)
+    const f = pcm16ToFloat32(backing.subarray(1, 3));
+    expect(f[0]).toBeCloseTo(0.5, 5);
+  });
+});
+
+describe('downmixToMono', () => {
+  it('averages stereo frames', () => {
+    // interleaved L,R,L,R → [(1+3)/2, (0.5-0.5)/2]
+    const stereo = Float32Array.from([1, 3, 0.5, -0.5]);
+    const mono = downmixToMono(stereo, 2);
+    expect(Array.from(mono)).toEqual([2, 0]);
+  });
+
+  it('returns the input unchanged for mono', () => {
+    const mono = Float32Array.from([0.1, 0.2]);
+    expect(downmixToMono(mono, 1)).toBe(mono);
+  });
+
+  it('ignores a trailing partial frame', () => {
+    const stereo = Float32Array.from([1, 1, 2]); // 1.5 frames
+    expect(downmixToMono(stereo, 2)).toHaveLength(1);
+  });
+});
+
+describe('resampleLinear', () => {
+  it('returns the input unchanged when rates match', () => {
+    const x = Float32Array.from([0.1, 0.2, 0.3]);
+    expect(resampleLinear(x, 16_000, 16_000)).toBe(x);
+  });
+
+  it('preserves a DC (constant) signal', () => {
+    const x = new Float32Array(240).fill(0.42);
+    const y = resampleLinear(x, 24_000, 16_000);
+    expect(y.length).toBe(160);
+    for (const s of y) expect(s).toBeCloseTo(0.42, 6);
+  });
+
+  it('changes length by the rate ratio (24k → 16k ≈ 2/3)', () => {
+    const y = resampleLinear(new Float32Array(300), 24_000, 16_000);
+    expect(y.length).toBe(200);
+    const up = resampleLinear(new Float32Array(160), 16_000, 24_000);
+    expect(up.length).toBe(240);
+  });
+
+  it('tracks a sine wave in continuous time after resampling 24k → 16k', () => {
+    const fromRate = 24_000;
+    const toRate = 16_000;
+    const freq = 220; // Hz — well below Nyquist at both rates
+    const n = 2400; // 0.1 s
+    const src = new Float32Array(n);
+    for (let i = 0; i < n; i += 1) src[i] = Math.sin((2 * Math.PI * freq * i) / fromRate);
+    const out = resampleLinear(src, fromRate, toRate);
+    // Each output sample should approximate the same continuous sine sampled at
+    // the target rate (linear interpolation error is tiny for 220 Hz).
+    for (let i = 0; i < out.length - 1; i += 1) {
+      const expected = Math.sin((2 * Math.PI * freq * i) / toRate);
+      expect(out[i]).toBeCloseTo(expected, 2);
+    }
+  });
+});
+
+describe('isRiffWave', () => {
+  it('detects RIFF/WAVE magic', () => {
+    expect(isRiffWave(buildWav([0, 0]))).toBe(true);
+    expect(isRiffWave(new Uint8Array([1, 2, 3, 4]))).toBe(false);
+    expect(isRiffWave(new Uint8Array(0))).toBe(false);
+  });
+});
+
+describe('parseWav', () => {
+  it('parses a mono PCM16 file', () => {
+    const wav = buildWav([0, 16384, -16384], { channels: 1, sampleRate: 16_000 });
+    const parsed = parseWav(wav);
+    expect(parsed.channels).toBe(1);
+    expect(parsed.sampleRate).toBe(16_000);
+    expect(parsed.samples[1]).toBeCloseTo(0.5, 4);
+    expect(parsed.samples[2]).toBeCloseTo(-0.5, 4);
+  });
+
+  it('parses a stereo PCM16 file (interleaved, still needs downmix)', () => {
+    const wav = buildWav([1000, 2000, 3000, 4000], { channels: 2, sampleRate: 8_000 });
+    const parsed = parseWav(wav);
+    expect(parsed.channels).toBe(2);
+    expect(parsed.samples).toHaveLength(4);
+    expect(Array.from(downmixToMono(parsed.samples, parsed.channels))).toHaveLength(2);
+  });
+
+  it('rejects IEEE-float WAV politely', () => {
+    const wav = buildWav([0, 0], { audioFormat: 3, bitsPerSample: 32 });
+    expect(() => parseWav(wav)).toThrow(/IEEE float/);
+  });
+
+  it('rejects 8-bit PCM WAV', () => {
+    const wav = buildWav([0, 0], { audioFormat: 1, bitsPerSample: 8 });
+    expect(() => parseWav(wav)).toThrow(/8-bit PCM/);
+  });
+
+  it('throws CONFIG_INVALID for a non-RIFF buffer', () => {
+    expect(() => parseWav(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]))).toThrow(
+      /not a RIFF/,
+    );
+    try {
+      parseWav(new Uint8Array(12));
+    } catch (err) {
+      expect((err as { code?: string }).code).toBe('CONFIG_INVALID');
+    }
+  });
+
+  it('tolerates an extra chunk before data and a padded odd-size chunk', () => {
+    // Hand-build: RIFF WAVE | fmt(16) | LIST(3, padded to 4) | data(4)
+    const parts: number[] = [];
+    const push32 = (n: number): void => {
+      parts.push(n & 0xff, (n >> 8) & 0xff, (n >> 16) & 0xff, (n >> 24) & 0xff);
+    };
+    const pushStr = (s: string): void => {
+      for (const c of s) parts.push(c.charCodeAt(0));
+    };
+    // placeholder RIFF size filled later
+    pushStr('RIFF');
+    push32(0);
+    pushStr('WAVE');
+    pushStr('fmt ');
+    push32(16);
+    parts.push(1, 0); // PCM
+    parts.push(1, 0); // mono
+    push32(16_000);
+    push32(16_000 * 2);
+    parts.push(2, 0); // block align
+    parts.push(16, 0); // bits
+    pushStr('LIST');
+    push32(3); // odd size
+    parts.push(9, 9, 9, 0); // 3 bytes + 1 pad
+    pushStr('data');
+    push32(4);
+    parts.push(0, 0, 0, 64); // two int16 samples: 0, 16384
+    const bytes = new Uint8Array(parts);
+    new DataView(bytes.buffer).setUint32(4, bytes.length - 8, true);
+    const parsed = parseWav(bytes);
+    expect(parsed.sampleRate).toBe(16_000);
+    expect(parsed.samples).toHaveLength(2);
+    expect(parsed.samples[1]).toBeCloseTo(0.5, 4);
+  });
+});

package/src/audio.ts

@@ -0,0 +1,220 @@
+/**
+ * Pure, dependency-free audio DSP for the local Whisper transcriber. sherpa's
+ * OfflineRecognizer wants Float32 mono PCM in [-1, 1] at 16 kHz; inbound audio
+ * arrives in several shapes, so these helpers convert each to that canonical
+ * form IN-PROCESS (no ffmpeg for raw PCM / WAV):
+ *
+ *   - `pcm16ToFloat32`  int16 little-endian bytes → Float32 in [-1, 1]
+ *   - `downmixToMono`   interleaved N-channel Float32 → averaged mono
+ *   - `resampleLinear`  linear-interpolation resample between two rates
+ *   - `parseWav`        RIFF/WAVE header parse → PCM16 samples (float) + rate +
+ *                       channels; rejects non-PCM16 (float/compressed) WAV
+ *
+ * The `decodeToMono16k` orchestrator (in ./decode.ts) drives these plus the
+ * ffmpeg path. Everything here is synchronous and unit-tested against synthetic
+ * fixtures — the header offsets and the resampler math are load-bearing.
+ */
+
+import { MoxxyError } from '@moxxy/sdk';
+
+/** The sample rate sherpa's Whisper feature extractor expects. */
+export const TARGET_SAMPLE_RATE = 16_000;
+
+/** Full-scale divisor: int16 spans [-32768, 32767]; dividing by 32768 keeps
+ *  the result in [-1, 1) without clipping the negative rail. */
+const INT16_SCALE = 32_768;
+
+/**
+ * Convert raw 16-bit little-endian PCM bytes to Float32 in [-1, 1]. A trailing
+ * odd byte (half a sample) is dropped. Channel interleaving is preserved — a
+ * stereo buffer stays interleaved, so callers downmix afterwards.
+ */
+export function pcm16ToFloat32(pcm: Uint8Array | ArrayBuffer): Float32Array {
+  const bytes = pcm instanceof Uint8Array ? pcm : new Uint8Array(pcm);
+  const usable = bytes.byteLength & ~1; // drop a trailing odd byte
+  const count = usable / 2;
+  const out = new Float32Array(count);
+  // Read via DataView so we don't depend on the platform being little-endian
+  // and don't require the byte offset to be 2-aligned (a subarray view can
+  // start on an odd offset).
+  const view = new DataView(bytes.buffer, bytes.byteOffset, usable);
+  for (let i = 0; i < count; i += 1) {
+    out[i] = view.getInt16(i * 2, true) / INT16_SCALE;
+  }
+  return out;
+}
+
+/**
+ * Average `channels` interleaved Float32 channels down to mono. `channels` must
+ * be a positive integer; a value of 1 returns the input unchanged. Trailing
+ * samples that don't complete a frame are ignored.
+ */
+export function downmixToMono(interleaved: Float32Array, channels: number): Float32Array {
+  if (!Number.isInteger(channels) || channels < 1) {
+    throw new MoxxyError({
+      code: 'INTERNAL',
+      message: `downmixToMono: invalid channel count ${channels}.`,
+    });
+  }
+  if (channels === 1) return interleaved;
+  const frames = Math.floor(interleaved.length / channels);
+  const out = new Float32Array(frames);
+  for (let f = 0; f < frames; f += 1) {
+    let sum = 0;
+    const base = f * channels;
+    for (let c = 0; c < channels; c += 1) sum += interleaved[base + c]!;
+    out[f] = sum / channels;
+  }
+  return out;
+}
+
+/**
+ * Resample mono Float32 audio from `fromRate` to `toRate` by linear
+ * interpolation. Cheap and dependency-free — good enough for speech recognition
+ * (Whisper is robust to the mild low-pass a linear kernel imposes). Returns the
+ * input unchanged when the rates match, and an empty array for empty input.
+ */
+export function resampleLinear(
+  input: Float32Array,
+  fromRate: number,
+  toRate: number,
+): Float32Array {
+  if (!Number.isFinite(fromRate) || !Number.isFinite(toRate) || fromRate <= 0 || toRate <= 0) {
+    throw new MoxxyError({
+      code: 'INTERNAL',
+      message: `resampleLinear: invalid rate(s) from=${fromRate} to=${toRate}.`,
+    });
+  }
+  if (fromRate === toRate) return input;
+  if (input.length === 0) return new Float32Array(0);
+  if (input.length === 1) return Float32Array.of(input[0]!);
+
+  const ratio = fromRate / toRate;
+  const outLen = Math.max(1, Math.round(input.length / ratio));
+  const out = new Float32Array(outLen);
+  const lastIdx = input.length - 1;
+  for (let i = 0; i < outLen; i += 1) {
+    const srcPos = i * ratio;
+    const i0 = Math.floor(srcPos);
+    if (i0 >= lastIdx) {
+      out[i] = input[lastIdx]!;
+      continue;
+    }
+    const frac = srcPos - i0;
+    out[i] = input[i0]! * (1 - frac) + input[i0 + 1]! * frac;
+  }
+  return out;
+}
+
+/** True when `bytes` begins with the `RIFF….WAVE` magic of a WAV container. */
+export function isRiffWave(bytes: Uint8Array): boolean {
+  return (
+    bytes.length >= 12 &&
+    bytes[0] === 0x52 && // R
+    bytes[1] === 0x49 && // I
+    bytes[2] === 0x46 && // F
+    bytes[3] === 0x46 && // F
+    bytes[8] === 0x57 && // W
+    bytes[9] === 0x41 && // A
+    bytes[10] === 0x56 && // V
+    bytes[11] === 0x45 // E
+  );
+}
+
+export interface ParsedWav {
+  /** PCM samples as Float32 in [-1, 1], still interleaved if multi-channel. */
+  readonly samples: Float32Array;
+  readonly sampleRate: number;
+  readonly channels: number;
+}
+
+// WAV `fmt ` audio-format codes we care about.
+const WAVE_FORMAT_PCM = 1;
+const WAVE_FORMAT_IEEE_FLOAT = 3;
+const WAVE_FORMAT_EXTENSIBLE = 0xfffe;
+
+/**
+ * Parse a canonical RIFF/WAVE buffer into PCM16 samples. Only linear 16-bit PCM
+ * is accepted — IEEE-float, μ-law, and compressed WAV are rejected with a clear
+ * `CONFIG_INVALID` MoxxyError (the caller falls back to ffmpeg for real
+ * compressed formats, but a mislabelled/exotic WAV should fail loudly, not
+ * silently mis-decode). Walks the chunk list rather than assuming a fixed
+ * 44-byte header, so files with extra chunks (`LIST`, `fact`, …) still parse.
+ */
+export function parseWav(bytes: Uint8Array): ParsedWav {
+  if (!isRiffWave(bytes)) {
+    throw wavError('not a RIFF/WAVE file (bad magic).');
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+
+  let fmt: { format: number; channels: number; sampleRate: number; bitsPerSample: number } | null =
+    null;
+  let dataOffset = -1;
+  let dataLen = 0;
+
+  // Chunks begin right after `RIFF<size>WAVE` (offset 12). Each chunk is a
+  // 4-byte id + uint32 little-endian size + payload, word-aligned (odd payloads
+  // carry a pad byte).
+  let off = 12;
+  while (off + 8 <= bytes.byteLength) {
+    const id = ascii4(bytes, off);
+    const size = view.getUint32(off + 4, true);
+    const body = off + 8;
+    if (id === 'fmt ') {
+      if (body + 16 > bytes.byteLength) throw wavError('truncated fmt chunk.');
+      fmt = {
+        format: view.getUint16(body, true),
+        channels: view.getUint16(body + 2, true),
+        sampleRate: view.getUint32(body + 4, true),
+        bitsPerSample: view.getUint16(body + 14, true),
+      };
+    } else if (id === 'data') {
+      dataOffset = body;
+      // Clamp a declared size that overruns the buffer (some encoders write 0
+      // or 0xffffffff for streamed data) to what's actually present.
+      dataLen = Math.min(size, bytes.byteLength - body);
+    }
+    // Advance past the payload + pad byte. Guard against a zero/garbage size
+    // that would loop forever.
+    const advance = 8 + size + (size & 1);
+    if (advance <= 8) break;
+    off += advance;
+  }
+
+  if (!fmt) throw wavError('missing fmt chunk.');
+  if (dataOffset < 0) throw wavError('missing data chunk.');
+
+  const { format, channels, sampleRate, bitsPerSample } = fmt;
+  if (!Number.isInteger(channels) || channels < 1) {
+    throw wavError(`unsupported channel count ${channels}.`);
+  }
+  if (!Number.isInteger(sampleRate) || sampleRate <= 0) {
+    throw wavError(`unsupported sample rate ${sampleRate}.`);
+  }
+  // Accept plain PCM; also accept EXTENSIBLE only when it's declared 16-bit PCM
+  // (a common wrapper the codecs emit for the same data). Reject float/exotic.
+  const isPcm16 =
+    (format === WAVE_FORMAT_PCM || format === WAVE_FORMAT_EXTENSIBLE) && bitsPerSample === 16;
+  if (!isPcm16) {
+    const kind =
+      format === WAVE_FORMAT_IEEE_FLOAT
+        ? 'IEEE float'
+        : format === WAVE_FORMAT_PCM || format === WAVE_FORMAT_EXTENSIBLE
+          ? `${bitsPerSample}-bit PCM`
+          : `format 0x${format.toString(16)}`;
+    throw wavError(
+      `unsupported WAV encoding (${kind}). Only 16-bit PCM WAV is decoded in-process; re-export as PCM16 WAV, or install ffmpeg to decode other formats.`,
+    );
+  }
+
+  const pcm = bytes.subarray(dataOffset, dataOffset + dataLen);
+  return { samples: pcm16ToFloat32(pcm), sampleRate, channels };
+}
+
+function ascii4(bytes: Uint8Array, off: number): string {
+  return String.fromCharCode(bytes[off]!, bytes[off + 1]!, bytes[off + 2]!, bytes[off + 3]!);
+}
+
+function wavError(detail: string): MoxxyError {
+  return new MoxxyError({ code: 'CONFIG_INVALID', message: `Invalid WAV audio: ${detail}` });
+}

package/src/decode.test.ts

@@ -0,0 +1,126 @@
+import { Buffer } from 'node:buffer';
+import { EventEmitter } from 'node:events';
+import type { spawn } from 'node:child_process';
+import { describe, expect, it } from 'vitest';
+
+import { MOXXY_PCM16_24KHZ_MIME } from '@moxxy/sdk';
+
+import { decodeToMono16k } from './decode.js';
+
+/** Minimal fake `spawn`: probe → exit 0, decode → emit the given f32le bytes. */
+function fakeSpawn(samples: Float32Array): typeof spawn {
+  return ((_cmd: string, args: readonly string[]) => {
+    const child = new EventEmitter() as EventEmitter & {
+      stdout: EventEmitter;
+      stderr: EventEmitter;
+      stdin: { writable: boolean; on: () => void; end: () => void };
+      kill: () => boolean;
+      killed: boolean;
+    };
+    child.stdout = new EventEmitter();
+    child.stderr = new EventEmitter();
+    child.killed = false;
+    child.kill = () => ((child.killed = true), true);
+    child.stdin = { writable: true, on: () => {}, end: () => {} };
+    const isProbe = args.includes('-version');
+    setImmediate(() => {
+      if (isProbe) {
+        child.emit('close', 0);
+        return;
+      }
+      if (samples.length > 0) child.stdout.emit('data', Buffer.from(samples.buffer.slice(0)));
+      child.emit('close', 0);
+    });
+    return child;
+  }) as unknown as typeof spawn;
+}
+
+/** Build raw PCM16 mono little-endian bytes for the given float samples. */
+function rawPcm16(samples: number[]): Uint8Array {
+  const bytes = new Uint8Array(samples.length * 2);
+  const view = new DataView(bytes.buffer);
+  samples.forEach((s, i) => view.setInt16(i * 2, Math.round(s * 32767), true));
+  return bytes;
+}
+
+/** Build a mono PCM16 WAV at the given sample rate. */
+function monoWav(samples: number[], sampleRate: number): Uint8Array {
+  const dataSize = samples.length * 2;
+  const buf = new Uint8Array(44 + dataSize);
+  const view = new DataView(buf.buffer);
+  const ascii = (o: number, s: string): void => {
+    for (let i = 0; i < s.length; i += 1) buf[o + i] = s.charCodeAt(i);
+  };
+  ascii(0, 'RIFF');
+  view.setUint32(4, 36 + dataSize, true);
+  ascii(8, 'WAVE');
+  ascii(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);
+  ascii(36, 'data');
+  view.setUint32(40, dataSize, true);
+  samples.forEach((s, i) => view.setInt16(44 + i * 2, Math.round(s * 32767), true));
+  return buf;
+}
+
+describe('decodeToMono16k', () => {
+  it('converts raw PCM16 mono @24k and resamples to 16k (no ffmpeg)', async () => {
+    const dc = new Array<number>(240).fill(0.5); // 240 samples @24k → 160 @16k
+    const out = await decodeToMono16k(rawPcm16(dc), MOXXY_PCM16_24KHZ_MIME);
+    expect(out.length).toBe(160);
+    for (const s of out) expect(s).toBeCloseTo(0.5, 2);
+  });
+
+  it('parses a 16k mono WAV unchanged (no resample, no ffmpeg)', async () => {
+    const wav = monoWav([0, 0.5, -0.5], 16_000);
+    const out = await decodeToMono16k(wav, 'audio/wav');
+    expect(out.length).toBe(3);
+    expect(out[1]).toBeCloseTo(0.5, 3);
+  });
+
+  it('resamples a 8k WAV up to 16k', async () => {
+    const wav = monoWav(new Array<number>(80).fill(0.25), 8_000);
+    const out = await decodeToMono16k(wav, 'audio/x-wav');
+    expect(out.length).toBe(160);
+  });
+
+  it('sniffs RIFF/WAVE magic when the MIME is missing', async () => {
+    const wav = monoWav([0.1, 0.2], 16_000);
+    const out = await decodeToMono16k(wav, undefined);
+    expect(out.length).toBe(2);
+  });
+
+  it('routes compressed audio (audio/ogg) through ffmpeg', async () => {
+    const decoded = Float32Array.from([0.1, -0.2, 0.3]);
+    const out = await decodeToMono16k(new Uint8Array([1, 2, 3]), 'audio/ogg', {
+      spawnImpl: fakeSpawn(decoded),
+    });
+    expect(Array.from(out)).toEqual([
+      expect.closeTo(0.1, 5),
+      expect.closeTo(-0.2, 5),
+      expect.closeTo(0.3, 5),
+    ]);
+  });
+
+  it('handles a MIME with a codecs= parameter (case-insensitive)', async () => {
+    const decoded = Float32Array.from([0.42]);
+    const out = await decodeToMono16k(new Uint8Array([1]), 'AUDIO/OGG; codecs=opus', {
+      spawnImpl: fakeSpawn(decoded),
+    });
+    expect(out[0]).toBeCloseTo(0.42, 5);
+  });
+
+  it('rejects an IEEE-float WAV politely instead of mis-decoding', async () => {
+    // Build a float WAV header (format 3) — parseWav must reject it.
+    const buf = monoWav([0], 16_000);
+    new DataView(buf.buffer).setUint16(20, 3, true); // audioFormat = IEEE float
+    await expect(decodeToMono16k(buf, 'audio/wav')).rejects.toMatchObject({
+      code: 'CONFIG_INVALID',
+    });
+  });
+});