decibri 3.4.1 → 4.0.0

package/README.md

@@ -1,182 +1,276 @@
-<!-- markdownlint-disable MD033 MD041 MD059 -->
-<div align="center">
-  <img width="100" height="100" alt="decibri" src="https://github.com/user-attachments/assets/a1a7aa23-6954-4cac-9490-76354f0865ee" />
-
 # decibri
 
-Cross-platform audio capture, playback, and voice activity detection for Python, Rust, and Node.js.
-
-<a href="https://pypi.org/project/decibri/"><img src="https://img.shields.io/pypi/v/decibri" alt="PyPI version"></a>&nbsp;
-<a href="https://www.npmjs.com/package/decibri"><img src="https://img.shields.io/npm/v/decibri" alt="npm version"></a>&nbsp;
-<a href="https://crates.io/crates/decibri"><img src="https://img.shields.io/crates/v/decibri" alt="crates.io version"></a>&nbsp;
-<a href="https://github.com/decibri/decibri/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="Apache 2.0 License"></a>&nbsp;
-<a href="https://decibri.com"><img src="https://img.shields.io/badge/Website-decibri.com-blue" alt="decibri.com"></a>&nbsp;
-<a href="https://decibri.com/docs/"><img src="https://img.shields.io/badge/docs-passing-brightgreen" alt="Docs"></a>
+Cross-platform audio capture, playback, and voice activity detection for Node.js and browsers.
 
-</div>
+## Installation
 
----
+```bash
+npm install decibri
+```
 
-## What is decibri?
+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.
 
-Decibri is a cross-platform audio engine for real-time speech and voice applications. One unified API across Python, Rust, Node.js, and browsers.
+Requires Node.js >= 18. TypeScript definitions are bundled.
 
-Key features:
+The package uses named exports:
 
-- Microphone capture and speaker playback
-- Voice activity detection (Silero or energy modes)
-- Async and streaming APIs
-- Cross-platform: Windows, macOS, Linux, browsers
-- Available in Python, Node.js, and Rust
-- Cloud and local speech-to-text integrations
+```javascript
+const { Microphone, Speaker, inputDevices, outputDevices, version } = require('decibri');
+```
 
