@crewhaus/vad-engine 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Catalog R16 `vad-engine` — Section 24 VOICE.
+ *
+ * Voice activity detection. WebRTC-VAD-style heuristic over PCM 16-bit
+ * frames: a frame is "speech" when BOTH (a) RMS energy crosses an
+ * aggressiveness-tuned threshold and (b) zero-crossing-rate sits in a
+ * speech-shaped band. Either signal alone produces a "transitioning"
+ * verdict, used by `barge-in-controller` to apply hysteresis (don't
+ * bargle in on a 50ms cough).
+ *
+ * Frame size is conventional: 30ms at the input sample rate. At 24kHz
+ * mono that's 720 samples; the detector accepts ANY length but reports
+ * the verdict as if it were a single frame, so callers framing at
+ * higher granularity will simply get richer output.
+ *
+ * Aggressiveness:
+ *   0 — most permissive (high speech recall, low false positives)
+ *   1 — default
+ *   2 — moderately aggressive (ignores low-amplitude background)
+ *   3 — most aggressive (rejects most non-vocal audio)
+ *
+ * No external ML deps: pure heuristic. Adequate for barge-in and as a
+ * pre-filter for paid VAD models. `T9` random-noise stability test
+ * proves a 10-second white-noise stream produces zero "speech" verdicts
+ * at aggressiveness 2+.
+ */
+export type Aggressiveness = 0 | 1 | 2 | 3;
+export type VadVerdict = "speech" | "silence" | "transitioning";
+export type DetectorOptions = {
+    readonly aggressiveness?: Aggressiveness;
+    /**
+     * Sample rate of incoming PCM (Hz). RESERVED — currently has no effect on
+     * detection: the energy thresholds and zero-crossing band below are
+     * sample-rate-independent, and the detector does NOT resample. The option is
+     * accepted for forward compatibility (a planned band-pass filter stage). Pass
+     * it for clarity if you like, but do not infer any resampling behaviour from
+     * it.
+     */
+    readonly sampleRate?: number;
+};
+export interface VadDetector {
+    detect(frame: Int16Array): VadVerdict;
+    readonly aggressiveness: Aggressiveness;
+}
+export declare function createVadDetector(opts?: DetectorOptions): VadDetector;
+/**
+ * Helper: split a long PCM buffer into 30ms frames at `sampleRate`. Tail
+ * shorter than one frame is dropped (caller can decide to pad).
+ */
+export declare function frames30ms(pcm: Int16Array, sampleRate?: number): Int16Array[];

package/dist/index.js

