decibri 3.4.2 → 4.1.0

package/README.md

@@ -1,6 +1,6 @@
 # decibri
 
-Cross-platform audio capture, output, and voice activity detection for Node.js and browsers.
+Cross-platform audio capture, playback, and voice activity detection for Node.js and browsers.
 
 ## Installation
 
@@ -8,18 +8,24 @@ Cross-platform audio capture, output, and voice activity detection for Node.js a
 npm install decibri
 ```
 
-One package for Node.js and browsers. Node.js gets a native addon (Rust via napi-rs). Browsers get a JavaScript AudioWorklet implementation. Platform-specific binaries are installed automatically.
+One package for Node.js and browsers. Node.js gets a prebuilt native addon. Browsers get a JavaScript AudioWorklet implementation. Platform-specific binaries are installed automatically.
 
 Requires Node.js >= 18. TypeScript definitions are bundled.
 
+The package uses named exports:
+
+```javascript
+const { Microphone, Speaker, inputDevices, outputDevices, version } = require('decibri');
+```
+
 ## Quick Start
 
 ### Capture audio
 
 ```javascript
-const Decibri = require('decibri');
+const { Microphone } = require('decibri');
 
-const mic = new Decibri({ sampleRate: 16000, channels: 1 });
+const mic = new Microphone({ sampleRate: 16000, channels: 1 });
 mic.on('data', (chunk) => { /* Buffer of Int16 PCM samples */ });
 setTimeout(() => mic.stop(), 5000);
 ```
@@ -27,9 +33,9 @@ setTimeout(() => mic.stop(), 5000);
 ### Play audio
 
 ```javascript
-const { DecibriOutput } = require('decibri');
+const { Speaker } = require('decibri');
 
-const speaker = new DecibriOutput({ sampleRate: 16000, channels: 1 });
+const speaker = new Speaker({ sampleRate: 16000, channels: 1 });
 speaker.write(pcmBuffer);
 speaker.end();
 ```
@@ -37,9 +43,9 @@ speaker.end();
 ### Browser capture
 
 ```javascript
-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) => { /* Int16Array of PCM samples */ });
 await mic.start(); // requires user gesture in Safari
 ```
@@ -47,14 +53,16 @@ await mic.start(); // requires user gesture in Safari
 ### Pipe capture to playback (echo)
 
 ```javascript