-To learn more, visit [decibri.com/docs/](https://decibri.com/docs/).
+## Quick Start
 
-## Installation
+### Capture audio
 
-**Python** (recommended with [uv](https://docs.astral.sh/uv/)):
+```javascript
+const { Microphone } = require('decibri');
 
-```bash
-uv pip install decibri
+const mic = new Microphone({ sampleRate: 16000, channels: 1 });
+mic.on('data', (chunk) => { /* Buffer of Int16 PCM samples */ });
+setTimeout(() => mic.stop(), 5000);
 ```
 
-Or with pip:
+### Play audio
 
-```bash
-pip install decibri
+```javascript
+const { Speaker } = require('decibri');
+
+const speaker = new Speaker({ sampleRate: 16000, channels: 1 });
+speaker.write(pcmBuffer);
+speaker.end();
 ```
 
-<br/>
+### Browser capture
 
-**Node.js:**
+```javascript
+import { Microphone } from 'decibri'; // browser entry via conditional export
 
-```bash
-npm install decibri
+const mic = new Microphone({ sampleRate: 16000 });
+mic.on('data', (chunk) => { /* Int16Array of PCM samples */ });
+await mic.start(); // requires user gesture in Safari
 ```
 
-<br/>
+### Pipe capture to playback (echo)
 
-**Rust:**
+```javascript
+const { Microphone, Speaker } = require('decibri');
 
-```bash
-cargo add decibri
+const mic = new Microphone({ sampleRate: 16000, channels: 1 });
+const speaker = new Speaker({ sampleRate: 16000, channels: 1 });
+mic.pipe(speaker);
 ```
 
-<br/>
+## API: Microphone (Capture)
 
-## Quick Start
+### `new Microphone(options?)`
 
-### Python
+Creates a Readable stream that captures from the microphone.
 
-```python
-import decibri
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sampleRate` | number | 16000 | Samples per second (1000 to 384000) |
+| `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 |
+| `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'` |
 
-with decibri.Microphone(sample_rate=16000) as mic:
-    for chunk in mic:
-        print(f"Got {len(chunk)} bytes")
-        break
-```
+Standard `ReadableOptions` (e.g. `highWaterMark`) are also accepted.
 
-Full Python guide: [here](bindings/python/README.md).
+`vad: true` is not accepted; pass the mode explicitly as `vad: 'silero'` or `vad: 'energy'`.
 
-<br/>
+### Methods
 
-### Node.js
+| Method | Description |
+| --- | --- |
+| `mic.stop()` | Stop capture and end stream. Safe to call multiple times |
+| `Microphone.devices()` | List available input devices |
+| `Microphone.version()` | Version info: `{ decibri, audioBackend, binding }` |
 
-```javascript
-const Decibri = require('decibri');
+The module-level `inputDevices()` and `version()` free functions are equivalent to the static methods.
 
-const mic = new Decibri({ sampleRate: 16000 });
-mic.on('data', (chunk) => console.log(`Got ${chunk.length} bytes`));
-setTimeout(() => mic.stop(), 5000);
-```
+### 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
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `'data'` | Buffer | Audio chunk (Int16 LE or Float32 LE) |
+| `'backpressure'` | - | Internal buffer full, consumer too slow |
+| `'speech'` | - | VAD: audio crosses threshold |
+| `'silence'` | - | VAD: audio below threshold for `vadHoldoff` ms |
+| `'end'` | - | Stream ended |
+| `'error'` | Error | An error occurred |
 
-Full Node.js and browser guide: [here](npm/decibri/README.md).
+## API: Speaker (Playback)
 
-<br/>
+### `new Speaker(options?)`
 
-### Rust
+Creates a Writable stream for speaker playback.
 
-```rust
-use decibri::capture::{AudioCapture, CaptureConfig};
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sampleRate` | number | 16000 | Playback sample rate (1000 to 384000) |
+| `channels` | number | 1 | Output channels (1 to 32) |
+| `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 |
 
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let capture = AudioCapture::new(CaptureConfig::default())?;
-    let stream = capture.start()?;
-    while let Ok(Some(chunk)) = stream.next_chunk(None) {
-        println!("Got {} bytes", chunk.data.len());
-    }
-    Ok(())
+Standard `WritableOptions` (e.g. `highWaterMark`) are also accepted.
+
+| Method / Property | Description |
+| --- | --- |
+| `speaker.write(chunk)` | Write PCM data for playback |
+| `speaker.end()` | Signal end. Drains remaining audio, then emits `'finish'` |
+| `speaker.stop()` | Immediate stop. Discards remaining audio |
+| `speaker.isPlaying` | `true` while audio is being output |
+| `Speaker.devices()` | List available output devices |
+| `Speaker.version()` | Same as `Microphone.version()` |
+
+The module-level `outputDevices()` free function is equivalent to `Speaker.devices()`.
+
+## 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'
+  }
 }
 ```
 
-Full Rust guide: [here](crates/decibri/README.md).
+`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`.
 
-<br/>
+## API: Browser
 
-## Platform Support
+The browser API uses `getUserMedia` and `AudioWorklet`. It differs from the Node.js API because browser audio is fundamentally async.
+
+### `new Microphone(options?)` (browser)
 
-Supports:
+Same options as Node.js, plus:
 
-- Windows x64
-- macOS arm64
-- Linux x64
-- Linux arm64
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `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 |
 
-<br/>
+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 |
+| --- | --- | --- |
+| Start | Automatic on first read | `await mic.start()` |
+| Base class | Readable stream | Custom Emitter |
+| Data type | Buffer | Int16Array / Float32Array |
+| `devices()` | Sync, returns array | Async, returns Promise |
+| Sample rate | Native device rate | Resampled from native rate |
+| VAD | `'silero'` or `'energy'` | `'energy'` only |
 
 ## Voice Activity Detection
 
-Decibri ships two VAD modes:
+### Energy mode
 
-- **Energy mode**: lightweight RMS threshold.
-- **Silero mode**: ML-based detection using the Silero VAD v5 ONNX model. More accurate, especially in noisy environments. The model (~2.3 MB) is bundled; no downloads or API keys required.
+Lightweight RMS energy threshold. No model required.
 
-```python
-import decibri
+```javascript
+const mic = new Microphone({ vad: 'energy', vadThreshold: 0.01 });
+mic.on('speech', () => console.log('speaking'));
+mic.on('silence', () => console.log('silent'));
+```
 
-with decibri.Microphone(sample_rate=16000, vad="silero", vad_threshold=0.5) as mic:
-    for chunk in mic:
-        print(f"VAD score {mic.vad_score}; speaking={mic.is_speaking}")
-        break
+### Silero mode
+
+ML-based detection using the Silero VAD v5 model. More accurate than energy mode, especially in noisy environments.
+
+```javascript
+const mic = new Microphone({ vad: 'silero', vadThreshold: 0.5 });
+mic.on('speech', () => console.log('speaking'));
+mic.on('silence', () => console.log('silent'));
 ```
 
-The same VAD API is available in Node.js and Rust. Language-specific examples and tuning advice live in each binding's README.
+The Silero model (~2MB) ships inside the npm package. No downloads or API keys required. Silero mode is Node.js only.
 
-<br/>
+## Device Selection
 
-## Integrations
+```javascript
+const { Microphone } = require('decibri');
+
+// System default
+const mic = new Microphone();
+
+// By name (case-insensitive substring match)
+const mic = new Microphone({ device: 'USB' });
+
+// By index
+const devices = Microphone.devices();
+const mic = new Microphone({ device: devices[1].index });
+
+// By stable per-host ID (survives across enumerations)
+const mic = new Microphone({ device: { id: devices[1].id } });
+
+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 }
+// ]
+```
 
-Decibri pipes microphone audio directly into cloud and local speech services. Full guides at [decibri.com/docs/integrations](https://decibri.com/docs/integrations).
+## Examples
 
-| Provider | Environment | STT | TTS | VAD | KWS |
-| :--- | :---: | :---: | :---: | :---: | :---: |
-| OpenAI Realtime | Cloud | ✅ | ✅ | | |
-| Deepgram | Cloud | ✅ | ✅ | | |
-| AssemblyAI | Cloud | ✅ | | | |
-| Mistral Voxtral | Cloud | ✅ | | | |
-| AWS Transcribe | Cloud | ✅ | | | |
-| Google Speech | Cloud | ✅ | ✅ | | |
-| Azure Speech | Cloud | ✅ | ✅ | | |
-| Sherpa-ONNX | Local | ✅ | ✅ | ✅ | ✅ |
-| Whisper.cpp | Local | ✅ | | | |
+Runnable examples ship with the package. After `npm install decibri`, find them under `node_modules/decibri/examples/`. From a clone of the repo they live at `npm/decibri/examples/`.
 
-<br/>
+```bash
+# Capture to WAV file (no extra dependencies)
+node node_modules/decibri/examples/wav-capture.js
+
+# Stream to WebSocket (requires: npm install ws)
+node node_modules/decibri/examples/websocket-server.js   # terminal 1
+node node_modules/decibri/examples/websocket-stream.js   # terminal 2
+```
 
-## Architecture
+## Migrating from 3.x
 
-Decibri is built on a single Rust core. The same audio engine powers all three language bindings, ensuring consistent behavior regardless of which language you use.
+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.
 
-Python and Node.js install pre-built native binaries for your platform. Browsers run the same API via a JavaScript implementation that ships inside the npm package.
+## Platform Support
 
-<br/>
+| Platform | Architecture | Audio Backend |
+| --- | --- | --- |
+| Windows | x64 | WASAPI |
+| macOS | arm64 | CoreAudio |
+| Linux | x64 | ALSA |
+| Linux | arm64 | ALSA |
+| Browser | - | Web Audio API (AudioWorklet) |
 
-## Contributing
+## How It Works
 
-[Issues](https://github.com/decibri/decibri/issues) and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.
+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.
 
-<br/>
+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
+
+- **Source code & issues**: [github.com/decibri/decibri](https://github.com/decibri/decibri)
+- **Provider integrations** (OpenAI, Deepgram, AssemblyAI): [decibri.com/docs](https://decibri.com/docs)
 
 ## License
 
-Apache-2.0 © 2026 [Decibri](https://github.com/decibri).
+Apache-2.0. See [LICENSE](https://github.com/decibri/decibri/blob/main/LICENSE) for details.
+
+Copyright (c) 2026 Decibri.

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

@@ -115,5 +115,5 @@ export interface OutputDeviceInfoJs {
 /** Version info returned to JS. */
 export interface VersionInfoJs {
   decibri: string
-  portaudio: string
+  audioBackend: string
 }