decibri 4.0.0 → 4.2.0

package/src/decibri-output.js

@@ -13,10 +13,45 @@ const PACKAGE_VERSION = require('../package.json').version;
 class Speaker extends Writable {
   /**
    * @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;
@@ -61,23 +96,41 @@ class Speaker extends Writable {
       resolvedDevice = options.device;
     }
 
-    // ── Store config ───────────────────────────────────────────────────────
-
-    this._dtype = dtype;
-    this._started = false;
-
-    // ── Create native bridge ───────────────────────────────────────────────
-
-    try {
-      this._native = new DecibriOutputBridge({
+    return {
+      dtype,
+      nativeOptions: {
         sampleRate,
         channels,
         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 */
@@ -104,6 +157,56 @@ class Speaker 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.
    */

package/src/decibri.d.ts

@@ -124,6 +124,27 @@ export interface MicrophoneOptions extends ReadableOptions {
 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;
 
@@ -235,6 +256,46 @@ export interface SpeakerOptions extends WritableOptions {
 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;
 

package/src/decibri.js

@@ -96,10 +96,56 @@ function computeRMS(chunk, dtype) {
 class Microphone extends Readable {
   /**
    * @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;
@@ -189,22 +235,13 @@ class Microphone extends Readable {
       ortLibraryPath = resolveBundledOrtPath();
     }
 
-    // ── Store config ───────────────────────────────────────────────────────
-
-    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;
-
-    // ── 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,
@@ -213,10 +250,39 @@ class Microphone extends Readable {
         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 */