decibri 4.4.1 → 5.0.0

package/src/decibri.d.ts

@@ -33,6 +33,34 @@ export interface VersionInfo {
   binding: string;
 }
 
+/**
+ * Voice-activity-detection config object, passed on the `vad` option to tune
+ * the detector's threshold and holdoff. The bare `vad: 'silero'` / `vad:
+ * 'energy'` shorthand selects a mode with its default policy; pass this object
+ * to override the threshold or holdoff.
+ */
+export interface VadOptions {
+  /**
+   * Which detector to run.
+   * - `'silero'`: Silero VAD v5 ML model (more accurate, ~1ms inference)
+   * - `'energy'`: RMS energy threshold (lightweight, no model)
+   */
+  model: 'silero' | 'energy';
+
+  /**
+   * Speech-detection threshold for the active mode.
+   * @default 0.5 for `'silero'`, 0.01 for `'energy'`
+   * @range 0–1
+   */
+  threshold?: number;
+
+  /**
+   * Milliseconds of sub-threshold audio before emitting `'silence'`.
+   * @default 300
+   */
+  holdoffMs?: number;
+}
+
 /** Constructor options for `Microphone`. */
 export interface MicrophoneOptions extends ReadableOptions {
   /**
@@ -43,9 +71,12 @@ export interface MicrophoneOptions extends ReadableOptions {
   sampleRate?: number;
 
   /**
-   * Number of input channels.
+   * Number of input channels. Mono only: the only accepted value is `1`, and a
+   * value greater than `1` throws a `RangeError` (multichannel capture is not
+   * supported) rather than being silently downmixed. The option is kept for
+   * forward compatibility: a future release may accept a value greater than `1`
+   * by delivering true interleaved multichannel.
    * @default 1
-   * @range 1–32
    */
   channels?: number;
 
@@ -76,36 +107,85 @@ export interface MicrophoneOptions extends ReadableOptions {
   dtype?: 'int16' | 'float32';
 
   /**
-   * Voice activity detection mode. One of:
+   * Voice activity detection. One of:
    * - `false`: disabled (default)
    * - `'silero'`: Silero VAD v5 ML model (more accurate, ~1ms inference)
    * - `'energy'`: RMS energy threshold (lightweight)
+   * - a `VadOptions` config object `{ model, threshold?, holdoffMs? }` to tune
+   *   the threshold and holdoff for the chosen model
    *
-   * When enabled, emits `'speech'` and `'silence'` events and updates `vadScore`.
-   * The legacy `vad: true` form is rejected; specify the mode explicitly.
+   * The string shorthand uses the mode's default threshold (0.5 for `'silero'`,
+   * 0.01 for `'energy'`) and a 300 ms holdoff; pass a `VadOptions` object to
+   * override them. When enabled, emits `'speech'` and `'silence'` events and
+   * updates `vadScore`. The legacy `vad: true` form is rejected; specify the
+   * mode explicitly.
    * @default false
    */
-  vad?: false | 'silero' | 'energy';
+  vad?: false | 'silero' | 'energy' | VadOptions;
 
   /**
-   * Speech-detection threshold for the active VAD mode.
-   * @default 0.5 for `'silero'`, 0.01 for `'energy'`
-   * @range 0–1
+   * Path to the Silero VAD ONNX model file.
+   * Only used when `vad` is `'silero'`.
+   * Defaults to `models/silero_vad.onnx` relative to the package.
    */
-  vadThreshold?: number;
+  modelPath?: string;
 
   /**
-   * Milliseconds of sub-threshold audio before emitting `'silence'`.
-   * @default 300
+   * Remove a constant (DC) offset from the captured audio with a one-pole
+   * DC-blocking high-pass. Set `true` to enable it; omit or set `false` to
+   * leave it off (the default), which keeps the capture path byte-identical.
+   * Runs first in the chain, before denoise, and is same-length with no added
+   * latency, so `vadScore` and the `speech` / `silence` events are unaffected.
+   * Pure DSP: no bundled file or download is needed.
+   * @default undefined
    */
-  vadHoldoff?: number;
+  dcRemoval?: boolean;
 
   /**
-   * Path to the Silero VAD ONNX model file.
-   * Only used when `vad` is `'silero'`.
-   * Defaults to `models/silero_vad.onnx` relative to the package.
+   * Single-channel speech enhancement (denoise) model applied to the captured
+   * audio. The only accepted value is `'fastenhancer-t'`; omit to leave denoise
+   * off (the default), which keeps the capture path unchanged. The bundled
+   * model ships with the package; no path is required.
+   *
+   * When set, the captured audio is denoised before delivery and the `'data'`
+   * chunks carry the enhanced signal. VAD reads the pre-enhancement signal, so
+   * `vadScore` and the `speech` / `silence` events are unaffected.
+   * @default undefined
    */
-  modelPath?: string;
+  denoise?: 'fastenhancer-t';
+
+  /**
+   * High-pass filter cutoff in Hz applied to the captured audio, removing
+   * low-frequency rumble below the voice band. The accepted values are `80` (an
+   * 80 Hz second-order Butterworth high-pass) and `100` (a 100 Hz one); omit to
+   * leave the high-pass off (the default), which keeps the capture path
+   * full-range. Runs after denoise in the chain. The closed value set is
+   * designed to grow (further cutoffs are additive) the way `denoise` grows.
+   * Out-of-set values raise a `RangeError`.
+   * @default undefined
+   */
+  highpass?: 80 | 100;
+
+  /**
+   * Automatic gain control target level in dBFS applied to the captured audio.
+   * Drives the running level toward this target with a smoothed, rate-limited
+   * gain. An integer in the range -40 to -3 (typical -18); omit to leave AGC
+   * off (the default), which keeps the level untouched. Runs after the
+   * high-pass step. Out-of-range values raise a `RangeError`.
+   * @default undefined
+   */
+  agc?: number;
+
+  /**
+   * Peak limiter ceiling in dBFS (sample-peak) applied to the captured audio.
+   * Holds the signal at or below this ceiling, the safety net that catches a
+   * transient the AGC's gain would let exceed full scale. A number in the range
+   * -3.0 to 0.0 (typical -1.0); omit to leave the limiter off (the default),
+   * which keeps the level untouched. Runs last in the chain, after the AGC step.
+   * Out-of-range values raise a `RangeError`.
+   * @default undefined
+   */
+  limiter?: number;
 }
 
 /**
@@ -158,6 +238,13 @@ export declare class Microphone extends Readable {
    */
   readonly vadScore: number;
 
+  /**
+   * Number of capture buffers dropped because the consumer could not keep pace.
+   * 0 while the consumer keeps up, or before capture starts. A rising value
+   * means audio is being dropped to bound memory.
+   */
+  readonly overrunCount: number;
+
   /** List all available audio input devices. */
   static devices(): MicrophoneInfo[];
 

package/src/decibri.js

@@ -72,25 +72,6 @@ function resolveBundledOrtPath() {
   }
 }
 