-const mic = new Decibri({ sampleRate: 16000, channels: 1 });
-const speaker = new DecibriOutput({ sampleRate: 16000, channels: 1 });
+const { Microphone, Speaker } = require('decibri');
+
+const mic = new Microphone({ sampleRate: 16000, channels: 1 });
+const speaker = new Speaker({ sampleRate: 16000, channels: 1 });
 mic.pipe(speaker);
 ```
 
-## API: Decibri (Capture)
+## API: Microphone (Capture)
 
-### `new Decibri(options?)`
+### `new Microphone(options?)`
 
 Creates a Readable stream that captures from the microphone.
 
@@ -64,27 +72,33 @@ Creates a Readable stream that captures from the microphone.
 | `channels` | number | 1 | Input channels (1 to 32) |
 | `framesPerBuffer` | number | 1600 | Frames per chunk (64 to 65536). At 16kHz mono, 1600 = 100ms = 3200 bytes |
 | `device` | number, string, or `{ id: string }` | system default | Device index, case-insensitive name substring, or stable per-host ID |
-| `format` | `'int16'` \| `'float32'` | `'int16'` | Sample encoding |
-| `vad` | boolean | false | Enable voice activity detection |
-| `vadMode` | `'energy'` \| `'silero'` | `'energy'` | VAD engine: RMS threshold or Silero ML model |
-| `vadThreshold` | number | 0.01 / 0.5 | Speech threshold. Default depends on `vadMode` |
+| `dtype` | `'int16'` \| `'float32'` | `'int16'` | Sample encoding |
+| `vad` | `false` \| `'silero'` \| `'energy'` | `false` | Voice activity detection: disabled, the Silero ML model, or an RMS energy threshold |
+| `vadThreshold` | number | 0.5 / 0.01 | Speech threshold. Default is 0.5 for `'silero'`, 0.01 for `'energy'` |
 | `vadHoldoff` | number | 300 | Silence holdoff in ms |
+| `modelPath` | string | bundled model | Path to the Silero model. Only used when `vad` is `'silero'` |
 
 Standard `ReadableOptions` (e.g. `highWaterMark`) are also accepted.
 
+`vad: true` is not accepted; pass the mode explicitly as `vad: 'silero'` or `vad: 'energy'`.
+
 ### Methods
 
 | Method | Description |
 | --- | --- |
 | `mic.stop()` | Stop capture and end stream. Safe to call multiple times |
-| `Decibri.devices()` | List available input devices |
-| `Decibri.version()` | Version info |
+| `Microphone.open(options?)` | Construct without blocking the event loop. Returns a `Promise<Microphone>`. See [Non-blocking API](#non-blocking-api) |
+| `Microphone.devices()` | List available input devices |
+| `Microphone.version()` | Version info: `{ decibri, audioBackend, binding }` |
+
+The module-level `inputDevices()` and `version()` free functions are equivalent to the static methods.
 
 ### Properties
 
 | Property | Type | Description |
 | --- | --- | --- |
 | `mic.isOpen` | boolean | `true` while capturing |
+| `mic.vadScore` | number | Latest VAD score for the active mode (Silero probability or normalized RMS); 0 when disabled |
 
 ### Events
 
@@ -97,9 +111,9 @@ Standard `ReadableOptions` (e.g. `highWaterMark`) are also accepted.
 | `'end'` | - | Stream ended |
 | `'error'` | Error | An error occurred |
 
-## API: DecibriOutput (Playback)
+## API: Speaker (Playback)
 
-### `new DecibriOutput(options?)`
+### `new Speaker(options?)`
 
 Creates a Writable stream for speaker playback.
 
@@ -107,7 +121,7 @@ Creates a Writable stream for speaker playback.
 | --- | --- | --- | --- |
 | `sampleRate` | number | 16000 | Playback sample rate (1000 to 384000) |
 | `channels` | number | 1 | Output channels (1 to 32) |
-| `format` | `'int16'` \| `'float32'` | `'int16'` | Sample encoding of incoming data |
+| `dtype` | `'int16'` \| `'float32'` | `'int16'` | Sample encoding of incoming data |
 | `device` | number, string, or `{ id: string }` | system default | Output device index, case-insensitive name substring, or stable per-host ID |
 
 Standard `WritableOptions` (e.g. `highWaterMark`) are also accepted.
@@ -115,27 +129,82 @@ Standard `WritableOptions` (e.g. `highWaterMark`) are also accepted.
 | Method / Property | Description |
 | --- | --- |
 | `speaker.write(chunk)` | Write PCM data for playback |
+| `speaker.writeAsync(chunk)` | Write without blocking the event loop. Returns a `Promise`. See [Non-blocking API](#non-blocking-api) |
 | `speaker.end()` | Signal end. Drains remaining audio, then emits `'finish'` |
+| `speaker.drainAsync()` | Wait for queued audio to finish without blocking the event loop. Returns a `Promise` |
 | `speaker.stop()` | Immediate stop. Discards remaining audio |
 | `speaker.isPlaying` | `true` while audio is being output |
-| `DecibriOutput.devices()` | List available output devices |
-| `DecibriOutput.version()` | Same as `Decibri.version()` |
+| `Speaker.open(options?)` | Construct without blocking the event loop. Returns a `Promise<Speaker>` |
+| `Speaker.devices()` | List available output devices |
+| `Speaker.version()` | Same as `Microphone.version()` |
+
+The module-level `outputDevices()` free function is equivalent to `Speaker.devices()`.
+
+## Non-blocking API
+
+The synchronous constructors and `write` / `drain` do their work on the event loop, which is fine for most apps. For event-loop-sensitive code (servers, real-time voice pipelines), 4.1.0 adds async variants that perform the blocking work without stalling the event loop. They are additive: the synchronous API is unchanged, and you opt in only where you need it.
+
+### Non-blocking construction
+
+`Microphone.open(options?)` and `Speaker.open(options?)` are async factories that return a Promise of a ready instance. They take the same options as the constructors. For a microphone with Silero VAD, the model load that the constructor does inline runs without blocking the event loop.
+
+```javascript
+const { Microphone, Speaker } = require('decibri');
+
+const mic = await Microphone.open({ sampleRate: 16000, vad: 'silero' });
+const speaker = await Speaker.open({ sampleRate: 16000, channels: 1 });
+```
+
+The synchronous `new Microphone(...)` and `new Speaker(...)` still work unchanged. A failed open rejects the Promise with the same typed error a failed constructor throws.
+
+### Non-blocking playback
+
+`speaker.writeAsync(chunk)` resolves once the audio is queued, performing the backpressure wait (when the playback buffer is full) without blocking the event loop. `speaker.drainAsync()` resolves when all queued audio has finished playing, again without blocking.
+
+```javascript
+const speaker = await Speaker.open({ sampleRate: 16000, channels: 1 });
+
+await speaker.writeAsync(pcmBuffer);
+await speaker.drainAsync(); // resolves when playback finishes
+```
+
+These are a direct alternative to the synchronous `write()` / `pipe()` / `end()` stream interface, which is unchanged. Use one path per instance (the stream methods or the async methods, not both at once), and await calls in sequence to keep samples in order.
+
+## Errors
+
+Construction errors come as typed classes you can catch:
+
+```javascript
+const { Microphone, DecibriError, DeviceError } = require('decibri');
+
+try {
+  new Microphone({ device: 'no such device' });
+} catch (err) {
+  if (err instanceof DeviceError) {
+    console.log(err.code); // e.g. 'MICROPHONE_NOT_FOUND'
+  }
+}
+```
+
+`DeviceError`, `OrtError`, and `OrtPathError` extend `DecibriError`, which extends `Error`. Each carries a stable `code` string. Argument validation (bad `sampleRate`, `channels`, `dtype`, or `vad`) throws a built-in `RangeError` or `TypeError`.
 
 ## API: Browser
 
 The browser API uses `getUserMedia` and `AudioWorklet`. It differs from the Node.js API because browser audio is fundamentally async.
 
-### `new Decibri(options?)` (browser)
+### `new Microphone(options?)` (browser)
 
 Same options as Node.js, plus:
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `device` | string | system default | Device ID from `Decibri.devices()` (not index) |
+| `device` | string | system default | Device ID from `Microphone.devices()` (not index) |
 | `echoCancellation` | boolean | true | Browser echo cancellation |
 | `noiseSuppression` | boolean | true | Browser noise suppression |
 | `workletUrl` | string | inline blob | Custom worklet URL for strict CSP |
 
+The browser runs energy-mode VAD only, so its `vad` option accepts `false` or `'energy'`. The browser `version()` returns `{ decibri }` only.
+
 ### Key differences from Node.js
 
 | Aspect | Node.js | Browser |
@@ -144,49 +213,52 @@ Same options as Node.js, plus:
 | Base class | Readable stream | Custom Emitter |
 | Data type | Buffer | Int16Array / Float32Array |
 | `devices()` | Sync, returns array | Async, returns Promise |
-| Sample rate | Direct via cpal | Resampled from native rate |
+| Sample rate | Native device rate | Resampled from native rate |
+| VAD | `'silero'` or `'energy'` | `'energy'` only |
 
 ## Voice Activity Detection
 
-### Energy mode (default)
+### Energy mode
 
 Lightweight RMS energy threshold. No model required.
 
 ```javascript
