decibri 3.4.2 → 4.1.0

package/src/decibri.js

@@ -4,7 +4,18 @@ const { Readable } = require('stream');
 const path = require('path');
 const fs = require('fs');
 const { DecibriBridge } = require('../index.js');
-const { wrapNativeError } = require('./errors');
+const {
+  wrapNativeError,
+  DecibriError,
+  DeviceError,
+  OrtError,
+  OrtPathError,
+} = require('./errors');
+
+// The npm package version, reported as `binding` by version(). Read from
+// package.json so it tracks the published package and cannot drift from a
+// hardcoded string.
+const PACKAGE_VERSION = require('../package.json').version;
 
 // ─── Bundled ONNX Runtime path resolution ────────────────────────────────────
 
@@ -63,9 +74,9 @@ function resolveBundledOrtPath() {
 
 // ─── RMS helper ──────────────────────────────────────────────────────────────
 
-function computeRMS(chunk, format) {
+function computeRMS(chunk, dtype) {
   let sum = 0, n;
-  if (format === 'float32') {
+  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];
@@ -80,15 +91,61 @@ function computeRMS(chunk, format) {
   return n > 0 ? Math.sqrt(sum / n) : 0;
 }
 
-// ─── Decibri (Readable) ─────────────────────────────────────────────────────
+// ─── Microphone (Readable) ──────────────────────────────────────────────────
 
-class Decibri extends Readable {
+class Microphone extends Readable {
   /**
-   * @param {import('./decibri').DecibriOptions} [options]
+   * @param {import('./decibri').MicrophoneOptions} [options]
+   * @param {{ prepared: object, native: object }} [_internal] Internal: a
+   *   pre-resolved options bundle and an already-constructed native bridge,
+   *   passed by the async `Microphone.open()` factory so the heavy open work
+   *   (the Silero model load) is not repeated on the event loop. Not part of
+   *   the public API.
    */
-  constructor(options = {}) {
+  constructor(options = {}, _internal = undefined) {
     super({ highWaterMark: options.highWaterMark, objectMode: false });
 
+    // Validate and resolve options once. The async factory passes its already
+    // resolved bundle through `_internal` to avoid recomputing it.
+    const prepared = _internal ? _internal.prepared : Microphone._prepareOptions(options);
+
+    // ── 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;
+
+    // ── Create or adopt native bridge ───────────────────────────────────────
+
+    if (_internal) {
+      // Built off the event loop by Microphone.open(); already wrapped.
+      this._native = _internal.native;
+    } else {
+      try {
+        this._native = new DecibriBridge(prepared.nativeOptions);
+      } catch (err) {
+        throw wrapNativeError(err);
+      }
+    }
+  }
+
+  /**
+   * Validate the constructor options and resolve them into the native options
+   * object plus the wrapper-side state. Throws the same `RangeError` /
+   * `TypeError` / `Error` as the constructor on invalid input. Shared by the
+   * synchronous constructor and the async `open()` factory so both validate
+   * identically. Does no native open work beyond the numeric-device bounds
+   * check (a fast device enumeration).
+   * @internal
+   * @param {import('./decibri').MicrophoneOptions} options
+   */
+  static _prepareOptions(options) {
     // ── Validate options ───────────────────────────────────────────────────
 
     const sampleRate = options.sampleRate ?? 16000;
@@ -106,33 +163,23 @@ class Decibri extends Readable {
       throw new RangeError('frames per buffer must be between 64 and 65536');
     }
 
-    const format = options.format ?? 'int16';
-    if (format !== 'int16' && format !== 'float32') {
-      throw new TypeError("format must be 'int16' or 'float32'");
+    const dtype = options.dtype ?? 'int16';
+    if (dtype !== 'int16' && dtype !== 'float32') {
+      throw new TypeError("dtype must be 'int16' or 'float32'");
     }
 
     // ── Resolve device ──────────────────────────────────────────────────────
 
+    // Name and multi-match resolution are delegated to the core, which owns
+    // the renamed-vocabulary errors (MicrophoneNotFound / MultipleDevicesMatch).
+    // A string name and an { id } object are passed straight through to the
+    // native addon. Only the numeric index keeps a client-side bounds check,
+    // for a clean Node-side RangeError without a round-trip.
     let resolvedDevice = options.device;
-    if (typeof options.device === 'string') {
-      const lower = options.device.toLowerCase();
-      const matches = DecibriBridge.devices().filter(d =>
-        d.name.toLowerCase().includes(lower)
-      );
-      if (matches.length === 0) {
-        throw new TypeError(`No audio input device found matching "${options.device}"`);
-      }
-      if (matches.length > 1) {
-        const names = matches.map(d => `  [${d.index}] ${d.name}`).join('\n');
-        throw new TypeError(
-          `Multiple devices match "${options.device}":\n${names}\nUse a more specific name or pass the device index directly.`
-        );
-      }
-      resolvedDevice = matches[0].index;
-    } else if (typeof options.device === 'number') {
+    if (typeof options.device === 'number') {
       const devices = DecibriBridge.devices();
       if (options.device < 0 || options.device >= devices.length) {
-        throw new RangeError('device index out of range. Call Decibri.devices() to list available devices');
+        throw new RangeError('device index out of range. Call Microphone.devices() to list available devices');
       }
       resolvedDevice = options.device;
     } else if (
@@ -151,14 +198,32 @@ class Decibri extends Readable {
 
     // ── Validate VAD options ─────────────────────────────────────────────────
 
-    const vadMode = options.vadMode ?? 'energy';
-    if (vadMode !== 'energy' && vadMode !== 'silero') {
-      throw new TypeError("vadMode must be 'energy' or 'silero'");
+    // 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.
+    const vad = options.vad ?? false;
+    let vadEnabled;
+    let vadMode;
+    if (vad === false) {
+      vadEnabled = false;
+      vadMode = 'energy'; // inert placeholder; ignored while disabled
+    } else if (vad === true) {
+      throw new TypeError(
+        "vad: true is no longer supported. Specify the mode explicitly: vad: 'silero' or vad: 'energy'."
+      );
+    } else if (vad === 'silero' || vad === 'energy') {
+      vadEnabled = true;
+      vadMode = vad;
+    } else {
+      throw new TypeError(
+        `Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'silero', or 'energy'.`
+      );
     }
 
     let modelPath = undefined;
     let ortLibraryPath = undefined;
-    if (vadMode === 'silero' && options.vad) {
+    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.`);
@@ -170,33 +235,54 @@ class Decibri extends Readable {
       ortLibraryPath = resolveBundledOrtPath();
     }
 
-    // ── Store config ───────────────────────────────────────────────────────
-
-    this._format = format;
-    this._vad = options.vad || false;
-    this._vadMode = vadMode;
-    this._vadThreshold = options.vadThreshold ?? (vadMode === 'silero' ? 0.5 : 0.01);
-    this._vadHoldoff = options.vadHoldoff ?? 300;
-    this._isSpeaking = false;
-    this._silenceTimer = null;
-    this._started = false;
-
-    // ── Create native bridge ───────────────────────────────────────────────
-
-    try {
-      this._native = new DecibriBridge({
+    return {
+      dtype,
+      vadEnabled,
+      vadMode,
+      vadThreshold: options.vadThreshold ?? (vadMode === 'silero' ? 0.5 : 0.01),
+      vadHoldoff: options.vadHoldoff ?? 300,
+      nativeOptions: {
         sampleRate,
         channels,
         framesPerBuffer,
-        format,
+        format: dtype,
         device: resolvedDevice,
-        vadMode: (options.vad && vadMode === 'silero') ? 'silero' : 'energy',
+        vadMode,
         modelPath,
         ortLibraryPath,
-      });
+      },
+    };
+  }
+
+  /**
+   * Construct a Microphone without blocking the event loop on the open work.
+   *
+   * The synchronous `new Microphone(...)` constructor loads the Silero VAD
+   * model inline when `vad: 'silero'` is set, which blocks the event loop for
+   * roughly 100 to 500 ms on a cold cache. This static factory runs that load
+   * (and device resolution) on the native thread pool and resolves to a ready
+   * instance, so latency-sensitive callers (voice pipelines, websocket
+   * handlers) do not stall. The synchronous constructor remains available and
+   * unchanged.
+   *
+   * Mirrors the Python `AsyncMicrophone.open()` factory. Options are identical
+   * to the constructor. A failed open (bad model path, unknown device, ORT
+   * load failure) rejects the returned Promise with the matching error class
+   * (`RangeError` / `TypeError` for invalid options, `DeviceError` / `OrtError`
+   * / `OrtPathError` for native failures), rather than throwing synchronously.
+   *
+   * @param {import('./decibri').MicrophoneOptions} [options]
+   * @returns {Promise<Microphone>}
+   */
+  static async open(options = {}) {
+    const prepared = Microphone._prepareOptions(options);
+    let native;
+    try {
+      native = await DecibriBridge.openAsync(prepared.nativeOptions);
     } catch (err) {
       throw wrapNativeError(err);
     }
+    return new Microphone(options, { prepared, native });
   }
 
   /** @internal */
@@ -230,7 +316,7 @@ class Decibri extends Readable {
 
   /** @internal Energy-based VAD (RMS threshold) */
   _processVadEnergy(chunk) {
-    const rms = computeRMS(chunk, this._format);
+    const rms = computeRMS(chunk, this._dtype);
     this._processVadValue(rms);
   }
 
@@ -241,6 +327,7 @@ class Decibri extends Readable {
 
   /** @internal Common speech/silence state machine */
   _processVadValue(value) {
+    this._vadScore = value;
     if (value >= this._vadThreshold) {
       clearTimeout(this._silenceTimer);
       this._silenceTimer = null;
@@ -277,6 +364,16 @@ class Decibri extends Readable {
     return this._native.isOpen;
   }
 
+  /**
+   * 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.
+   * 0 when VAD is disabled or before the first chunk is processed.
+   * @returns {number}
+   */
+  get vadScore() {
+    return this._vadScore;
+  }
+
   /**
    * List all available input devices on the system.
    * @returns {Array<{index: number, name: string, maxInputChannels: number, defaultSampleRate: number, isDefault: boolean}>}
@@ -286,15 +383,49 @@ class Decibri extends Readable {
   }
 
   /**
-   * Version information for decibri and the audio runtime.
-   * @returns {{ decibri: string, portaudio: string }}
+   * Version information for decibri, the audio backend, and this binding.
+   * @returns {{ decibri: string, audioBackend: string, binding: string }}
    */
   static version() {
-    return DecibriBridge.version();
+    const v = DecibriBridge.version();
+    return { decibri: v.decibri, audioBackend: v.audioBackend, binding: PACKAGE_VERSION };
   }
 }
 
-const DecibriOutput = require('./decibri-output.js');
-Decibri.DecibriOutput = DecibriOutput;
+const Speaker = require('./decibri-output.js');
+
+/**
+ * List all available audio input devices.
+ * @returns {Array<{index: number, name: string, maxInputChannels: number, defaultSampleRate: number, isDefault: boolean}>}
+ */
+function inputDevices() {
+  return Microphone.devices();
+}
+
+/**
+ * List all available audio output devices.
+ * @returns {Array<{index: number, name: string, maxOutputChannels: number, defaultSampleRate: number, isDefault: boolean}>}
+ */
+function outputDevices() {
+  return Speaker.devices();
+}
+
+/**
+ * Version information for decibri, the audio backend, and this binding.
+ * @returns {{ decibri: string, audioBackend: string, binding: string }}
+ */
+function version() {
+  return Microphone.version();
+}
 
-module.exports = Decibri;
+module.exports = {
+  Microphone,
+  Speaker,
+  inputDevices,
+  outputDevices,
+  version,
+  DecibriError,
+  DeviceError,
+  OrtError,
+  OrtPathError,
+};

package/src/errors.js

@@ -1,40 +1,143 @@
 'use strict';
 
 /**
- * Wrap a native error from decibri-node as a typed JS error class.
+ * decibri error classes.
  *
- * The native binding's to_napi_error uses Status::InvalidArg for caller-input
- * errors and Status::GenericFailure for system errors. This wrapper inspects
- * err.code and matches on the frozen error message prefixes from the Rust
- * core (see CLAUDE.md:28-30, error messages are part of the frozen contract)
- * to classify as TypeError (wrong kind of value) or RangeError (value out of
- * allowed range). Non-InvalidArg errors are passed through unchanged.
+ * A shallow set of catch-root classes that mirror the catch-roots the Python
+ * binding exposes (see bindings/python/python/decibri/exceptions.py), so
+ * `instanceof DecibriError` / `instanceof DeviceError` works the same way
+ * across bindings. Node idiom is shallow classes plus a stable `code` string,
+ * not a deep subclass tree: branch on `err.code` or on `instanceof`.
  *
- * The shim covers all InvalidArg errors, not just a specific subset: even
- * though only some code paths currently reach Rust's to_napi_error, the
- * mapping stays complete and consistent so future paths get typed errors
- * without additional shim updates.
+ *   DecibriError            (base; extends Error)
+ *   +- DeviceError          (device enumeration / selection failures)
+ *   +- OrtError             (ONNX Runtime setup / inference failures)
+ *      +- OrtPathError      (a specific ORT library path could not be loaded)
  *
- * @param {Error} err Error thrown from a native DecibriBridge /
- *   DecibriOutputBridge call.
- * @returns {Error|TypeError|RangeError} Re-wrapped error preserving code.
+ * Argument validation (bad sample rate, channels, frames, dtype, vad) keeps
+ * Node's built-in RangeError / TypeError, matching Node core; those are not
+ * decibri error classes by design.
+ */
+
+class DecibriError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [code] Stable string code for `err.code` branching.
+   */
+  constructor(message, code) {
+    super(message);
+    this.name = 'DecibriError';
+    this.code = code;
+  }
+}
+
+class DeviceError extends DecibriError {
+  constructor(message, code) {
+    super(message, code);
+    this.name = 'DeviceError';
+  }
+}
+
+class OrtError extends DecibriError {
+  constructor(message, code) {
+    super(message, code);
+    this.name = 'OrtError';
+  }
+}
+
+class OrtPathError extends OrtError {
+  constructor(message, code) {
+    super(message, code);
+    this.name = 'OrtPathError';
+  }
+}
+
+// ─── Native error classification ─────────────────────────────────────────────
+
+// The napi layer flattens every core DecibriError variant to a Status plus the
+// variant's Display string (see bindings/node/src/lib.rs to_napi_error), so the
+// message text is the only thing left to classify on. The prefixes below match
+// the frozen core messages in crates/decibri/src/error.rs.
+
+const DEVICE_CODES = [
+  ['No microphone found matching', 'MICROPHONE_NOT_FOUND'],
+  ['No speaker found matching', 'SPEAKER_NOT_FOUND'],
+  ['Multiple devices match', 'MULTIPLE_DEVICES_MATCH'],
+  ['No microphone found.', 'NO_MICROPHONE_FOUND'],
+  ['No speaker found.', 'NO_SPEAKER_FOUND'],
+  ['Selected device is not a valid microphone', 'NOT_AN_INPUT_DEVICE'],
+  ['Failed to enumerate devices', 'DEVICE_ENUMERATION_FAILED'],
+];
+
+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 create ort session builder', 'ORT_SESSION_BUILD_FAILED'],
+  ['Failed to set ort threads', 'ORT_THREADS_CONFIG_FAILED'],
+  ['Silero VAD inference failed', 'ORT_INFERENCE_FAILED'],
+];
+
+/**
+ * Wrap an error thrown from a native DecibriBridge / DecibriOutputBridge call
+ * into the appropriate JS error: a built-in for argument validation, or a
+ * decibri catch-root class (with a `code`) for device and ONNX Runtime
+ * failures. The message is preserved verbatim.
+ *
+ * @param {Error} err Error thrown from a native constructor.
+ * @returns {Error} A RangeError, TypeError, or DecibriError subclass.
  */
 function wrapNativeError(err) {
-  if (err.code !== 'InvalidArg') return err;
+  const msg = (err && err.message) || String(err);
 
-  const msg = err.message;
-  const isRange =
+  // Argument validation stays as Node built-ins. `device index out of range`
+  // is kept here (RangeError) so the index error type is the same whether it
+  // is raised by the client-side bounds check or by the core.
+  if (
     msg.startsWith('sample rate must be between') ||
     msg.startsWith('channels must be between') ||
     msg.startsWith('frames per buffer must be between') ||
     msg.startsWith('Silero VAD only supports') ||
     msg.startsWith('VAD threshold must be between') ||
-    msg.startsWith('device index out of range');
+    msg.startsWith('device index out of range')
+  ) {
+    return new RangeError(msg);
+  }
+  if (
+    msg.startsWith("dtype must be 'int16' or 'float32'") ||
+    msg.startsWith("format must be 'int16' or 'float32'")
+  ) {
+    return new TypeError(msg);
+  }
+
+  // Device enumeration / selection failures.
+  for (const [prefix, code] of DEVICE_CODES) {
+    if (msg.startsWith(prefix)) return new DeviceError(msg, code);
+  }
+
+  // ONNX Runtime: a bad library path is an OrtPathError (subclass of OrtError);
+  // OrtLoadFailed and OrtPathInvalid share this message prefix and the same
+  // user-facing meaning. Other ORT failures are OrtError.
+  if (msg.startsWith('decibri: failed to load ONNX Runtime from')) {
+    return new OrtPathError(msg, 'ORT_LOAD_FAILED');
+  }
+  for (const [prefix, code] of ORT_CODES) {
+    if (msg.startsWith(prefix)) return new OrtError(msg, code);
+  }
+  if (msg.startsWith('Failed to create') && msg.includes('tensor')) {
+    return new OrtError(msg, 'ORT_TENSOR_CREATE_FAILED');
+  }
+  if (msg.startsWith('Failed to extract') && msg.includes('tensor')) {
+    return new OrtError(msg, 'ORT_TENSOR_EXTRACT_FAILED');
+  }
 
-  const Wrapper = isRange ? RangeError : TypeError;
-  const wrapped = new Wrapper(msg);
-  wrapped.code = err.code;
-  return wrapped;
+  // Any other error from the native constructor is still a decibri error.
+  return new DecibriError(msg, 'DECIBRI_ERROR');
 }
 
-module.exports = { wrapNativeError };
+module.exports = {
+  DecibriError,
+  DeviceError,
+  OrtError,
+  OrtPathError,
+  wrapNativeError,
+};