-// ─── RMS helper ──────────────────────────────────────────────────────────────
-
-function computeRMS(chunk, dtype) {
-  let sum = 0, n;
-  if (dtype === 'float32') {
-    const samples = new Float32Array(chunk.buffer, chunk.byteOffset, chunk.length / 4);
-    n = samples.length;
-    for (let i = 0; i < n; i++) sum += samples[i] * samples[i];
-  } else {
-    const samples = new Int16Array(chunk.buffer, chunk.byteOffset, chunk.length / 2);
-    n = samples.length;
-    for (let i = 0; i < n; i++) {
-      const s = samples[i] / 32768;
-      sum += s * s;
-    }
-  }
-  return n > 0 ? Math.sqrt(sum / n) : 0;
-}
-
 // ─── Microphone (Readable) ──────────────────────────────────────────────────
 
 class Microphone extends Readable {
@@ -111,15 +92,19 @@ class Microphone extends Readable {
 
     // ── Store config ───────────────────────────────────────────────────────
 
-    this._dtype = prepared.dtype;
     this._vad = prepared.vadEnabled;
-    this._vadMode = prepared.vadMode;
     this._vadThreshold = prepared.vadThreshold;
     this._vadHoldoff = prepared.vadHoldoff;
     this._vadScore = 0;
     this._isSpeaking = false;
     this._silenceTimer = null;
     this._started = false;
+    // Terminal once stop() runs: blocks _read() from restarting native capture
+    // while the end-of-stream push(null) is deferred past the flushed tail.
+    this._stopped = false;
+    // Set just before the deferred push(null); the data callback drops any
+    // straggler that arrives after end-of-stream rather than pushing past EOF.
+    this._ended = false;
 
     // ── Create or adopt native bridge ───────────────────────────────────────
 
@@ -153,10 +138,17 @@ class Microphone extends Readable {
       throw new RangeError('sample rate must be between 1000 and 384000');
     }
 
+    // Mono only: the capture path delivers a single channel. A value below 1
+    // is a plain range error; a value above 1 is rejected as multichannel
+    // (not silently downmixed) so a later move to true multichannel stays
+    // additive. The `channels` option is kept for that forward compatibility.
     const channels = options.channels ?? 1;
-    if (channels < 1 || channels > 32) {
+    if (channels < 1) {
       throw new RangeError('channels must be between 1 and 32');
     }
+    if (channels > 1) {
+      throw new RangeError('multichannel capture is not supported; channels must be 1 (mono)');
+    }
 
     const framesPerBuffer = options.framesPerBuffer ?? 1600;
     if (framesPerBuffer < 64 || framesPerBuffer > 65536) {
@@ -198,13 +190,25 @@ class Microphone extends Readable {
 
     // ── Validate VAD options ─────────────────────────────────────────────────
 
-    // Single vad union: false (disabled, default), 'silero', or 'energy'. The
-    // legacy two-flag form (vad: true plus vadMode) is rejected with a
-    // migration error. Energy and Silero are both computed in this wrapper;
-    // the union only selects which.
+    // vad selects the detector and (optionally) its threshold/holdoff policy.
+    // It accepts false (disabled, default), the 'silero'/'energy' shorthand
+    // (which uses the mode's default threshold and holdoff), or a config object
+    // { model, threshold, holdoffMs } to tune the policy. The legacy two-flag
+    // form (vad: true plus vadMode) and the flat vadThreshold/vadHoldoff
+    // options are rejected with a migration error. The threshold and holdoff
+    // live JS-side (the state machine runs in this wrapper); only the mode is
+    // passed to native.
+    if (options.vadThreshold !== undefined || options.vadHoldoff !== undefined) {
+      throw new TypeError(
+        'vadThreshold and vadHoldoff are no longer supported. ' +
+          "Pass them on the vad config object: vad: { model: 'silero', threshold: 0.5, holdoffMs: 300 }."
+      );
+    }
     const vad = options.vad ?? false;
     let vadEnabled;
     let vadMode;
+    let vadThreshold;
+    let vadHoldoff;
     if (vad === false) {
       vadEnabled = false;
       vadMode = 'energy'; // inert placeholder; ignored while disabled
@@ -215,23 +219,123 @@ class Microphone extends Readable {
     } else if (vad === 'silero' || vad === 'energy') {
       vadEnabled = true;
       vadMode = vad;
+    } else if (vad !== null && typeof vad === 'object' && !Array.isArray(vad)) {
+      // Config object form: { model, threshold?, holdoffMs? }. model is required
+      // and selects the detector; threshold and holdoffMs override the mode
+      // defaults when supplied.
+      const { model, threshold, holdoffMs } = vad;
+      if (model !== 'silero' && model !== 'energy') {
+        throw new TypeError(
+          `Invalid vad model: ${JSON.stringify(model)}. Expected 'silero' or 'energy'.`
+        );
+      }
+      vadEnabled = true;
+      vadMode = model;
+      if (threshold !== undefined) {
+        if (typeof threshold !== 'number' || Number.isNaN(threshold)) {
+          throw new TypeError('vad threshold must be a number');
+        }
+        if (threshold < 0 || threshold > 1) {
+          throw new RangeError('vad threshold must be between 0 and 1');
+        }
+        vadThreshold = threshold;
+      }
+      if (holdoffMs !== undefined) {
+        if (typeof holdoffMs !== 'number' || Number.isNaN(holdoffMs)) {
+          throw new TypeError('vad holdoffMs must be a number');
+        }
+        if (holdoffMs < 0) {
+          throw new RangeError('vad holdoffMs must be non-negative');
+        }
+        vadHoldoff = holdoffMs;
+      }
     } else {
       throw new TypeError(
-        `Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'silero', or 'energy'.`
+        `Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'silero', 'energy', or a config object { model, threshold, holdoffMs }.`
       );
     }
 
     let modelPath = undefined;
-    let ortLibraryPath = undefined;
     if (vadEnabled && vadMode === 'silero') {
       modelPath = options.modelPath || path.join(__dirname, '..', 'models', 'silero_vad.onnx');
       if (!fs.existsSync(modelPath)) {
         throw new Error(`Silero VAD model not found at ${modelPath}. Ensure the models/ directory is included in your installation.`);
       }
-      // Internal plumbing: inject the bundled ORT dylib path into the napi
-      // constructor. If resolution fails (unknown platform, platform package
-      // not installed), leaves ortLibraryPath as undefined and lets Rust fall
-      // through to ORT_DYLIB_PATH or surface a decibri-specific init error.
+    }
+
+    // ── DC removal ───────────────────────────────────────────────────────────
+
+    // A plain bool toggle for the one-pole DC-blocking high-pass, the first
+    // transform stage (before denoise). Absent or false leaves it off (the
+    // default), a byte-identical no-op. No range or closed-set check (it is just
+    // a bool); the value is threaded straight to the native config.
+    const dcRemoval = options.dcRemoval;
+
+    // ── Validate and resolve denoise ─────────────────────────────────────────
+
+    // Closed-set selector mirroring the Silero VAD shape: a model name resolves
+    // to a bundled ONNX file, absence leaves denoise off. The only accepted
+    // value is 'fastenhancer-t'; anything else is an explicit error rather than
+    // a silent miss. The bundled model file is resolved relative to the package
+    // exactly as the Silero model is.
+    const denoise = options.denoise;
+    let denoiseModelPath = undefined;
+    if (denoise !== undefined) {
+      if (denoise !== 'fastenhancer-t') {
+        throw new TypeError(
+          `Invalid denoise value: ${JSON.stringify(denoise)}. Expected 'fastenhancer-t'.`
+        );
+      }
+      denoiseModelPath = path.join(__dirname, '..', 'models', 'fastenhancer_t.onnx');
+      if (!fs.existsSync(denoiseModelPath)) {
+        throw new Error(`Denoise model not found at ${denoiseModelPath}. Ensure the models/ directory is included in your installation.`);
+      }
+    }
+
+    // ── Validate high-pass ───────────────────────────────────────────────────
+
+    // Closed growable numeric cutoff selector mirroring the denoise shape: a
+    // cutoff in Hz selects a filter, absence leaves the high-pass off. The
+    // accepted values are 80 and 100; anything else (an out-of-set cutoff or a
+    // non-number) is an explicit RangeError rather than a silent miss, matching
+    // the numeric range checks on agc and limiter. The filter is pure DSP with
+    // no bundled file, so there is nothing to resolve here, only the closed-set
+    // check.
+    const highpass = options.highpass;
+    if (highpass !== undefined && highpass !== 80 && highpass !== 100) {
+      throw new RangeError('highpass must be one of: 80, 100');
+    }
+
+    // ── Validate AGC ─────────────────────────────────────────────────────────
+
+    // AGC target level in dBFS: a number in [-40, -3] (typical -18) drives the
+    // captured level toward the target; absence leaves it off. Mirrors the
+    // sample-rate range check, a RangeError on an out-of-range numeric value;
+    // the native backstop and the Rust core guard the same range.
+    const agc = options.agc;
+    if (agc !== undefined && (agc < -40 || agc > -3)) {
+      throw new RangeError('agc target level must be between -40 and -3');
+    }
+
+    // ── Validate limiter ─────────────────────────────────────────────────────
+
+    // Sample-peak ceiling in dBFS: a number in [-3.0, 0.0] (typical -1.0) holds
+    // the captured signal at or below the ceiling, catching a peak the AGC would
+    // let through; absence leaves it off. Mirrors the agc range check, a
+    // RangeError on an out-of-range numeric value; the native backstop and the
+    // Rust core guard the same range.
+    const limiter = options.limiter;
+    if (limiter !== undefined && (limiter < -3.0 || limiter > 0.0)) {
+      throw new RangeError('limiter ceiling must be between -3.0 and 0.0');
+    }
+
+    // Internal plumbing: inject the bundled ORT dylib path into the napi
+    // constructor whenever an ONNX stage loads (Silero VAD or denoise). If
+    // resolution fails (unknown platform, platform package not installed), this
+    // is left undefined and Rust falls through to ORT_DYLIB_PATH or surfaces a
+    // decibri-specific init error.
+    let ortLibraryPath = undefined;
+    if ((vadEnabled && vadMode === 'silero') || denoise !== undefined) {
       ortLibraryPath = resolveBundledOrtPath();
     }
 
@@ -239,17 +343,27 @@ class Microphone extends Readable {
       dtype,
       vadEnabled,
       vadMode,
-      vadThreshold: options.vadThreshold ?? (vadMode === 'silero' ? 0.5 : 0.01),
-      vadHoldoff: options.vadHoldoff ?? 300,
+      vadThreshold: vadThreshold ?? (vadMode === 'silero' ? 0.5 : 0.01),
+      vadHoldoff: vadHoldoff ?? 300,
       nativeOptions: {
         sampleRate,
         channels,
         framesPerBuffer,
         format: dtype,
         device: resolvedDevice,
-        vadMode,
+        // Pass the mode to native only when VAD is enabled. When disabled the
+        // local vadMode is an inert 'energy' placeholder; sending it would make
+        // native compute the energy score for a microphone that did not ask for
+        // VAD. Absent means VAD off in native.
+        vadMode: vadEnabled ? vadMode : undefined,
         modelPath,
+        dcRemoval,
+        denoise,
+        denoiseModelPath,
         ortLibraryPath,
+        highpass,
+        agc,
+        limiter,
       },
     };
   }
@@ -287,16 +401,31 @@ class Microphone extends Readable {
 
   /** @internal */
   _read() {
-    if (this._started) return;
+    // Never (re)start native capture once stopped: stop() defers the
+    // end-of-stream push(null), and a _read() in that window would otherwise
+    // reopen the device.
+    if (this._started || this._stopped) return;
     this._started = true;
 
     this._native.start((err, chunk) => {
       if (err) {
         this._started = false;
+        // A start()-time failure is delivered here as the raw native error (not
+        // via wrapNativeError), so no decibri `code` is attached on the 'error'
+        // event, as with device-open failures; the dedicated MODEL_LOAD_FAILED
+        // code is reachable through wrapNativeError, not on this streaming path.
         this.destroy(err);
         return;
       }
 
+      // On close the native pump flushes the buffered tail; that final data
+      // callback can run after stop() has begun ending the stream. Once the
+      // end-of-stream push(null) has been issued (or the stream was destroyed),
+      // drop any straggler rather than pushing past EOF.
+      if (this._ended || this.destroyed) {
+        return;
+      }
+
       // push returns false when the consumer is slow. We can't pause a mic,
       // but we surface the backpressure warning so callers can react.
       if (!this.push(chunk)) {
@@ -304,27 +433,15 @@ class Microphone extends Readable {
       }
 
       if (this._vad) {
-        if (this._vadMode === 'silero') {
-          const prob = this._native.vadProbability;
-          this._processVadSilero(prob);
-        } else {
-          this._processVadEnergy(chunk);
-        }
+        // Both modes read the score from native: the Silero speech probability
+        // or, in energy mode, the RMS of the pre-enhancement signal. The native
+        // pump computes both on the signal before the opt-in enhancement step,
+        // so enabling enhancement does not change detection in either mode.
+        this._processVadValue(this._native.vadProbability);
       }
     });
   }
 
-  /** @internal Energy-based VAD (RMS threshold) */
-  _processVadEnergy(chunk) {
-    const rms = computeRMS(chunk, this._dtype);
-    this._processVadValue(rms);
-  }
-
-  /** @internal Silero ML-based VAD (reads probability from native) */
-  _processVadSilero(probability) {
-    this._processVadValue(probability);
-  }
-
   /** @internal Common speech/silence state machine */
   _processVadValue(value) {
     this._vadScore = value;
@@ -350,10 +467,23 @@ class Microphone extends Readable {
   stop() {
     if (!this._started) return;
     this._started = false;
+    this._stopped = true;
     this._native.stop();
     clearTimeout(this._silenceTimer);
     this._silenceTimer = null;
-    this.push(null); // signals stream end
+    // The native pump flushes any buffered tail on close; those final data
+    // callbacks are queued on the event loop and run before a setImmediate
+    // scheduled now. Defer the end-of-stream push(null) past them so the final
+    // short chunk reaches consumers without landing after EOF
+    // (ERR_STREAM_PUSH_AFTER_EOF). `_ended` is set first so the data callback
+    // drops any straggler that somehow arrives after this point.
+    setImmediate(() => {
+      // A device error in the same tick may have destroyed the stream before
+      // this runs; don't end an already-destroyed stream.
+      if (this.destroyed) return;
+      this._ended = true;
+      this.push(null); // signals stream end
+    });
   }
 
   /**
@@ -366,7 +496,9 @@ class Microphone extends Readable {
 
   /**
    * Most recent VAD score for the active mode: the Silero speech probability
-   * in 'silero' mode, the normalized RMS of the last chunk in 'energy' mode.
+   * in 'silero' mode, the normalized RMS of the pre-enhancement signal in
+   * 'energy' mode. Both are computed natively on the signal before any opt-in
+   * enhancement step, so enabling enhancement does not change the score.
    * 0 when VAD is disabled or before the first chunk is processed.
    * @returns {number}
    */
@@ -374,6 +506,16 @@ class Microphone extends Readable {
     return this._vadScore;
   }
 
+  /**
+   * Number of capture buffers dropped because the consumer could not keep
+   * pace. 0 while the consumer keeps up, or before capture starts. A rising
+   * value means audio is being dropped to bound memory.
+   * @returns {number}
+   */
+  get overrunCount() {
+    return this._native.overrunCount;
+  }
+
   /**
    * List all available input devices on the system.
    * @returns {Array<{index: number, name: string, id: string, maxInputChannels: number, defaultSampleRate: number, isDefault: boolean}>}

package/src/errors.js

@@ -72,6 +72,7 @@ const DEVICE_CODES = [
 const ORT_CODES = [
   ['decibri: failed to initialize ONNX Runtime', 'ORT_INIT_FAILED'],
   ['Failed to load Silero VAD model from', 'VAD_MODEL_LOAD_FAILED'],
+  ['Failed to load model from', 'MODEL_LOAD_FAILED'],
   ['Failed to create ort session builder', 'ORT_SESSION_BUILD_FAILED'],
   ['Failed to set ort threads', 'ORT_THREADS_CONFIG_FAILED'],
   ['Silero VAD inference failed', 'ORT_INFERENCE_FAILED'],
@@ -130,6 +131,19 @@ function wrapNativeError(err) {
     return new OrtError(msg, 'ORT_TENSOR_EXTRACT_FAILED');
   }
 
+  // Runtime device/driver failure during streaming. Distinct from the
+  // enumeration/selection DeviceError family above (which mirrors the core's
+  // "Device errors"): this is the core's "Stream errors" DeviceFailed, surfaced
+  // as a base DecibriError with a dedicated code.
+  if (msg.startsWith('decibri: audio device error:')) {
+    return new DecibriError(msg, 'DEVICE_FAILED');
+  }
+  // Non-ORT ONNX backend failure: the reserved backend catch-all, surfaced as a
+  // base DecibriError with a dedicated code (not an OrtError).
+  if (msg.startsWith('ONNX backend error from')) {
+    return new DecibriError(msg, 'ONNX_BACKEND_FAILED');
+  }
+
   // Any other error from the native constructor is still a decibri error.
   return new DecibriError(msg, 'DECIBRI_ERROR');
 }