mlx-bun 0.4.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mlx-bun",
-  "version": "0.4.0",
-  "description": "Native MLX inference for Bun on Apple Silicon — local LLM server (OpenAI/Anthropic-compatible) and TypeScript library. No Python.",
+  "version": "0.5.0",
+  "description": "Native MLX inference for Bun on Apple Silicon \u2014 local LLM server (OpenAI/Anthropic-compatible) and TypeScript library. No Python.",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/audio/audiotoolbox.ts

@@ -0,0 +1,112 @@
+// In-process audio decoding through macOS AudioToolbox (ExtAudioFile) over
+// bun:ffi — every container/codec CoreAudio reads (mp3, m4a/aac, flac, ogg,
+// aiff, caf, wav, mov/mp4 audio tracks…) straight to 16 kHz mono float32,
+// with CoreAudio's own resampler. Replaces the `afconvert` subprocess of
+// transcode.ts (no process spawn, no WAV re-parse); the bytes still touch a
+// temp file because ExtAudioFile opens URLs.
+
+import { dlopen, FFIType, ptr, read } from "bun:ffi";
+import { randomUUID } from "node:crypto";
+import { unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const { ptr: P, i32, u32, u64, i64 } = FFIType;
+
+function openLibs() {
+  const at = dlopen("/System/Library/Frameworks/AudioToolbox.framework/AudioToolbox", {
+    ExtAudioFileOpenURL: { args: [u64, P], returns: i32 },
+    ExtAudioFileSetProperty: { args: [u64, u32, u32, P], returns: i32 },
+    ExtAudioFileGetProperty: { args: [u64, u32, P, P], returns: i32 },
+    ExtAudioFileRead: { args: [u64, P, P], returns: i32 },
+    ExtAudioFileDispose: { args: [u64], returns: i32 },
+  }).symbols;
+  const cf = dlopen("/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation", {
+    CFURLCreateFromFileSystemRepresentation: { args: [u64, P, i64, FFIType.bool], returns: u64 },
+    CFRelease: { args: [u64], returns: i32 },
+  }).symbols;
+  return { at, cf };
+}
+
+let libs: ReturnType<typeof openLibs> | null = null;
+const load = () => (libs ??= openLibs());
+
+const fourcc = (s: string) => (s.charCodeAt(0) << 24 | s.charCodeAt(1) << 16 | s.charCodeAt(2) << 8 | s.charCodeAt(3)) >>> 0;
+const kExtAudioFileProperty_ClientDataFormat = fourcc("cfmt");
+const kExtAudioFileProperty_FileLengthFrames = fourcc("#frm");
+const kAudioFormatLinearPCM = fourcc("lpcm");
+const kAudioFormatFlagIsFloat = 1;
+const kAudioFormatFlagIsPacked = 8;
+
+export const AUDIOTOOLBOX_SAMPLE_RATE = 16_000;
+
+/** Decode a file to 16 kHz mono float32 with CoreAudio. Throws on undecodable input. */
+export function decodeFileWithAudioToolbox(path: string, sampleRate = AUDIOTOOLBOX_SAMPLE_RATE): Float32Array {
+  const { at, cf } = load();
+  const pathBuf = Buffer.from(path, "utf8");
+  const url = cf.CFURLCreateFromFileSystemRepresentation(0n, ptr(pathBuf), BigInt(pathBuf.length), false) as bigint;
+  if (!url) throw new Error("AudioToolbox: cannot build file URL");
+  const refSlot = new BigUint64Array(1);
+  try {
+    let st = at.ExtAudioFileOpenURL(url, ptr(refSlot)) as number;
+    if (st !== 0) throw new Error(`AudioToolbox: unrecognized or undecodable audio (ExtAudioFileOpenURL ${st})`);
+    const ref = read.u64(ptr(refSlot), 0);
+    try {
+      // AudioStreamBasicDescription: 40 bytes
+      const asbd = Buffer.alloc(40);
+      asbd.writeDoubleLE(sampleRate, 0);
+      asbd.writeUInt32LE(kAudioFormatLinearPCM, 8);
+      asbd.writeUInt32LE(kAudioFormatFlagIsFloat | kAudioFormatFlagIsPacked, 12);
+      asbd.writeUInt32LE(4, 16); // bytes per packet
+      asbd.writeUInt32LE(1, 20); // frames per packet
+      asbd.writeUInt32LE(4, 24); // bytes per frame
+      asbd.writeUInt32LE(1, 28); // channels
+      asbd.writeUInt32LE(32, 32); // bits per channel
+      st = at.ExtAudioFileSetProperty(ref, kExtAudioFileProperty_ClientDataFormat, 40, ptr(asbd)) as number;
+      if (st !== 0) throw new Error(`AudioToolbox: cannot set client format (${st})`);
+      // frame count hint (source rate), used only to size the first buffer
+      const lenSlot = new BigInt64Array(1);
+      const lenSize = new Uint32Array([8]);
+      at.ExtAudioFileGetProperty(ref, kExtAudioFileProperty_FileLengthFrames, ptr(lenSize), ptr(lenSlot));
+      const chunkFrames = 1 << 16;
+      const chunk = new Float32Array(chunkFrames);
+      // AudioBufferList { UInt32 mNumberBuffers; [pad 4]; AudioBuffer { UInt32 mNumberChannels; UInt32 mDataByteSize; void* mData } }
+      const abl = Buffer.alloc(24);
+      const frames = new Uint32Array(1);
+      const parts: Float32Array[] = [];
+      let total = 0;
+      for (;;) {
+        abl.writeUInt32LE(1, 0);
+        abl.writeUInt32LE(1, 8);
+        abl.writeUInt32LE(chunkFrames * 4, 12);
+        abl.writeBigUInt64LE(BigInt(ptr(chunk)), 16);
+        frames[0] = chunkFrames;
+        st = at.ExtAudioFileRead(ref, ptr(frames), ptr(abl)) as number;
+        if (st !== 0) throw new Error(`AudioToolbox: decode failed (ExtAudioFileRead ${st})`);
+        const n = frames[0]!;
+        if (n === 0) break;
+        parts.push(chunk.slice(0, n));
+        total += n;
+      }
+      const out = new Float32Array(total);
+      let o = 0;
+      for (const p of parts) { out.set(p, o); o += p.length; }
+      return out;
+    } finally {
+      at.ExtAudioFileDispose(ref);
+    }
+  } finally {
+    cf.CFRelease(url);
+  }
+}
+
+/** Decode in-memory bytes (any CoreAudio-readable container) via a temp file. */
+export function decodeBytesWithAudioToolbox(bytes: Uint8Array, sampleRate = AUDIOTOOLBOX_SAMPLE_RATE): Float32Array {
+  const path = join(tmpdir(), `mlx-bun-audio-${randomUUID()}`);
+  writeFileSync(path, bytes);
+  try {
+    return decodeFileWithAudioToolbox(path, sampleRate);
+  } finally {
+    try { unlinkSync(path); } catch { /* already gone */ }
+  }
+}

package/src/audio/conformer.ts

@@ -43,6 +43,7 @@
 // mlx inline-temporary hazard (CLAUDE.md): every op result is held in a
 // local and disposed; no nested `ops.foo(x.slice(...))` chains.
 
+import { tensorFingerprint } from "../model/fingerprint";
 import { ptr, read } from "bun:ffi";
 import { MlxArray, cpuStream } from "../mlx/array";
 import { C, Dtype } from "../mlx/ffi";
@@ -115,6 +116,13 @@ interface AttnContext {
 
 export class AudioTower {
   #weights = new Map<string, MlxArray>();
+  #cacheIdentity?: string;
+  /** Immutable encoder weights and computation settings, hashed once on use. */
+  get cacheIdentity(): string {
+    return this.#cacheIdentity ??= new Bun.CryptoHasher("sha256")
+      .update("gemma-audio-raw-v1").update(JSON.stringify([this.cfg, this.embedScale]))
+      .update(tensorFingerprint(this.#weights)).digest("hex");
+  }
   readonly cfg: AudioTowerConfig;
   readonly embedScale: number;
 

package/src/audio/mic-capture.ts

@@ -0,0 +1,98 @@
+// Microphone capture for `mlx-bun dictate`: spawns the AVAudioEngine
+// sidecar (src/native/mic_capture.swift, `mlx-bun-mic-capture`), yields
+// 16 kHz float32 PCM chunks and hotkey down/up events. Resolution mirrors
+// the video frame extractor: env override → beside the binary → the
+// native-pack dir → dev-compile from source with swiftc.
+
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { nativeRuntimeDir } from "../native-pack";
+import { runtimeValue } from "../runtime-config";
+
+const BIN = "mlx-bun-mic-capture";
+let devCompile: Promise<string | null> | null = null;
+
+function compileFromSource(): Promise<string | null> {
+  devCompile ??= (async () => {
+    const src = join(import.meta.dir, "..", "native", "mic_capture.swift");
+    if (!existsSync(src)) return null;
+    const out = join(import.meta.dir, "..", "..", "dist-native", BIN);
+    try {
+      mkdirSync(dirname(out), { recursive: true });
+      const proc = Bun.spawn(["swiftc", "-O", src, "-o", out], { stdout: "ignore", stderr: "pipe" });
+      if ((await proc.exited) === 0 && existsSync(out)) return out;
+    } catch { /* no swiftc */ }
+    return null;
+  })();
+  return devCompile;
+}
+
+export async function resolveMicCapture(): Promise<string | null> {
+  const explicit = runtimeValue("MLX_BUN_MIC_CAPTURE");
+  if (explicit) return explicit;
+  const beside = join(dirname(process.execPath), BIN);
+  if (existsSync(beside)) return beside;
+  const dir = nativeRuntimeDir();
+  if (dir && existsSync(join(dir, BIN))) return join(dir, BIN);
+  const dev = join(import.meta.dir, "..", "..", "dist-native", BIN);
+  if (existsSync(dev)) return dev;
+  return compileFromSource();
+}
+
+export type MicEvent =
+  | { kind: "ready"; info: string }
+  | { kind: "pcm"; samples: Float32Array }
+  | { kind: "hotkey"; down: boolean }
+  | { kind: "error"; message: string };
+
+export interface MicCapture {
+  events: AsyncIterable<MicEvent>;
+  stop(): void;
+}
+
+/** Start capturing. `hotkey` is a macOS virtual keycode (61 = Right Option). */
+export async function startMicCapture(opts: { hotkey?: number | null } = {}): Promise<MicCapture> {
+  const bin = await resolveMicCapture();
+  if (!bin) throw new Error("microphone capture needs the mlx-bun-mic-capture sidecar (build: scripts/build-mic-capture.sh, needs swiftc)");
+  const args = [bin, "--rate", "16000"];
+  if (opts.hotkey != null) args.push("--hotkey", String(opts.hotkey));
+  const proc = Bun.spawn(args, { stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+  const queue: MicEvent[] = [];
+  const waiter: { fn: (() => void) | null } = { fn: null };
+  let done = false;
+  const push = (e: MicEvent) => { queue.push(e); const w = waiter.fn; waiter.fn = null; w?.(); };
+  (async () => {
+    let carry = new Uint8Array(0);
+    for await (const chunk of proc.stdout) {
+      const buf = new Uint8Array(carry.length + chunk.length);
+      buf.set(carry); buf.set(chunk, carry.length);
+      const usable = buf.length - (buf.length % 4);
+      if (usable > 0) push({ kind: "pcm", samples: new Float32Array(buf.buffer.slice(0, usable)) });
+      carry = buf.subarray(usable);
+    }
+    done = true; const w = waiter.fn; waiter.fn = null; w?.();
+  })();
+  (async () => {
+    let text = "";
+    for await (const chunk of proc.stderr) {
+      text += new TextDecoder().decode(chunk);
+      let nl: number;
+      while ((nl = text.indexOf("\n")) >= 0) {
+        const line = text.slice(0, nl).trim(); text = text.slice(nl + 1);
+        if (line.startsWith("ready")) push({ kind: "ready", info: line.slice(5).trim() });
+        else if (line === "hotkey down") push({ kind: "hotkey", down: true });
+        else if (line === "hotkey up") push({ kind: "hotkey", down: false });
+        else if (line.startsWith("error:")) push({ kind: "error", message: line.slice(6).trim() });
+      }
+    }
+  })();
+  const events: AsyncIterable<MicEvent> = {
+    async *[Symbol.asyncIterator]() {
+      while (!done || queue.length) {
+        if (queue.length) { yield queue.shift()!; continue; }
+        await new Promise<void>((r) => { waiter.fn = r; });
+      }
+    },
+  };
+  return { events, stop: () => { try { proc.stdin.end(); } catch { /* gone */ } proc.kill(); } };
+}

package/src/audio/silero-vad.ts

@@ -0,0 +1,379 @@
+// Silero VAD v6 (16 kHz) — the voice-activity gate sotto runs before Whisper:
+// per 512-sample chunk (32 ms) a speech probability, then the reference
+// `get_speech_timestamps` state machine. Ported from the silero-vad 6.2.1
+// TorchScript graph (NOT whisper.cpp's approximation, which drops the
+// 64-sample inter-chunk context and pads both sides):
+//   x = [context(64) ‖ chunk(512)] → ReflectionPad1d(0, 64) → conv1d with
+//   the STFT basis (258 filters, 256 taps, hop 128) → |re, im| → [129, 4]
+//   → 4 × (Conv1d k3 + ReLU; strides 1,2,2,1; channels 128,64,64,128) → [128]
+//   → LSTMCell(128) → ReLU → Conv1d(128→1) → sigmoid.
+// Weights: ggml-org/whisper-vad's ggml-silero-v6.2.0.bin (885 KB; conv and
+// STFT weights are stored f16 there, so probabilities differ from the f32
+// reference by ~1e-3 — parity test tolerance; segments match).
+// Execution: the STFT, the conv encoder and the LSTM input projection run
+// batched over ALL chunks in one MLX graph; only the 128-wide recurrence
+// runs per chunk, on the host (65 K MACs each).
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { MlxArray } from "../mlx/array";
+import { Dtype } from "../mlx/ffi";
+import * as ops from "../mlx/ops";
+
+export const VAD_SAMPLE_RATE = 16_000;
+export const VAD_WINDOW = 512;
+export const VAD_CONTEXT = 64;
+const STFT_FILTERS = 258;
+const STFT_TAPS = 256;
+const STFT_HOP = 128;
+const STFT_PAD_RIGHT = 64;
+const LSTM_HIDDEN = 128;
+
+export interface VadStreamState {
+  h: Float32Array;
+  c: Float32Array;
+  /** Last 64 samples of the previous call (null before the first). */
+  context: Float32Array | null;
+  chunks: number;
+}
+
+export interface VadSegment {
+  /** Sample offsets at 16 kHz. */
+  start: number;
+  end: number;
+}
+
+export interface SpeechTimestampOptions {
+  threshold?: number;
+  minSpeechDurationMs?: number;
+  maxSpeechDurationS?: number;
+  minSilenceDurationMs?: number;
+  speechPadMs?: number;
+  negThreshold?: number | null;
+  minSilenceAtMaxSpeechMs?: number;
+  useMaxPossibleSilenceAtMaxSpeech?: boolean;
+}
+
+interface Tensor {
+  data: Float32Array;
+  shape: number[];
+}
+
+/** Parse whisper.cpp's ggml Silero container (models/convert-silero-vad-to-ggml.py). */
+export function parseSileroGgml(bytes: Uint8Array): { tensors: Map<string, Tensor>; version: string } {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let o = 0;
+  const i32 = () => { const v = dv.getInt32(o, true); o += 4; return v; };
+  if (i32() !== 0x67676d6c) throw new Error("silero vad: not a ggml file");
+  const typeLen = i32();
+  const modelType = new TextDecoder().decode(bytes.subarray(o, o + typeLen)); o += typeLen;
+  if (modelType !== "silero-16k") throw new Error(`silero vad: unexpected model type ${modelType}`);
+  const version = `${i32()}.${i32()}.${i32()}`;
+  const window = i32(); const context = i32();
+  if (window !== VAD_WINDOW || context !== VAD_CONTEXT) throw new Error(`silero vad: window ${window}/context ${context} unsupported`);
+  const nLayers = i32();
+  for (let l = 0; l < nLayers; l++) { i32(); i32(); i32(); }
+  i32(); i32(); i32(); i32(); // lstm in/hidden, final in/out
+  const tensors = new Map<string, Tensor>();
+  while (o < bytes.byteLength) {
+    const nDims = i32(); const nameLen = i32(); const ftype = i32();
+    const dims: number[] = [];
+    for (let d = 0; d < nDims; d++) dims.push(i32());
+    const name = new TextDecoder().decode(bytes.subarray(o, o + nameLen)); o += nameLen;
+    const n = dims.reduce((a, b) => a * b, 1);
+    const shape = [...dims].reverse(); // ggml ne[] is reversed row-major
+    let data: Float32Array;
+    if (ftype === 1) {
+      data = new Float32Array(n);
+      for (let i = 0; i < n; i++) data[i] = f16ToF32(dv.getUint16(o + 2 * i, true));
+      o += 2 * n;
+    } else {
+      data = new Float32Array(n);
+      for (let i = 0; i < n; i++) data[i] = dv.getFloat32(o + 4 * i, true);
+      o += 4 * n;
+    }
+    tensors.set(name, { data, shape });
+  }
+  return { tensors, version };
+}
+
+function f16ToF32(h: number): number {
+  const s = (h & 0x8000) ? -1 : 1;
+  const e = (h >> 10) & 0x1f;
+  const f = h & 0x3ff;
+  if (e === 0) return s * 2 ** -14 * (f / 1024);
+  if (e === 0x1f) return f ? Number.NaN : s * Infinity;
+  return s * 2 ** (e - 15) * (1 + f / 1024);
+}
+
+/** HF-cache location of ggml-org/whisper-vad's ggml-silero-v6.2.0.bin, or null. */
+export function resolveSileroVadPath(explicit?: string | null): string | null {
+  if (explicit) return existsSync(explicit) ? explicit : null;
+  const base = `${process.env.HOME}/.cache/huggingface/hub/models--ggml-org--whisper-vad/snapshots`;
+  try {
+    for (const snap of readdirSync(base)) {
+      const p = `${base}/${snap}/ggml-silero-v6.2.0.bin`;
+      if (existsSync(p)) return p;
+    }
+  } catch { /* absent */ }
+  return null;
+}
+
+export class SileroVad {
+  readonly version: string;
+  // device weights (MLX layouts)
+  readonly #stftW: MlxArray;        // [258, 256, 1]
+  readonly #convW: MlxArray[] = []; // [out, k, in]
+  readonly #convB: MlxArray[] = []; // [out]
+  readonly #convStride = [1, 2, 2, 1];
+  readonly #wIhT: MlxArray;         // [128, 512]
+  readonly #bIhHh: MlxArray;        // [512] = b_ih + b_hh
+  // host weights for the recurrence
+  readonly #wHh: Float32Array;      // [512, 128]
+  readonly #wFinal: Float32Array;   // [128]
+  readonly #bFinal: number;
+
+  private constructor(tensors: Map<string, Tensor>, version: string) {
+    this.version = version;
+    const t = (name: string): Tensor => {
+      const v = tensors.get(name);
+      if (!v) throw new Error(`silero vad: missing tensor ${name}`);
+      return v;
+    };
+    // STFT basis: torch (258, 1, 256) → MLX conv weight [out=258, k=256, in=1]
+    this.#stftW = MlxArray.fromFloat32(t("_model.stft.forward_basis_buffer").data, [STFT_FILTERS, STFT_TAPS, 1]);
+    for (let l = 0; l < 4; l++) {
+      const w = t(`_model.encoder.${l}.reparam_conv.weight`); // torch (out, in, 3)
+      const [out, inC, k] = w.shape as [number, number, number];
+      const mlx = new Float32Array(out * k * inC);
+      for (let oc = 0; oc < out; oc++) for (let ic = 0; ic < inC; ic++) for (let kk = 0; kk < k; kk++)
+        mlx[(oc * k + kk) * inC + ic] = w.data[(oc * inC + ic) * k + kk]!;
+      this.#convW.push(MlxArray.fromFloat32(mlx, [out, k, inC]));
+      this.#convB.push(MlxArray.fromFloat32(t(`_model.encoder.${l}.reparam_conv.bias`).data, [out]));
+    }
+    const wIh = t("_model.decoder.rnn.weight_ih"); // (512, 128)
+    const wIhT = new Float32Array(LSTM_HIDDEN * 4 * LSTM_HIDDEN);
+    for (let r = 0; r < 4 * LSTM_HIDDEN; r++) for (let c = 0; c < LSTM_HIDDEN; c++) wIhT[c * 4 * LSTM_HIDDEN + r] = wIh.data[r * LSTM_HIDDEN + c]!;
+    this.#wIhT = MlxArray.fromFloat32(wIhT, [LSTM_HIDDEN, 4 * LSTM_HIDDEN]);
+    const bIh = t("_model.decoder.rnn.bias_ih").data;
+    const bHh = t("_model.decoder.rnn.bias_hh").data;
+    const b = new Float32Array(4 * LSTM_HIDDEN);
+    for (let i = 0; i < b.length; i++) b[i] = bIh[i]! + bHh[i]!;
+    this.#bIhHh = MlxArray.fromFloat32(b, [4 * LSTM_HIDDEN]);
+    this.#wHh = t("_model.decoder.rnn.weight_hh").data;
+    this.#wFinal = t("_model.decoder.decoder.2.weight").data;
+    this.#bFinal = t("_model.decoder.decoder.2.bias").data[0]!;
+    ops.evalAll([this.#stftW, ...this.#convW, ...this.#convB, this.#wIhT, this.#bIhHh]);
+  }
+
+  static load(path?: string | null): SileroVad {
+    const p = resolveSileroVadPath(path);
+    if (!p)
+      throw new Error(
+        "Silero VAD weights not found: download ggml-org/whisper-vad (ggml-silero-v6.2.0.bin, 885 KB) " +
+        "into the HF cache or pass --vad-model <path>",
+      );
+    const { tensors, version } = parseSileroGgml(new Uint8Array(readFileSync(p)));
+    return new SileroVad(tensors, version);
+  }
+
+  /** Speech probability per 512-sample chunk (the last chunk zero-padded). */
+  probs(samples: Float32Array): Float32Array {
+    return this.probsStreaming(samples, null);
+  }
+
+  /** Streaming variant: `state` (LSTM h/c + the previous chunk's 64-sample
+   *  context) carries across calls; pass null to start fresh. Feed whole
+   *  512-sample multiples per call (a trailing partial chunk is zero-padded
+   *  and ends the stream like the reference). */
+  probsStreaming(samples: Float32Array, state: VadStreamState | null): Float32Array {
+    const n = Math.ceil(samples.length / VAD_WINDOW);
+    if (n === 0) return new Float32Array(0);
+    const hState = state?.h ?? new Float32Array(LSTM_HIDDEN);
+    const cState = state?.c ?? new Float32Array(LSTM_HIDDEN);
+    const prevContext = state?.context ?? null;
+    // [n, 640]: context (previous chunk's last 64 samples) ‖ chunk ‖ reflect pad 64
+    const W = VAD_CONTEXT + VAD_WINDOW + STFT_PAD_RIGHT;
+    const x = new Float32Array(n * W);
+    for (let c = 0; c < n; c++) {
+      const row = c * W;
+      const start = c * VAD_WINDOW;
+      for (let i = 0; i < VAD_CONTEXT; i++) {
+        const src = start - VAD_CONTEXT + i;
+        x[row + i] = src >= 0 ? samples[src]! : (prevContext ? prevContext[VAD_CONTEXT + src]! : 0);
+      }
+      for (let i = 0; i < VAD_WINDOW; i++) x[row + VAD_CONTEXT + i] = samples[start + i] ?? 0;
+      // reflect (torch ReflectionPad1d): pad[i] = x[L - 2 - i]
+      const L = VAD_CONTEXT + VAD_WINDOW;
+      for (let i = 0; i < STFT_PAD_RIGHT; i++) x[row + L + i] = x[row + L - 2 - i]!;
+    }
+    const inp = MlxArray.fromFloat32(x, [n, W, 1]);
+    let h = ops.conv1d(inp, this.#stftW, STFT_HOP, 0); // [n, 4, 258]
+    inp.dispose();
+    const cutoff = STFT_FILTERS / 2; // 129
+    const re = h.slice([0, 0, 0], [n, 4, cutoff]);
+    const im = h.slice([0, 0, cutoff], [n, 4, STFT_FILTERS]);
+    h.dispose();
+    const re2 = ops.square(re); const im2 = ops.square(im);
+    re.dispose(); im.dispose();
+    let mag = ops.add(re2, im2);
+    re2.dispose(); im2.dispose();
+    mag = dispose(mag, ops.sqrt(mag)); // [n, 4, 129]
+    let cur = mag;
+    const zero = MlxArray.fromFloat32(new Float32Array([0]), []);
+    for (let l = 0; l < 4; l++) {
+      cur = dispose(cur, ops.conv1d(cur, this.#convW[l]!, this.#convStride[l]!, 1));
+      cur = dispose(cur, ops.add(cur, this.#convB[l]!));
+      cur = dispose(cur, ops.maximum(cur, zero)); // ReLU
+    }
+    zero.dispose();
+    // cur: [n, 1, 128] → input gates [n, 512]
+    cur = dispose(cur, ops.reshape(cur, [n, LSTM_HIDDEN]));
+    let gates = ops.addmm(this.#bIhHh, cur, this.#wIhT);
+    cur.dispose();
+    const g = gates.toFloat32();
+    gates.dispose();
+    // host recurrence
+    const H = LSTM_HIDDEN;
+    const pre = new Float32Array(4 * H);
+    const out = new Float32Array(n);
+    const wHh = this.#wHh;
+    for (let t = 0; t < n; t++) {
+      const gi = t * 4 * H;
+      for (let r = 0; r < 4 * H; r++) {
+        let acc = g[gi + r]!;
+        const wr = r * H;
+        for (let c = 0; c < H; c++) acc += wHh[wr + c]! * hState[c]!;
+        pre[r] = acc;
+      }
+      for (let j = 0; j < H; j++) {
+        const i = sigmoid(pre[j]!);
+        const f = sigmoid(pre[H + j]!);
+        const gg = Math.tanh(pre[2 * H + j]!);
+        const o = sigmoid(pre[3 * H + j]!);
+        const c = f * cState[j]! + i * gg;
+        cState[j] = c;
+        hState[j] = o * Math.tanh(c);
+      }
+      let acc = this.#bFinal;
+      for (let j = 0; j < H; j++) acc += this.#wFinal[j]! * Math.max(0, hState[j]!);
+      out[t] = sigmoid(acc);
+    }
+    if (state) {
+      state.h = hState;
+      state.c = cState;
+      const ctx = new Float32Array(VAD_CONTEXT);
+      const tail = n * VAD_WINDOW - VAD_CONTEXT;
+      for (let i = 0; i < VAD_CONTEXT; i++) ctx[i] = samples[tail + i] ?? 0;
+      state.context = ctx;
+      state.chunks += n;
+    }
+    return out;
+  }
+
+  /** Fresh streaming state. */
+  static streamState(): VadStreamState {
+    return { h: new Float32Array(LSTM_HIDDEN), c: new Float32Array(LSTM_HIDDEN), context: null, chunks: 0 };
+  }
+
+  /** get_speech_timestamps over the probabilities (sample offsets). */
+  static speechTimestamps(probs: Float32Array, audioLengthSamples: number, opts: SpeechTimestampOptions = {}): VadSegment[] {
+    const sr = VAD_SAMPLE_RATE;
+    const window = VAD_WINDOW;
+    const threshold = opts.threshold ?? 0.5;
+    const minSpeech = sr * (opts.minSpeechDurationMs ?? 250) / 1000;
+    const speechPad = sr * (opts.speechPadMs ?? 30) / 1000;
+    const maxSpeechS = opts.maxSpeechDurationS ?? Infinity;
+    const maxSpeech = sr * maxSpeechS - window - 2 * speechPad;
+    const minSilence = sr * (opts.minSilenceDurationMs ?? 100) / 1000;
+    const minSilenceAtMax = sr * (opts.minSilenceAtMaxSpeechMs ?? 98) / 1000;
+    const useMaxPoss = opts.useMaxPossibleSilenceAtMaxSpeech ?? true;
+    const negThreshold = opts.negThreshold ?? Math.max(threshold - 0.15, 0.01);
+    let triggered = false;
+    const speeches: { start: number; end: number }[] = [];
+    let current: { start: number; end?: number } | null = null;
+    let tempEnd = 0; let prevEnd = 0; let nextStart = 0;
+    let possibleEnds: [number, number][] = [];
+    for (let i = 0; i < probs.length; i++) {
+      const p = probs[i]!;
+      const cur = window * i;
+      if (p >= threshold && tempEnd) {
+        const silDur = cur - tempEnd;
+        if (silDur > minSilenceAtMax) possibleEnds.push([tempEnd, silDur]);
+        tempEnd = 0;
+        if (nextStart < prevEnd) nextStart = cur;
+      }
+      if (p >= threshold && !triggered) { triggered = true; current = { start: cur }; continue; }
+      if (triggered && current && cur - current.start > maxSpeech) {
+        if (useMaxPoss && possibleEnds.length) {
+          let best = possibleEnds[0]!;
+          for (const pe of possibleEnds) if (pe[1] > best[1]) best = pe;
+          const [pEnd, dur] = best;
+          prevEnd = pEnd;
+          speeches.push({ start: current.start, end: prevEnd });
+          current = null;
+          nextStart = prevEnd + dur;
+          if (nextStart < prevEnd + cur) current = { start: nextStart };
+          else triggered = false;
+          prevEnd = nextStart = tempEnd = 0;
+          possibleEnds = [];
+        } else if (prevEnd) {
+          speeches.push({ start: current.start, end: prevEnd });
+          current = null;
+          if (nextStart < prevEnd) triggered = false; else current = { start: nextStart };
+          prevEnd = nextStart = tempEnd = 0;
+          possibleEnds = [];
+        } else {
+          speeches.push({ start: current.start, end: cur });
+          current = null;
+          prevEnd = nextStart = tempEnd = 0;
+          triggered = false;
+          possibleEnds = [];
+          continue;
+        }
+      }
+      if (p < negThreshold && triggered && current) {
+        if (!tempEnd) tempEnd = cur;
+        const silNow = cur - tempEnd;
+        if (!useMaxPoss && silNow > minSilenceAtMax) prevEnd = tempEnd;
+        if (silNow < minSilence) continue;
+        if (tempEnd - current.start > minSpeech) speeches.push({ start: current.start, end: tempEnd });
+        current = null;
+        prevEnd = nextStart = tempEnd = 0;
+        triggered = false;
+        possibleEnds = [];
+        continue;
+      }
+    }
+    if (current && audioLengthSamples - current.start > minSpeech) speeches.push({ start: current.start, end: audioLengthSamples });
+    for (let i = 0; i < speeches.length; i++) {
+      const s = speeches[i]!;
+      if (i === 0) s.start = Math.floor(Math.max(0, s.start - speechPad));
+      if (i !== speeches.length - 1) {
+        const nxt = speeches[i + 1]!;
+        const silence = nxt.start - s.end;
+        if (silence < 2 * speechPad) {
+          s.end += Math.floor(silence / 2);
+          nxt.start = Math.floor(Math.max(0, nxt.start - Math.floor(silence / 2)));
+        } else {
+          s.end = Math.floor(Math.min(audioLengthSamples, s.end + speechPad));
+          nxt.start = Math.floor(Math.max(0, nxt.start - speechPad));
+        }
+      } else s.end = Math.floor(Math.min(audioLengthSamples, s.end + speechPad));
+    }
+    return speeches;
+  }
+
+  /** Probabilities + segments in one call. */
+  detect(samples: Float32Array, opts: SpeechTimestampOptions = {}): { probs: Float32Array; segments: VadSegment[] } {
+    const probs = this.probs(samples);
+    return { probs, segments: SileroVad.speechTimestamps(probs, samples.length, opts) };
+  }
+
+  dispose(): void {
+    this.#stftW.dispose();
+    for (const a of [...this.#convW, ...this.#convB, this.#wIhT, this.#bIhHh]) a.dispose();
+  }
+}
+
+const sigmoid = (x: number) => 1 / (1 + Math.exp(-x));
+const dispose = (old: MlxArray, next: MlxArray): MlxArray => { old.dispose(); return next; };