decibri 3.4.2 → 4.0.0

package/src/browser/decibri-browser.js

@@ -3,7 +3,10 @@
 const { Emitter } = require('./emitter.js');
 const { WORKLET_SOURCE } = require('./worklet-inline.js');
 
-const VERSION = '3.0.0';
+// Browser build version. Keep in sync with package.json on each release; the
+// browser bundle cannot read package.json at runtime the way the Node wrapper
+// does, so this is a maintained constant.
+const VERSION = '4.0.0';
 
 /**
  * Browser microphone capture.
@@ -14,14 +17,14 @@ const VERSION = '3.0.0';
  * Ported from decibri-web decibri.ts. Logic identical, types removed.
  *
  * @example
- * const { Decibri } = require('decibri'); // browser entry via conditional export
- * const mic = new Decibri({ sampleRate: 16000 });
+ * const { Microphone } = require('decibri'); // browser entry via conditional export
+ * const mic = new Microphone({ sampleRate: 16000 });
  * mic.on('data', (chunk) => { // chunk is Int16Array });
  * await mic.start();
  * // later...
  * mic.stop();
  */
-class Decibri extends Emitter {
+class Microphone extends Emitter {
   constructor(options = {}) {
     super();
 
@@ -35,9 +38,22 @@ class Decibri extends Emitter {
     this._stopRequested = false;
 
     // ── VAD state ─────────────────────────────────────────────────────────
-    this._vad = options.vad ?? false;
+    // Single vad union: false (disabled, default) or 'energy'. The browser
+    // runs energy VAD only; Silero needs ONNX Runtime, which is Node-only. The
+    // legacy vad: true form is rejected with a migration error.
+    const vad = options.vad ?? false;
+    if (vad === false) {
+      this._vad = false;
+    } else if (vad === true) {
+      throw new TypeError("vad: true is no longer supported. Specify the mode explicitly: vad: 'energy'.");
+    } else if (vad === 'energy') {
+      this._vad = true;
+    } else {
+      throw new TypeError(`Invalid vad value: ${JSON.stringify(vad)}. Expected false or 'energy'.`);
+    }
     this._vadThreshold = options.vadThreshold ?? 0.01;
     this._vadHoldoff = options.vadHoldoff ?? 300;
+    this._vadScore = 0;
     this._isSpeaking = false;
     this._silenceTimer = null;
 
@@ -46,7 +62,7 @@ class Decibri extends Emitter {
     this._channels = options.channels ?? 1;
     this._framesPerBuffer = options.framesPerBuffer ?? 1600;
     this._device = options.device;
-    this._format = options.format ?? 'int16';
+    this._dtype = options.dtype ?? 'int16';
     this._echoCancellation = options.echoCancellation ?? true;
     this._noiseSuppression = options.noiseSuppression ?? true;
     this._workletUrl = options.workletUrl;
@@ -61,8 +77,8 @@ class Decibri extends Emitter {
     if (this._framesPerBuffer < 64 || this._framesPerBuffer > 65536) {
       throw new TypeError(`frames per buffer must be between 64 and 65536, got ${this._framesPerBuffer}`);
     }
-    if (this._format !== 'int16' && this._format !== 'float32') {
-      throw new TypeError("format must be 'int16' or 'float32'");
+    if (this._dtype !== 'int16' && this._dtype !== 'float32') {
+      throw new TypeError("dtype must be 'int16' or 'float32'");
     }
     if (this._vadThreshold < 0 || this._vadThreshold > 1) {
       throw new TypeError(`vadThreshold must be between 0 and 1, got ${this._vadThreshold}`);
@@ -143,6 +159,15 @@ class Decibri extends Emitter {
     return this._started;
   }
 
+  /**
+   * Most recent VAD score: the normalized RMS of the last chunk in `'energy'`
+   * mode, or 0 when VAD is disabled or before the first chunk is processed.
+   * @returns {number}
+   */
+  get vadScore() {
+    return this._vadScore;
+  }
+
   /**
    * List available audio input devices.
    * Device labels may be empty until microphone permission is granted.
@@ -217,7 +242,7 @@ class Decibri extends Emitter {
     this._workletNode = new AudioWorkletNode(this._audioContext, 'decibri-processor', {
       processorOptions: {
         framesPerBuffer: this._framesPerBuffer,
-        format: this._format,
+        format: this._dtype,
         nativeSampleRate,
         targetSampleRate: this._sampleRate,
       },
@@ -226,7 +251,7 @@ class Decibri extends Emitter {
     // 5. Wire up data from worklet
     this._workletNode.port.onmessage = (event) => {
       const buffer = event.data;
-      const chunk = this._format === 'int16'
+      const chunk = this._dtype === 'int16'
         ? new Int16Array(buffer)
         : new Float32Array(buffer);
 
@@ -272,6 +297,7 @@ class Decibri extends Emitter {
 
   _processVad(chunk) {
     const rms = this._computeRms(chunk);
+    this._vadScore = rms;
 
     if (rms >= this._vadThreshold) {
       if (this._silenceTimer !== null) {
@@ -309,4 +335,4 @@ class Decibri extends Emitter {
   }
 }
 
-module.exports = { Decibri };
+module.exports = { Microphone };

package/src/browser/index.d.ts

@@ -1,5 +1,5 @@
 /** Information about an available audio input device (browser). */
-export interface DeviceInfo {
+export interface MicrophoneInfo {
   /** Opaque device identifier (pass to constructor as `device`). */
   deviceId: string;
   /** Human-readable device name. May be empty until permission is granted. */
@@ -8,14 +8,15 @@ export interface DeviceInfo {
   groupId: string;
 }
 
-/** Version information. */
+/** Version information (browser). The browser surface has no native audio
+ *  backend, so it reports only the decibri version. */
 export interface VersionInfo {
-  /** decibri package version (e.g. `"3.0.0"`). */
+  /** decibri version. */
   decibri: string;
 }
 
-/** Constructor options for the browser `Decibri` class. */
-export interface DecibriOptions {
+/** Constructor options for the browser `Microphone` class. */
+export interface MicrophoneOptions {
   /**
    * Target sample rate in Hz. Browser captures at native rate and resamples.
    * @default 16000
@@ -38,24 +39,30 @@ export interface DecibriOptions {
   framesPerBuffer?: number;
 
   /**
-   * Audio input device. Pass a deviceId string from `Decibri.devices()`.
+   * Audio input device. Pass a deviceId string from `Microphone.devices()`.
    * Omit to use the system default input device.
    */
   device?: string;
 
   /**
-   * Sample encoding format.
+   * Sample encoding data type.
    * - `'int16'`: Int16Array of PCM samples
    * - `'float32'`: Float32Array of samples in [-1, 1]
    * @default 'int16'
    */
-  format?: 'int16' | 'float32';
+  dtype?: 'int16' | 'float32';
 
   /**
-   * Enable energy-based voice activity detection.
+   * Voice activity detection mode. One of:
+   * - `false`: disabled (default)
+   * - `'energy'`: RMS energy threshold
+   *
+   * The browser runs energy VAD only; Silero is Node-only. 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 | 'energy';
 
   /**
    * RMS energy threshold for speech detection (VAD mode only).
@@ -95,9 +102,9 @@ export interface DecibriOptions {
  *
  * @example
  * ```js
- * import { Decibri } from 'decibri'; // browser entry via conditional export
+ * import { Microphone } from 'decibri'; // browser entry via conditional export
  *
- * const mic = new Decibri({ sampleRate: 16000 });
+ * const mic = new Microphone({ sampleRate: 16000 });
  * mic.on('data', (chunk) => {
  *   // chunk is an Int16Array of PCM samples
  * });
@@ -105,8 +112,8 @@ export interface DecibriOptions {
  * mic.stop();
  * ```
  */
-export declare class Decibri {
-  constructor(options?: DecibriOptions);
+export declare class Microphone {
+  constructor(options?: MicrophoneOptions);
 
   /**
    * Start microphone capture.
@@ -121,11 +128,17 @@ export declare class Decibri {
   /** Whether the microphone is currently capturing. */
   readonly isOpen: boolean;
 
+  /**
+   * Most recent VAD score: the normalized RMS of the last chunk in `'energy'`
+   * mode, or 0 when VAD is disabled or before the first chunk is processed.
+   */
+  readonly vadScore: number;
+
   /**
    * List available audio input devices.
    * Labels may be empty until microphone permission is granted.
    */
-  static devices(): Promise<DeviceInfo[]>;
+  static devices(): Promise<MicrophoneInfo[]>;
 
   /** Version information. */
   static version(): VersionInfo;

package/src/browser/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { Decibri } = require('./decibri-browser.js');
+const { Microphone } = require('./decibri-browser.js');
 const { Emitter } = require('./emitter.js');
 
-module.exports = { Decibri, Emitter };
+module.exports = { Microphone, Emitter };

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 {}