decibri 3.4.1 → 4.0.0

package/src/decibri-output.js

@@ -4,11 +4,15 @@ const { Writable } = require('stream');
 const { DecibriOutputBridge } = require('../index.js');
 const { wrapNativeError } = require('./errors');
 
-// ─── DecibriOutput (Writable) ───────────────────────────────────────────────
+// The npm package version, reported as `binding` by version(). Read from
+// package.json so it tracks the published package and cannot drift.
+const PACKAGE_VERSION = require('../package.json').version;
 
-class DecibriOutput extends Writable {
+// ─── Speaker (Writable) ─────────────────────────────────────────────────────
+
+class Speaker extends Writable {
   /**
-   * @param {import('./decibri').DecibriOutputOptions} [options]
+   * @param {import('./decibri').SpeakerOptions} [options]
    */
   constructor(options = {}) {
     super({ highWaterMark: options.highWaterMark || 16384 });
@@ -25,33 +29,23 @@ class DecibriOutput extends Writable {
       throw new RangeError('channels must be between 1 and 32');
     }
 
-    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 (SpeakerNotFound / 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 = DecibriOutputBridge.devices().filter(d =>
-        d.name.toLowerCase().includes(lower)
-      );
-      if (matches.length === 0) {
-        throw new TypeError(`No audio output 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 = DecibriOutputBridge.devices();
       if (options.device < 0 || options.device >= devices.length) {
-        throw new RangeError('device index out of range. Call DecibriOutput.devices() to list available devices');
+        throw new RangeError('device index out of range. Call Speaker.devices() to list available devices');
       }
       resolvedDevice = options.device;
     } else if (
@@ -69,7 +63,7 @@ class DecibriOutput extends Writable {
 
     // ── Store config ───────────────────────────────────────────────────────
 
-    this._format = format;
+    this._dtype = dtype;
     this._started = false;
 
     // ── Create native bridge ───────────────────────────────────────────────
@@ -78,7 +72,7 @@ class DecibriOutput extends Writable {
       this._native = new DecibriOutputBridge({
         sampleRate,
         channels,
-        format,
+        format: dtype,
         device: resolvedDevice,
       });
     } catch (err) {
@@ -134,12 +128,13 @@ class DecibriOutput extends Writable {
   }
 
   /**
-   * 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 DecibriOutputBridge.version();
+    const v = DecibriOutputBridge.version();
+    return { decibri: v.decibri, audioBackend: v.audioBackend, binding: PACKAGE_VERSION };
   }
 }
 
-module.exports = DecibriOutput;
+module.exports = Speaker;

package/src/decibri.d.ts

@@ -1,7 +1,7 @@
 import { Readable, ReadableOptions, Writable, WritableOptions } from 'stream';
 
 /** Information about an available audio input device. */
-export interface DeviceInfo {
+export interface MicrophoneInfo {
   /** Device index (pass to constructor as `device`). */
   index: number;
   /** Human-readable device name from the OS. */
@@ -23,16 +23,18 @@ export interface DeviceInfo {
   isDefault: boolean;
 }
 
-/** Version strings returned by `Decibri.version()`. */
+/** Version strings returned by `Microphone.version()`. */
 export interface VersionInfo {
-  /** decibri package version (e.g. `"3.0.0"`). */
+  /** decibri core version. */
   decibri: string;
-  /** Audio runtime version string (e.g. `"cpal 0.17"`). */
-  portaudio: string;
+  /** Audio backend version string (e.g. `"cpal 0.17"`). */
+  audioBackend: string;
+  /** This binding's npm package version. */
+  binding: string;
 }
 
-/** Constructor options for `Decibri`. */
-export interface DecibriOptions extends ReadableOptions {
+/** Constructor options for `Microphone`. */
+export interface MicrophoneOptions extends ReadableOptions {
   /**
    * Sample rate in Hz.
    * @default 16000
@@ -57,53 +59,50 @@ export interface DecibriOptions extends ReadableOptions {
 
   /**
    * Audio input device. One of:
-   * - numeric index (from `DeviceInfo.index`)
+   * - numeric index (from `MicrophoneInfo.index`)
    * - case-insensitive name substring
-   * - `{ id: string }` for stable per-host device ID from `DeviceInfo.id`
+   * - `{ id: string }` for stable per-host device ID from `MicrophoneInfo.id`
    *
    * Omit to use the system default input device.
    */
   device?: number | string | { id: string };
 
   /**
-   * Sample encoding format.
+   * Sample encoding data type.
    * - `'int16'`: 16-bit signed integer, little-endian (2 bytes per sample)
    * - `'float32'`: 32-bit IEEE 754 float, little-endian (4 bytes per sample)
    * @default 'int16'
    */
-  format?: 'int16' | 'float32';
+  dtype?: 'int16' | 'float32';
 
   /**
-   * Enable energy-based voice activity detection.
-   * When enabled, emits `'speech'` and `'silence'` events.
+   * Voice activity detection mode. One of:
+   * - `false`: disabled (default)
+   * - `'silero'`: Silero VAD v5 ML model (more accurate, ~1ms inference)
+   * - `'energy'`: RMS energy threshold (lightweight)
+   *
+   * When enabled, emits `'speech'` and `'silence'` events and updates `vadScore`.
+   * The legacy `vad: true` form is rejected; specify the mode explicitly.
    * @default false
    */
-  vad?: boolean;
+  vad?: false | 'silero' | 'energy';
 
   /**
-   * RMS energy threshold for speech detection (VAD mode only).
-   * @default 0.01
+   * Speech-detection threshold for the active VAD mode.
+   * @default 0.5 for `'silero'`, 0.01 for `'energy'`
    * @range 0–1
    */
   vadThreshold?: number;
 
   /**
-   * Milliseconds of sub-threshold audio before emitting `'silence'` (VAD mode only).
+   * Milliseconds of sub-threshold audio before emitting `'silence'`.
    * @default 300
    */
   vadHoldoff?: number;
 
-  /**
-   * VAD engine to use.
-   * - `'energy'`: RMS energy threshold (default, lightweight)
-   * - `'silero'`: Silero VAD v5 ML model (more accurate, ~1ms inference)
-   * @default 'energy'
-   */
-  vadMode?: 'energy' | 'silero';
-
   /**
    * Path to the Silero VAD ONNX model file.
-   * Only used when `vadMode` is `'silero'`.
+   * Only used when `vad` is `'silero'`.
    * Defaults to `models/silero_vad.onnx` relative to the package.
    */
   modelPath?: string;
@@ -114,16 +113,16 @@ export interface DecibriOptions extends ReadableOptions {
  *
  * @example
  * ```js
- * const Decibri = require('decibri');
- * const mic = new Decibri({ sampleRate: 16000, channels: 1 });
+ * const { Microphone } = require('decibri');
+ * const mic = new Microphone({ sampleRate: 16000, channels: 1 });
  * mic.on('data', (chunk) => {
  *   // chunk is a Buffer of Int16 LE PCM samples
  * });
  * setTimeout(() => mic.stop(), 5000);
  * ```
  */
-declare class Decibri extends Readable {
-  constructor(options?: DecibriOptions);
+export declare class Microphone extends Readable {
+  constructor(options?: MicrophoneOptions);
 
   /** Stop microphone capture and end the stream. Safe to call multiple times. */
   stop(): void;
@@ -131,8 +130,15 @@ declare class Decibri extends Readable {
   /** Whether the microphone is currently capturing audio. */
   readonly isOpen: boolean;
 
+  /**
+   * 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.
+   */
+  readonly vadScore: number;
+
   /** List all available audio input devices. */
-  static devices(): DeviceInfo[];
+  static devices(): MicrophoneInfo[];
 
   /** Version information for decibri and the audio runtime. */
   static version(): VersionInfo;
@@ -162,13 +168,13 @@ declare class Decibri extends Readable {
 }
 
 /** Information about an available audio output device. */
-export interface OutputDeviceInfo {
+export interface SpeakerInfo {
   /** Device index (pass to constructor as `device`). */
   index: number;
   /** Human-readable device name from the OS. */
   name: string;
   /**
-   * Stable per-host device ID. See `DeviceInfo.id` for format and fallback
+   * Stable per-host device ID. See `MicrophoneInfo.id` for format and fallback
    * semantics; identical rules for output devices.
    */
   id: string;
@@ -180,8 +186,8 @@ export interface OutputDeviceInfo {
   isDefault: boolean;
 }
 
-/** Constructor options for `DecibriOutput`. */
-export interface DecibriOutputOptions extends WritableOptions {
+/** Constructor options for `Speaker`. */
+export interface SpeakerOptions extends WritableOptions {
   /**
    * Sample rate in Hz.
    * @default 16000
@@ -197,18 +203,18 @@ export interface DecibriOutputOptions extends WritableOptions {
   channels?: number;
 
   /**
-   * Sample encoding format of incoming data.
+   * Sample encoding data type of incoming data.
    * - `'int16'`: 16-bit signed integer, little-endian (2 bytes per sample)
    * - `'float32'`: 32-bit IEEE 754 float, little-endian (4 bytes per sample)
    * @default 'int16'
    */
-  format?: 'int16' | 'float32';
+  dtype?: 'int16' | 'float32';
 
   /**
    * Audio output device. One of:
-   * - numeric index (from `OutputDeviceInfo.index`)
+   * - numeric index (from `SpeakerInfo.index`)
    * - case-insensitive name substring
-   * - `{ id: string }` for stable per-host device ID from `OutputDeviceInfo.id`
+   * - `{ id: string }` for stable per-host device ID from `SpeakerInfo.id`
    *
    * Omit to use the system default output device.
    */
@@ -220,14 +226,14 @@ export interface DecibriOutputOptions extends WritableOptions {
  *
  * @example
  * ```js
- * const { DecibriOutput } = require('decibri');
- * const speaker = new DecibriOutput({ sampleRate: 16000, channels: 1 });
+ * const { Speaker } = require('decibri');
+ * const speaker = new Speaker({ sampleRate: 16000, channels: 1 });
  * speaker.write(pcmBuffer);
  * speaker.end();
  * ```
  */
-declare class DecibriOutput extends Writable {
-  constructor(options?: DecibriOutputOptions);
+export declare class Speaker extends Writable {
+  constructor(options?: SpeakerOptions);
 
   /** Immediate stop. Discards remaining buffered audio. */
   stop(): void;
@@ -236,7 +242,7 @@ declare class DecibriOutput extends Writable {
   readonly isPlaying: boolean;
 
   /** List all available audio output devices. */
-  static devices(): OutputDeviceInfo[];
+  static devices(): SpeakerInfo[];
 
   /** Version information for decibri and the audio runtime. */
   static version(): VersionInfo;
@@ -252,8 +258,36 @@ declare class DecibriOutput extends Writable {
   on(event: string | symbol, listener: (...args: any[]) => void): this;
 }
 
-export = Decibri;
+/** List all available audio input devices. */
+export declare function inputDevices(): MicrophoneInfo[];
+
+/** List all available audio output devices. */
+export declare function outputDevices(): SpeakerInfo[];
 
-declare namespace Decibri {
-  export { DecibriOutput };
+/** Version information for decibri and the audio runtime. */
+export declare function version(): VersionInfo;
+
+/**
+ * Base class for errors raised by the decibri native bindings.
+ *
+ * Catch this to handle any decibri device or ONNX Runtime failure generically;
+ * catch a subclass for finer control. Argument validation (bad sample rate,
+ * channels, frames, dtype, vad) throws built-in `RangeError` / `TypeError`, not
+ * a `DecibriError`.
+ */
+export declare class DecibriError extends Error {
+  /** Stable string code identifying the specific failure. */
+  readonly code: string;
 }
+
+/**
+ * Device enumeration or selection failure: an unmatched device name, an
+ * ambiguous name match, or missing hardware.
+ */
+export declare class DeviceError extends DecibriError {}
+
+/** ONNX Runtime setup or inference failure (Silero VAD). */
+export declare class OrtError extends DecibriError {}
+
+/** A specific ONNX Runtime library path could not be loaded. */
+export declare class OrtPathError extends OrtError {}

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,11 +91,11 @@ 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]
    */
   constructor(options = {}) {
     super({ highWaterMark: options.highWaterMark, objectMode: false });
@@ -106,33 +117,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 +152,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.`);
@@ -172,11 +191,12 @@ class Decibri extends Readable {
 
     // ── Store config ───────────────────────────────────────────────────────
 
-    this._format = format;
-    this._vad = options.vad || false;
+    this._dtype = dtype;
+    this._vad = vadEnabled;
     this._vadMode = vadMode;
     this._vadThreshold = options.vadThreshold ?? (vadMode === 'silero' ? 0.5 : 0.01);
     this._vadHoldoff = options.vadHoldoff ?? 300;
+    this._vadScore = 0;
     this._isSpeaking = false;
     this._silenceTimer = null;
     this._started = false;
@@ -188,9 +208,9 @@ class Decibri extends Readable {
         sampleRate,
         channels,
         framesPerBuffer,
-        format,
+        format: dtype,
         device: resolvedDevice,
-        vadMode: (options.vad && vadMode === 'silero') ? 'silero' : 'energy',
+        vadMode,
         modelPath,
         ortLibraryPath,
       });
@@ -230,7 +250,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 +261,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 +298,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 +317,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();
+}
 
-module.exports = Decibri;
+/**
+ * Version information for decibri, the audio backend, and this binding.
+ * @returns {{ decibri: string, audioBackend: string, binding: string }}
+ */
+function version() {
+  return Microphone.version();
+}
+
+module.exports = {
+  Microphone,
+  Speaker,
+  inputDevices,
+  outputDevices,
+  version,
+  DecibriError,
+  DeviceError,
+  OrtError,
+  OrtPathError,
+};