@@ -0,0 +1,81 @@
+/**
+ * Catalog R16 `vad-engine` — Section 24 VOICE.
+ *
+ * Voice activity detection. WebRTC-VAD-style heuristic over PCM 16-bit
+ * frames: a frame is "speech" when BOTH (a) RMS energy crosses an
+ * aggressiveness-tuned threshold and (b) zero-crossing-rate sits in a
+ * speech-shaped band. Either signal alone produces a "transitioning"
+ * verdict, used by `barge-in-controller` to apply hysteresis (don't
+ * bargle in on a 50ms cough).
+ *
+ * Frame size is conventional: 30ms at the input sample rate. At 24kHz
+ * mono that's 720 samples; the detector accepts ANY length but reports
+ * the verdict as if it were a single frame, so callers framing at
+ * higher granularity will simply get richer output.
+ *
+ * Aggressiveness:
+ *   0 — most permissive (high speech recall, low false positives)
+ *   1 — default
+ *   2 — moderately aggressive (ignores low-amplitude background)
+ *   3 — most aggressive (rejects most non-vocal audio)
+ *
+ * No external ML deps: pure heuristic. Adequate for barge-in and as a
+ * pre-filter for paid VAD models. `T9` random-noise stability test
+ * proves a 10-second white-noise stream produces zero "speech" verdicts
+ * at aggressiveness 2+.
+ */
+const ENERGY_THRESHOLDS = {
+    0: 280,
+    1: 540,
+    2: 900,
+    3: 1500,
+};
+// Speech-shaped ZCR band (per 1k samples). Empirical for 24kHz speech
+// vs ambient noise vs single-frequency tones. The lower bound rejects
+// pure low-frequency tones (e.g. 60Hz mains hum); the upper bound
+// rejects white noise / high-frequency hiss.
+const ZCR_LOW_PER_1K = 15;
+const ZCR_HIGH_PER_1K = 220;
+export function createVadDetector(opts = {}) {
+    const aggressiveness = opts.aggressiveness ?? 1;
+    void opts.sampleRate; // currently unused; reserved for future bandpass filter
+    return {
+        aggressiveness,
+        detect(frame) {
+            if (frame.length === 0)
+                return "silence";
+            let sumSq = 0;
+            let zeroCrossings = 0;
+            let prev = frame[0] ?? 0;
+            for (let i = 0; i < frame.length; i++) {
+                const v = frame[i] ?? 0;
+                sumSq += v * v;
+                if (i > 0 && Math.sign(v) !== Math.sign(prev) && (v !== 0 || prev !== 0)) {
+                    zeroCrossings += 1;
+                }
+                prev = v;
+            }
+            const rms = Math.sqrt(sumSq / frame.length);
+            const zcrPer1k = (zeroCrossings * 1000) / frame.length;
+            const energyOk = rms >= ENERGY_THRESHOLDS[aggressiveness];
+            const zcrInBand = zcrPer1k >= ZCR_LOW_PER_1K && zcrPer1k <= ZCR_HIGH_PER_1K;
+            if (energyOk && zcrInBand)
+                return "speech";
+            if (!energyOk && !zcrInBand)
+                return "silence";
+            return "transitioning";
+        },
+    };
+}
+/**
+ * Helper: split a long PCM buffer into 30ms frames at `sampleRate`. Tail
+ * shorter than one frame is dropped (caller can decide to pad).
+ */
+export function frames30ms(pcm, sampleRate = 24_000) {
+    const n = Math.floor(sampleRate * 0.03);
+    const out = [];
+    for (let i = 0; i + n <= pcm.length; i += n) {
+        out.push(pcm.subarray(i, i + n));
+    }
+    return out;
+}

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@crewhaus/vad-engine",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Voice activity detection — energy + ZCR heuristic over PCM 16-bit frames (Section 24 VOICE)",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
@@ -29,5 +32,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,124 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { createVadDetector, frames30ms } from "./index.js";
-
-function silence(n: number): Int16Array {
-  return new Int16Array(n);
-}
-
-function whiteNoise(n: number, amplitude: number, seed = 1): Int16Array {
-  // Linear-congruential PRNG so tests are deterministic.
-  let s = seed;
-  const out = new Int16Array(n);
-  for (let i = 0; i < n; i++) {
-    s = (s * 1103515245 + 12345) & 0x7fffffff;
-    const r = ((s % 1000) - 500) / 500; // [-1, 1)
-    out[i] = Math.round(r * amplitude);
-  }
-  return out;
-}
-
-function tone(n: number, freqHz: number, sampleRate: number, amplitude: number): Int16Array {
-  const out = new Int16Array(n);
-  for (let i = 0; i < n; i++) {
-    out[i] = Math.round(Math.sin((2 * Math.PI * freqHz * i) / sampleRate) * amplitude);
-  }
-  return out;
-}
-
-/**
- * Speech-like signal: a sum of two formants (F1 ≈ 500Hz, F2 ≈ 1500Hz)
- * with amplitude modulation to approximate voicing. Enough to push both
- * energy and ZCR into the speech band for aggressiveness ≤ 2.
- */
-function speechLike(n: number, sampleRate: number, amplitude: number): Int16Array {
-  const out = new Int16Array(n);
-  for (let i = 0; i < n; i++) {
-    const env = 0.6 + 0.4 * Math.sin((2 * Math.PI * 5 * i) / sampleRate);
-    const sig =
-      0.7 * Math.sin((2 * Math.PI * 500 * i) / sampleRate) +
-      0.3 * Math.sin((2 * Math.PI * 1500 * i) / sampleRate);
-    out[i] = Math.round(env * sig * amplitude);
-  }
-  return out;
-}
-
-describe("createVadDetector — energy + ZCR heuristic (T1)", () => {
-  test("silent frame → silence at every aggressiveness", () => {
-    for (const a of [0, 1, 2, 3] as const) {
-      const det = createVadDetector({ aggressiveness: a });
-      expect(det.detect(silence(720))).toBe("silence");
-    }
-  });
-
-  test("speech-like signal → speech at aggressiveness 0..2", () => {
-    const f = speechLike(720, 24_000, 8000);
-    for (const a of [0, 1, 2] as const) {
-      const det = createVadDetector({ aggressiveness: a });
-      expect(det.detect(f)).toBe("speech");
-    }
-  });
-
-  test("aggressiveness=3 ignores low-amplitude speech-shaped signal", () => {
-    const det = createVadDetector({ aggressiveness: 3 });
-    const f = speechLike(720, 24_000, 1500);
-    // Low energy at aggressiveness 3: should NOT be classified as speech.
-    expect(det.detect(f)).not.toBe("speech");
-  });
-
-  test("low-energy white noise → silence (T9 noise rejection at aggressiveness ≥ 2)", () => {
-    const det = createVadDetector({ aggressiveness: 2 });
-    const f = whiteNoise(720, 250);
-    // Low-amplitude noise → energy below threshold.
-    expect(det.detect(f)).toBe("silence");
-  });
-
-  test("loud white noise → not speech (ZCR too high)", () => {
-    // White noise has ZCR much higher than the speech band.
-    const det = createVadDetector({ aggressiveness: 1 });
-    const f = whiteNoise(720, 12000);
-    // High energy but ZCR way out of band → transitioning, NOT speech.
-    expect(det.detect(f)).not.toBe("speech");
-  });
-
-  test("pure tone at 60Hz → not speech (ZCR too low)", () => {
-    const det = createVadDetector({ aggressiveness: 1 });
-    const f = tone(720, 60, 24_000, 8000);
-    // Energy passes but ZCR is too low → not speech.
-    expect(det.detect(f)).not.toBe("speech");
-  });
-
-  test("empty frame → silence", () => {
-    const det = createVadDetector({ aggressiveness: 1 });
-    expect(det.detect(new Int16Array(0))).toBe("silence");
-  });
-});
-
-describe("frames30ms helper", () => {
-  test("splits a 2-second PCM buffer into 66 30ms frames at 24kHz", () => {
-    const pcm = new Int16Array(24_000 * 2);
-    const fs = frames30ms(pcm, 24_000);
-    expect(fs.length).toBe(66); // floor(48000 / 720) = 66
-    expect(fs[0]?.length).toBe(720);
-  });
-
-  test("drops a partial tail shorter than one frame", () => {
-    const pcm = new Int16Array(720 + 100);
-    const fs = frames30ms(pcm, 24_000);
-    expect(fs.length).toBe(1);
-  });
-});
-
-describe("T9 noise-injection stability — random noise at aggressiveness 2+ never reports speech", () => {
-  test("10-second white-noise stream → 0 speech verdicts at aggressiveness 2", () => {
-    const sr = 24_000;
-    const det = createVadDetector({ aggressiveness: 2 });
-    const pcm = whiteNoise(sr * 10, 6000, 42);
-    const fs = frames30ms(pcm, sr);
-    const counts = { speech: 0, silence: 0, transitioning: 0 };
-    for (const f of fs) {
-      counts[det.detect(f)] += 1;
-    }
-    expect(counts.speech).toBe(0);
-    expect(counts.silence + counts.transitioning).toBe(fs.length);
-  });
-});