-const mic = new Decibri({ vad: true, vadThreshold: 0.01 });
+const mic = new Microphone({ vad: 'energy', vadThreshold: 0.01 });
 mic.on('speech', () => console.log('speaking'));
 mic.on('silence', () => console.log('silent'));
 ```
 
 ### Silero mode
 
-ML-based detection using the Silero VAD v5 ONNX model. More accurate than energy mode, especially in noisy environments.
+ML-based detection using the Silero VAD v5 model. More accurate than energy mode, especially in noisy environments.
 
 ```javascript
-const mic = new Decibri({ vad: true, vadMode: 'silero', vadThreshold: 0.5 });
+const mic = new Microphone({ vad: 'silero', vadThreshold: 0.5 });
 mic.on('speech', () => console.log('speaking'));
 mic.on('silence', () => console.log('silent'));
 ```
 
-The Silero model (~2MB) ships inside the npm package. No downloads or API keys required.
+The Silero model (~2MB) ships inside the npm package. No downloads or API keys required. Silero mode is Node.js only.
 
 ## Device Selection
 
 ```javascript
+const { Microphone } = require('decibri');
+
 // System default
-const mic = new Decibri();
+const mic = new Microphone();
 
 // By name (case-insensitive substring match)
-const mic = new Decibri({ device: 'USB' });
+const mic = new Microphone({ device: 'USB' });
 
 // By index
