decibri 3.4.2 → 4.1.0

package/src/decibri-output.js

@@ -4,15 +4,54 @@ 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]
+   * @param {{ prepared: object, native: object }} [_internal] Internal: a
+   *   pre-resolved options bundle and an already-constructed native bridge,
+   *   passed by the async `Speaker.open()` factory. Not part of the public API.
    */
-  constructor(options = {}) {
+  constructor(options = {}, _internal = undefined) {
     super({ highWaterMark: options.highWaterMark || 16384 });
 
+    // Validate and resolve options once. The async factory passes its already
+    // resolved bundle through `_internal` to avoid recomputing it.
+    const prepared = _internal ? _internal.prepared : Speaker._prepareOptions(options);
+
+    // ── Store config ───────────────────────────────────────────────────────
+
+    this._dtype = prepared.dtype;
+    this._started = false;
+
+    // ── Create or adopt native bridge ───────────────────────────────────────
+
+    if (_internal) {
+      // Built off the event loop by Speaker.open(); already wrapped.
+      this._native = _internal.native;
+    } else {
+      try {
+        this._native = new DecibriOutputBridge(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` as the constructor on invalid input. Shared by the synchronous
+   * constructor and the async `open()` factory.
+   * @internal
+   * @param {import('./decibri').SpeakerOptions} options
+   */
+  static _prepareOptions(options) {
     // ── Validate options ───────────────────────────────────────────────────
 
     const sampleRate = options.sampleRate ?? 16000;
@@ -25,33 +64,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 (
@@ -67,23 +96,41 @@ class DecibriOutput extends Writable {
       resolvedDevice = options.device;
     }
 
-    // ── Store config ───────────────────────────────────────────────────────
-
-    this._format = format;
-    this._started = false;
-
-    // ── Create native bridge ───────────────────────────────────────────────
-
-    try {
-      this._native = new DecibriOutputBridge({
+    return {
+      dtype,
+      nativeOptions: {
         sampleRate,
         channels,
-        format,
+        format: dtype,
         device: resolvedDevice,
-      });
+      },
+    };
+  }
+
+  /**
+   * Construct a Speaker without blocking the event loop.
+   *
+   * Symmetric with `Microphone.open()` and the Python `AsyncSpeaker.open()`.
+   * The speaker loads no model, so the only open work is device resolution and
+   * the practical blocking risk is small; this factory exists chiefly so async
+   * callers can use one consistent construction pattern across both classes.
+   * The synchronous constructor remains available and unchanged.
+   *
+   * A failed open (unknown device) rejects the returned Promise with the
+   * matching error class rather than throwing synchronously.
+   *
+   * @param {import('./decibri').SpeakerOptions} [options]
+   * @returns {Promise<Speaker>}
+   */
+  static async open(options = {}) {
+    const prepared = Speaker._prepareOptions(options);
+    let native;
+    try {
+      native = await DecibriOutputBridge.openAsync(prepared.nativeOptions);
     } catch (err) {
       throw wrapNativeError(err);
     }
+    return new Speaker(options, { prepared, native });
   }
 
   /** @internal */
@@ -110,6 +157,56 @@ class DecibriOutput extends Writable {
     }
   }
 
+  /**
+   * Write PCM audio without blocking the event loop.
+   *
+   * The blocking part of a write is the backpressure wait when the native
+   * playback queue is full; the synchronous stream path (`write()` / `pipe()`)
+   * performs that wait on the event loop. This method performs it on the native
+   * thread pool and resolves when the samples are queued. The audio stream is
+   * created on the first call (a fast device open) and stays on its own thread;
+   * only the queue handoff runs off the event loop.
+   *
+   * Additive and non-blocking: the synchronous `write()` / `pipe()` stream
+   * interface is unchanged. This is a direct, opt-in alternative that bypasses
+   * the Writable buffer, so do not interleave it with `write()` / `pipe()` on
+   * the same instance; pick one path per instance. Await calls sequentially to
+   * preserve sample order. An empty buffer resolves immediately. A failed write
+   * (a closed or stopped stream) rejects with the matching error class.
+   *
+   * @param {Buffer} chunk PCM samples in the configured `dtype`.
+   * @returns {Promise<void>}
+   */
+  async writeAsync(chunk) {
+    try {
+      await this._native.writeAsync(chunk);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  /**
+   * Wait for all queued audio to finish playing without blocking the event
+   * loop.
+   *
+   * The synchronous drain (run by `end()` / `_final`) polls for completion on
+   * the event loop for the full playback tail; this method runs that wait on the
+   * native thread pool and resolves when the buffer has drained. If nothing has
+   * been written yet it resolves immediately.
+   *
+   * Additive and non-blocking: the synchronous drain via `end()` is unchanged.
+   * Pair this with `writeAsync()` for a fully non-blocking playback path.
+   *
+   * @returns {Promise<void>}
+   */
+  async drainAsync() {
+    try {
+      await this._native.drainAsync();
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
   /**
    * Immediate stop. Discards remaining buffered audio.
    */
@@ -134,12 +231,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,37 @@ 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);
+
+  /**
+   * Construct a Microphone without blocking the event loop on the open work.
+   *
+   * The synchronous constructor loads the Silero VAD model inline when
+   * `vad: 'silero'` is set, blocking the event loop for roughly 100 to 500 ms
+   * on a cold cache. This factory runs that load (and device resolution) on the
+   * native thread pool and resolves to a ready instance. The synchronous
+   * constructor remains available and unchanged.
+   *
+   * Options are identical to the constructor. A failed open rejects the Promise
+   * with the matching error: `RangeError` / `TypeError` for invalid options, or
+   * a `DeviceError` / `OrtError` / `OrtPathError` for native failures.
+   *
+   * @example
+   * ```js
+   * const mic = await Microphone.open({ vad: 'silero' });
+   * mic.on('data', (chunk) => { ... });
+   * ```
+   */
+  static open(options?: MicrophoneOptions): Promise<Microphone>;
 
   /** Stop microphone capture and end the stream. Safe to call multiple times. */
   stop(): void;
@@ -131,8 +151,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 +189,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 +207,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 +224,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 +247,54 @@ 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);
+
+  /**
+   * Construct a Speaker without blocking the event loop. Symmetric with
+   * `Microphone.open()`. The speaker loads no model, so the only open work is
+   * device resolution; this factory is provided so async callers can use one
+   * consistent construction pattern across both classes. The synchronous
+   * constructor remains available and unchanged.
+   *
+   * A failed open (unknown device) rejects the Promise with the matching error.
+   *
+   * @example
+   * ```js
+   * const speaker = await Speaker.open({ sampleRate: 24000 });
+   * speaker.write(pcmBuffer);
+   * ```
+   */
+  static open(options?: SpeakerOptions): Promise<Speaker>;
+
+  /**
+   * Write PCM audio without blocking the event loop. Performs the backpressure
+   * wait (when the native playback queue is full) on the native thread pool and
+   * resolves when the samples are queued.
+   *
+   * Additive: the synchronous `write()` / `pipe()` stream interface is
+   * unchanged. This is a direct, opt-in alternative that bypasses the Writable
+   * buffer; do not interleave it with `write()` / `pipe()` on the same instance.
+   * Await calls sequentially to preserve sample order. An empty buffer resolves
+   * immediately; a closed or stopped stream rejects with the matching error.
+   */
+  writeAsync(chunk: Buffer): Promise<void>;
+
+  /**
+   * Wait for all queued audio to finish playing without blocking the event
+   * loop. Runs the drain wait on the native thread pool and resolves when the
+   * buffer has drained; resolves immediately if nothing was written.
+   *
+   * Additive: the synchronous drain via `end()` is unchanged. Pair with
+   * `writeAsync()` for a fully non-blocking playback path.
+   */
+  drainAsync(): Promise<void>;
 
   /** Immediate stop. Discards remaining buffered audio. */
   stop(): void;
@@ -236,7 +303,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 +319,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 {}