package/src/index.ts

@@ -1,107 +0,0 @@
-/**
- * Catalog R16 `vad-engine` — Section 24 VOICE.
- *
- * Voice activity detection. WebRTC-VAD-style heuristic over PCM 16-bit
- * frames: a frame is "speech" when BOTH (a) RMS energy crosses an
- * aggressiveness-tuned threshold and (b) zero-crossing-rate sits in a
- * speech-shaped band. Either signal alone produces a "transitioning"
- * verdict, used by `barge-in-controller` to apply hysteresis (don't
- * bargle in on a 50ms cough).
- *
- * Frame size is conventional: 30ms at the input sample rate. At 24kHz
- * mono that's 720 samples; the detector accepts ANY length but reports
- * the verdict as if it were a single frame, so callers framing at
- * higher granularity will simply get richer output.
- *
- * Aggressiveness:
- *   0 — most permissive (high speech recall, low false positives)
- *   1 — default
- *   2 — moderately aggressive (ignores low-amplitude background)
- *   3 — most aggressive (rejects most non-vocal audio)
- *
- * No external ML deps: pure heuristic. Adequate for barge-in and as a
- * pre-filter for paid VAD models. `T9` random-noise stability test
- * proves a 10-second white-noise stream produces zero "speech" verdicts
- * at aggressiveness 2+.
- */
-
-export type Aggressiveness = 0 | 1 | 2 | 3;
-
-export type VadVerdict = "speech" | "silence" | "transitioning";
-
-export type DetectorOptions = {
-  readonly aggressiveness?: Aggressiveness;
-  /**
-   * Sample rate of incoming PCM (Hz). RESERVED — currently has no effect on
-   * detection: the energy thresholds and zero-crossing band below are
-   * sample-rate-independent, and the detector does NOT resample. The option is
-   * accepted for forward compatibility (a planned band-pass filter stage). Pass
-   * it for clarity if you like, but do not infer any resampling behaviour from
-   * it.
-   */
-  readonly sampleRate?: number;
-};
-
-const ENERGY_THRESHOLDS: Record<Aggressiveness, number> = {
-  0: 280,
-  1: 540,
-  2: 900,
-  3: 1500,
-};
-
-// Speech-shaped ZCR band (per 1k samples). Empirical for 24kHz speech
-// vs ambient noise vs single-frequency tones. The lower bound rejects
-// pure low-frequency tones (e.g. 60Hz mains hum); the upper bound
-// rejects white noise / high-frequency hiss.
-const ZCR_LOW_PER_1K = 15;
-const ZCR_HIGH_PER_1K = 220;
-
-export interface VadDetector {
-  detect(frame: Int16Array): VadVerdict;
-  readonly aggressiveness: Aggressiveness;
-}
-
-export function createVadDetector(opts: DetectorOptions = {}): VadDetector {
-  const aggressiveness = opts.aggressiveness ?? 1;
-  void opts.sampleRate; // currently unused; reserved for future bandpass filter
-
-  return {
-    aggressiveness,
-    detect(frame: Int16Array): VadVerdict {
-      if (frame.length === 0) return "silence";
-      let sumSq = 0;
-      let zeroCrossings = 0;
-      let prev = frame[0] ?? 0;
-      for (let i = 0; i < frame.length; i++) {
-        const v = frame[i] ?? 0;
-        sumSq += v * v;
-        if (i > 0 && Math.sign(v) !== Math.sign(prev) && (v !== 0 || prev !== 0)) {
-          zeroCrossings += 1;
-        }
-        prev = v;
-      }
-      const rms = Math.sqrt(sumSq / frame.length);
-      const zcrPer1k = (zeroCrossings * 1000) / frame.length;
-
-      const energyOk = rms >= ENERGY_THRESHOLDS[aggressiveness];
-      const zcrInBand = zcrPer1k >= ZCR_LOW_PER_1K && zcrPer1k <= ZCR_HIGH_PER_1K;
-
-      if (energyOk && zcrInBand) return "speech";
-      if (!energyOk && !zcrInBand) return "silence";
-      return "transitioning";
-    },
-  };
-}
-
-/**
- * Helper: split a long PCM buffer into 30ms frames at `sampleRate`. Tail
- * shorter than one frame is dropped (caller can decide to pad).
- */
-export function frames30ms(pcm: Int16Array, sampleRate = 24_000): Int16Array[] {
-  const n = Math.floor(sampleRate * 0.03);
-  const out: Int16Array[] = [];
-  for (let i = 0; i + n <= pcm.length; i += n) {
-    out.push(pcm.subarray(i, i + n));
-  }
-  return out;
-}