-const devices = Decibri.devices();
-const mic = new Decibri({ device: devices[1].index });
+const devices = Microphone.devices();
+const mic = new Microphone({ device: devices[1].index });
 
 // By stable per-host ID (survives across enumerations)
-const mic = new Decibri({ device: { id: devices[1].id } });
+const mic = new Microphone({ device: { id: devices[1].id } });
 
-Decibri.devices();
+Microphone.devices();
 // [
 //   { index: 0, name: 'Microphone', id: '{0.0.1.00000000}.{...}', maxInputChannels: 2, defaultSampleRate: 48000, isDefault: true },
 //   { index: 1, name: 'USB Headset', id: '{0.0.1.00000000}.{...}', maxInputChannels: 1, defaultSampleRate: 44100, isDefault: false }
@@ -206,6 +278,10 @@ node node_modules/decibri/examples/websocket-server.js   # terminal 1
 node node_modules/decibri/examples/websocket-stream.js   # terminal 2
 ```
 
+## Migrating from 3.x
+
+decibri 4.0.0 renames the API to a microphone and speaker vocabulary and switches to named exports. See [MIGRATION.md](./MIGRATION.md) for a complete before-and-after guide.
+
 ## Platform Support
 
 | Platform | Architecture | Audio Backend |
@@ -218,9 +294,9 @@ node node_modules/decibri/examples/websocket-stream.js   # terminal 2
 
 ## How It Works
 
-decibri is a Rust library using cpal for cross-platform audio I/O. The Rust core compiles to a Node.js native addon via napi-rs and ships pre-built binaries for each platform. Browser support uses a JavaScript AudioWorklet implementation with the same event-driven API.
+decibri compiles a Rust audio core to a Node.js native addon and ships prebuilt binaries for each platform, so there is no build step on install. Browser support uses a JavaScript AudioWorklet implementation with the same event-driven API.
 
-Audio flows from the OS audio device through cpal's callback, into a crossbeam channel, through frame-exact buffering (guarantees consistent chunk sizes), and into Node.js via a threadsafe function. The JavaScript layer wraps this in a standard Readable stream.
+On Node.js, audio flows from the OS audio device through frame-exact buffering (which guarantees consistent chunk sizes) and into a standard Readable stream. In the browser, audio is captured and resampled in an AudioWorklet and delivered through the same `'data'` event interface.
 
 ## Documentation
 

package/examples/wav-capture.js

@@ -5,14 +5,14 @@
 // Usage (from repo clone):            node npm/decibri/examples/wav-capture.js
 
 const fs = require('fs');
-const Decibri = require('decibri');
+const { Microphone } = require('decibri');
 
 const SAMPLE_RATE     = 16000;
 const CHANNELS        = 1;
 const BITS_PER_SAMPLE = 16;
 const DURATION_MS     = 5000;
 
-const mic    = new Decibri({ sampleRate: SAMPLE_RATE, channels: CHANNELS });
+const mic    = new Microphone({ sampleRate: SAMPLE_RATE, channels: CHANNELS });
 const chunks = [];
 
 mic.on('data',  (chunk) => chunks.push(chunk));

package/examples/websocket-stream.js

@@ -5,11 +5,11 @@
 // Usage (from repo clone):            node npm/decibri/examples/websocket-stream.js [ws://localhost:8080]
 
 const { WebSocket } = require('ws');
-const Decibri       = require('decibri');
+const { Microphone } = require('decibri');
 
 const url = process.argv[2] || 'ws://localhost:8080';
 const ws  = new WebSocket(url);
-const mic = new Decibri({ sampleRate: 16000, channels: 1 });
+const mic = new Microphone({ sampleRate: 16000, channels: 1 });
 
 ws.on('open', () => {
   console.log(`Connected to ${url}, streaming audio. Ctrl+C to stop.`);

package/index.d.ts

@@ -3,6 +3,14 @@
 /** Native bridge class exposed to Node.js via napi-rs. */
 export declare class DecibriBridge {
   constructor(options?: DecibriOptions | undefined | null)
+  /**
+   * Construct a microphone bridge without blocking the JS event loop. The
+   * device resolution and Silero model load run on the libuv thread pool;
+   * the returned Promise resolves to a fully constructed bridge, or rejects
+   * with the matching error. The synchronous `new` remains available and
+   * unchanged.
+   */
+  static openAsync(options?: DecibriOptions | undefined | null): Promise<unknown>
   /** Start capturing audio. The callback receives `(err, chunk)` for each buffer. */
   start(callback: (err: Error | null, chunk: Buffer) => void): void
   /** Stop capturing audio. */
@@ -23,13 +31,36 @@ export declare class DecibriBridge {
 /** Native bridge class for audio output, exposed to Node.js via napi-rs. */
 export declare class DecibriOutputBridge {
   constructor(options?: DecibriOutputOptions | undefined | null)
+  /**
+   * Construct a speaker bridge without blocking the JS event loop. The device
+   * resolution runs on the libuv thread pool; the returned Promise resolves
+   * to a constructed bridge, or rejects with the matching error. The
+   * synchronous `new` remains available and unchanged.
+   */
+  static openAsync(options?: DecibriOutputOptions | undefined | null): Promise<unknown>
   /**
    * Write PCM data for playback. Starts the output stream on first call.
    * Empty buffers are a no-op.
    */
   write(buffer: Buffer): void
+  /**
+   * Non-blocking write: convert the samples and start the stream on the JS
+   * thread (a fast device open, same as the synchronous first write), then
+   * perform the blocking channel `send` (which stalls under backpressure when
+   * the queue is full) on the libuv thread pool. The returned Promise
+   * resolves when the samples are queued, or rejects with the matching error.
+   * Empty buffers resolve immediately. The synchronous `write` is unchanged.
+   */
+  writeAsync(buffer: Buffer): Promise<unknown>
   /** Graceful drain: blocks until all queued samples have been played. */
   drain(): void
+  /**
+   * Non-blocking drain: the poll loop that waits for the cpal callback to play
+   * everything queued runs on the libuv thread pool instead of the event loop.
+   * The returned Promise resolves when the buffer has drained. With no stream
+   * yet created it resolves immediately. The synchronous `drain` is unchanged.
+   */
+  drainAsync(): Promise<unknown>
   /** Immediate stop. Discards remaining samples. */
   stop(): void
   /** Whether audio is currently being output. */
@@ -115,5 +146,5 @@ export interface OutputDeviceInfoJs {
 /** Version info returned to JS. */
 export interface VersionInfoJs {
   decibri: string
-  portaudio: string
+  audioBackend: string
 }