decibri 4.4.2 → 5.1.0

package/CHANGELOG.md

@@ -9,7 +9,37 @@ For other decibri packages, see:
 - Rust crate: [crates/decibri/CHANGELOG.md](../../crates/decibri/CHANGELOG.md)
 - Python wheel: [bindings/python/CHANGELOG.md](../../bindings/python/CHANGELOG.md)
 
-## [Unreleased]
+## [5.1.0] - 2026-07-17
+
+### Added
+
+- `File`, an offline source: the same conditioning options as `Microphone` over a WAV file (`new File(path)` synchronously, `await File.open(path)` off the event loop) or a `Float32Array` of samples (`File.buffer(samples, { inputRate })`; a raw `Buffer` of bytes is rejected as ambiguous), delivered as a finite Readable stream of conditioned chunks.
+- Whole-file speech analysis: `file.analyze()` (also spelled `file.analyse()`) resolves to a `VadReport` with per-window `scores` (`{ start, end, vadScore, isSpeech }`) and merged speech `segments` (`{ start, end }`), all in seconds of file time. Requires `vad: 'silero'`; a `File` opened without `vad` rejects with `analysis requires VAD`.
+- Per-chunk VAD on files: `vadScore` and the `speech` / `silence` events alongside the stream, with the speaking holdoff measured in file time (sample positions) rather than wall-clock time, so processing speed never changes the reported events.
+
+## [5.0.0] - 2026-06-24
+
+### Added
+
+- A device or driver failure during streaming now surfaces as a `DecibriError` with the dedicated `code` `'DEVICE_FAILED'`, and a non-ORT ONNX backend failure as `'ONNX_BACKEND_FAILED'`, instead of the generic `'DECIBRI_ERROR'`. Both are catchable by branching on `err.code`; the message text is unchanged.
+- `dcRemoval`: an opt-in `Microphone` option that removes a constant (DC) offset from the captured audio with a one-pole DC-blocking high-pass. Set `true` to enable it; omit it or set `false` to leave it off (the default), which keeps the capture path byte-identical. Pure DSP: no bundled file or download is needed. It runs first in the chain, before denoise, and is same-length with no added latency, so `vadScore` and the `speech` / `silence` events are unaffected.
+- `highpass`: an opt-in `Microphone` option that applies a high-pass filter to the captured audio, removing low-frequency rumble below the voice band. The accepted values are the cutoff in Hz, `80` (an 80 Hz second-order Butterworth high-pass) or `100` (a 100 Hz one); omit it to leave the high-pass off (the default), which keeps the capture path full-range. Pure DSP: no bundled file or download is needed. It runs after denoise in the chain and adds no latency, so `vadScore` and the `speech` / `silence` events are unaffected. An out-of-set value throws a `RangeError`. The closed cutoff set is designed to grow (further cutoffs are additive).
+- `agc`: an opt-in `Microphone` option that applies automatic gain control to the captured audio, driving the running level toward a target with a smoothed, rate-limited gain. The value is a target level in dBFS (an integer in -40 to -3, typical -18); omit it to leave AGC off (the default), which keeps the level untouched. Pure DSP: no bundled file or download is needed. It runs after the high-pass step and adds no latency, so `vadScore` and the `speech` / `silence` events are unaffected. The opening is delivered at its natural level and reaches the target within tens of milliseconds (no opening window of wrong gain). An out-of-range value throws a `RangeError`.
+- `limiter`: an opt-in `Microphone` option that applies a peak limiter to the captured audio, holding the signal at or below a sample-peak ceiling, the safety net that catches a transient the AGC's gain would let through. The value is a ceiling in dBFS (a number in -3.0 to 0.0, typical -1.0); omit it to leave the limiter off (the default), which keeps the level untouched. Pure DSP: no bundled file or download is needed. It runs last in the chain, after the AGC step, and adds no latency, so `vadScore` and the `speech` / `silence` events are unaffected. No output sample ever exceeds the ceiling, even on an instantaneous transient. An out-of-range value throws a `RangeError`.
+- `denoise`: an opt-in `Microphone` option that runs a bundled single-channel speech-enhancement model over the captured audio. The only accepted value is `'fastenhancer-t'`; omit it to leave denoise off (the default), which keeps the capture path unchanged. The model ships with the package, so no path or download is needed. The delivered `'data'` chunks carry the enhanced audio; VAD reads the pre-enhancement signal, so `vadScore` and the `speech` / `silence` events are unaffected. An unknown model name throws a `TypeError`. A denoise model-load failure raises a dedicated `MODEL_LOAD_FAILED` `OrtError` via `wrapNativeError`; note that a failure surfaced from `start()` is delivered on the `'error'` event as the raw native error without the decibri `code` attached (as with device-open failures), so match it by message there.
+
+### Changed
+
+- A microphone whose native sample rate differs from the configured `sampleRate` is now resampled to the requested rate in the engine, so capture delivers audio at exactly the configured rate on every device. The device is opened at its native rate and decibri resamples (anti-aliased polyphase) to the target; a device already at the requested rate is unchanged (no resample). Chunk size and the reported rate are unchanged (still `framesPerBuffer * outputChannels * bytesPerSample` at the configured rate). Previously the requested rate was handed to the platform audio backend, which delivered it only when the device or OS could. Breaking for consumers whose device's native rate differs from the configured rate: the delivered samples are now decibri-resampled.
+- Microphone capture is now mono only, narrowing a capability that shipped in 4.x. decibri 4.x delivered interleaved multichannel audio when a microphone was opened with `channels` greater than `1`; 5.0 captures mono, and the `channels` option accepts only `1` (the default). A value greater than `1` now throws a `RangeError` (`multichannel capture is not supported; channels must be 1 (mono)`), a clear error rather than a silent substitution of mono. The `channels` option is retained and the emitted `'data'` chunks keep their channel-general shape (`framesPerBuffer * bytesPerSample`, mono today), so multichannel can return later as an additive change rather than a further break: a future release may accept a value greater than `1` by delivering true interleaved multichannel. The intended longer-term multichannel direction is array ingest (consuming several channels internally for processing such as beamforming or array noise reduction while still delivering one conditioned stream), which is distinct from raw multichannel delivery. The default single-channel capture is unchanged. Breaking for consumers that opened a microphone with more than one channel: pass `channels: 1` or omit it.
+- Capture now emits a final, possibly-shorter `'data'` chunk at stream close (on `stop()`), carrying the buffered tail, before `'end'`. Steady-state chunks are unchanged (still exactly `framesPerBuffer * channels * bytesPerSample`); only the last chunk before `'end'` may be shorter, and no captured audio is dropped. Internally the binding now re-blocks through the Rust core instead of a binding-side accumulator, and `stop()` defers the stream's end-of-stream signal by one tick so the flushed tail is delivered before `'end'` rather than dropped.
+- The `vad` option now accepts a config object `{ model, threshold, holdoffMs }` (a `VadOptions`) alongside the `'silero'` / `'energy'` shorthand, and the flat `vadThreshold` / `vadHoldoff` options are removed. The shorthand is unchanged and keeps the default threshold (0.5 for `'silero'`, 0.01 for `'energy'`) and 300 ms holdoff; only code that tuned the threshold or holdoff migrates, by passing them on the object (`vad: { model: 'silero', threshold: 0.6, holdoffMs: 200 }`). An out-of-range threshold or a negative holdoff throws a `RangeError`, an unknown model a `TypeError`. Passing the removed `vadThreshold` or `vadHoldoff` throws a `TypeError`. The same object form applies to the browser build, where `model` is `'energy'`. Breaking for consumers that set `vadThreshold` or `vadHoldoff`; detection, the `vadScore` getter, and the `speech` / `silence` events are unchanged.
+
+### Fixed
+
+- Energy-mode VAD (`vad: 'energy'`) now reads the signal before the opt-in capture enhancement, so enabling an enhancement step (`denoise`, `highpass`, `agc`, `limiter`) no longer changes `vadScore` or the `speech` / `silence` events, matching the guarantee Silero mode already had. The energy RMS is computed natively on the pre-enhancement signal; previously it was computed on the delivered (post-enhancement) audio, so an enhancement step shifted the score (`agc` most of all, since it drives the delivered level toward its target, which could defeat energy endpointing). Energy detection with no enhancement enabled is unchanged.
+- Resampled capture (a device whose native rate differs from the configured `sampleRate`) no longer drops the resampler's group-delay tail at stream close: the final, possibly-shorter `'data'` chunk(s) before `'end'` now carry it, so the complete resampled signal is delivered. A device already at the requested rate (no resample) is unchanged.
+- On macOS, the microphone-permission error message now reads "System Settings > Privacy & Security" (the modern macOS wording) instead of the pre-Ventura "System Preferences > Security & Privacy".
 
 ## [4.4.2] - 2026-06-12
 
@@ -137,7 +167,7 @@ Error message wording on shipped `DecibriError` variants has historically been s
 
 ## [3.3.0] - 2026-04-23
 
-Groundwork release for upcoming P3 Python bindings. Adds a stable-ID form for audio device selection (`DeviceSelector::Id`), fixes a long-standing direction bug in `DecibriError::DeviceNotFound` when resolving output devices, exposes both in the Node binding, and extends the reference documentation with a Cargo feature flag guide plus additional crate-level rustdoc. No Node.js or browser API break. Direct Rust crate consumers pattern-matching on `DeviceSelector` or struct-literal-constructing `DeviceInfo` / `OutputDeviceInfo` need to update for the new `#[non_exhaustive]` attributes (see Migration notes below).
+Groundwork release for upcoming Python bindings. Adds a stable-ID form for audio device selection (`DeviceSelector::Id`), fixes a long-standing direction bug in `DecibriError::DeviceNotFound` when resolving output devices, exposes both in the Node binding, and extends the reference documentation with a Cargo feature flag guide plus additional crate-level rustdoc. No Node.js or browser API break. Direct Rust crate consumers pattern-matching on `DeviceSelector` or struct-literal-constructing `DeviceInfo` / `OutputDeviceInfo` need to update for the new `#[non_exhaustive]` attributes (see Migration notes below).
 
 ### Changed
 
@@ -160,7 +190,7 @@ Groundwork release for upcoming P3 Python bindings. Adds a stable-ID form for au
 ### Internal
 
 - `DeviceDirection` trait gains a `not_found_error(String) -> DecibriError` method so `resolve_device_generic`'s `Name` and `Id` arms produce direction-correct errors via the `Input` / `Output` impls.
-- Unit tests for `Arc<Mutex<CaptureStream>>` confirming the wrapping is `Send + Sync` (compile-time assertion) and serializes concurrent access across two threads (runtime test with `Barrier`). Documents the wrapping strategy the P3 Python binding will apply to share `!Sync` capture streams across Python threads.
+- Unit tests for `Arc<Mutex<CaptureStream>>` confirming the wrapping is `Send + Sync` (compile-time assertion) and serializes concurrent access across two threads (runtime test with `Barrier`). Documents the wrapping strategy the Python binding will apply to share `!Sync` capture streams across Python threads.
 - Crate-level rustdoc additions in `lib.rs`: a section on ORT error construction FFI side effects (the `ortsys![CreateStatus]` dylib-load trigger that motivates the `OrtPathInvalid` split from `OrtLoadFailed`) and a section on fork safety (guidance for Python `multiprocessing` consumers to use `spawn` start method).
 - `lib.rs` rustdoc "Feature flags" section cross-references `docs/features.md` for consumers wanting the deep-dive reference.
 - Em-dash cleanup across 19 code locations in `lib.rs`, `capture.rs`, `output.rs`, `vad.rs`, `error.rs`, `vad_integration.rs`, and `vad_ort_load_failure.rs`. Per CLAUDE.md, the codebase forbids em dashes; these were pre-existing violations.

package/MIGRATION.md

@@ -5,6 +5,76 @@ vocabulary that matches the Rust and Python packages, and tidies several option
 and return shapes. This guide lists every breaking change with before and after
 code.
 
+## Breaking in 5.0.0: the vad config object
+
+decibri 5.0.0 replaces the flat `vadThreshold` and `vadHoldoff` options with a
+single `vad` config object that carries the model selector and its policy. The
+`vad: 'silero'` and `vad: 'energy'` shorthand is unchanged and still uses the
+default threshold (0.5 for `'silero'`, 0.01 for `'energy'`) and a 300 ms
+holdoff, so only code that tuned the threshold or holdoff needs to migrate.
+Move those values onto the object.
+
+Before:
+
+```js
+new Microphone({ vad: 'silero', vadThreshold: 0.6, vadHoldoff: 200 });
+new Microphone({ vad: 'energy', vadThreshold: 0.02 });
+```
+
+After:
+
+```js
+new Microphone({ vad: { model: 'silero', threshold: 0.6, holdoffMs: 200 } });
+new Microphone({ vad: { model: 'energy', threshold: 0.02 } });
+```
+
+`vadThreshold` and `vadHoldoff` are no longer accepted; passing either throws a
+`TypeError`. The shorthand without tuning is unchanged:
+
+```js
+new Microphone({ vad: 'silero' }); // unchanged
+new Microphone({ vad: false });    // unchanged; the default
+```
+
+The same realignment applies to the browser build, where the object's `model`
+is `'energy'` (the only browser detector): `vad: { model: 'energy', threshold: 0.02, holdoffMs: 200 }`.
+
+## Breaking in 5.0.0: mono-only capture
+
+decibri 4.x delivered interleaved multichannel audio when a microphone was
+opened with `channels` greater than `1`. decibri 5.0.0 narrows capture to mono:
+the `channels` option accepts only `1` (the default), and a value greater than
+`1` throws a `RangeError` instead of being captured. If your code opened a
+microphone with more than one channel, pass `channels: 1` (or omit it).
+
+Before:
+
+```js
+new Microphone({ channels: 2 }); // 4.x: interleaved stereo capture
+```
+
+After:
+
+```js
+new Microphone({ channels: 1 }); // 5.0: mono (or omit channels entirely)
+new Microphone();                // unchanged; mono is the default
+```
+
+A value greater than `1` now throws:
+
+```js
+new Microphone({ channels: 2 });
+// RangeError: multichannel capture is not supported; channels must be 1 (mono)
+```
+
+The `channels` option and the channel-general `'data'` chunk shape are kept, so
+multichannel may return later as an additive change (a future release accepting
+a value greater than `1` by delivering true interleaved multichannel) rather
+than a further break. The intended longer-term multichannel direction is array
+ingest (consuming several channels internally for processing such as
+beamforming or array noise reduction while still delivering one conditioned
+stream), which is distinct from raw multichannel delivery.
+
 ## New in 4.2.0 (additive, nothing to migrate)
 
 decibri 4.2.0 is a browser-only, additive release. Code written for 4.1.0 keeps

package/README.md

@@ -30,6 +30,22 @@ mic.on('data', (chunk) => { /* Buffer of Int16 PCM samples */ });
 setTimeout(() => mic.stop(), 5000);
 ```
 
+### Condition and analyze a file
+
+```javascript
+const { File } = require('decibri');
+
+// The same conditioning chain as the live microphone, over a WAV file.
+const file = await File.open('clip.wav', { denoise: 'fastenhancer-t', highpass: 80 });
+file.on('data', (chunk) => { /* Buffer of conditioned Int16 PCM */ });
+file.on('end', () => console.log('done'));
+
+// Whole-file speech analysis (a live stream cannot do this).
+const f = await File.open('clip.wav', { vad: 'silero' });
+const report = await f.analyze();
+for (const s of report.segments) console.log(s.start, s.end); // seconds
+```
+
 ### Play audio
 
 ```javascript
@@ -82,18 +98,21 @@ Creates a Readable stream that captures from the microphone.
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `sampleRate` | number | 16000 | Samples per second (1000 to 384000) |
-| `channels` | number | 1 | Input channels (1 to 32) |
+| `channels` | number | 1 | Mono only: the only accepted value is `1`; a value greater than `1` throws a `RangeError` |
 | `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 |
+| `vad` | `false` \| `'silero'` \| `'energy'` \| `VadOptions` | `false` | Voice activity detection: disabled, the Silero ML model, an RMS energy threshold, or a config object `{ model, threshold, holdoffMs }` to tune the policy |
 | `modelPath` | string | bundled model | Path to the Silero model. Only used when `vad` is `'silero'` |
+| `dcRemoval` | boolean | off | Remove a constant (DC) offset with a one-pole DC-blocking high-pass. Runs first in the chain; same-length, no added latency |
+| `denoise` | `'fastenhancer-t'` | off | Single-channel speech-enhancement (denoise) model. The model ships in the package; no path or download needed |
+| `highpass` | `80` \| `100` | off | High-pass cutoff in Hz (second-order Butterworth) that removes low-frequency rumble. Runs after denoise. Out-of-set values throw a `RangeError` |
+| `agc` | number | off | AGC target level in dBFS, an integer in -40 to -3 (typical -18). Runs after the high-pass. Out-of-range throws a `RangeError` |
+| `limiter` | number | off | Peak limiter ceiling in dBFS, a number in -3.0 to 0.0 (typical -1.0). Runs last. Out-of-range throws a `RangeError` |
 
 Standard `ReadableOptions` (e.g. `highWaterMark`) are also accepted.
 
-`vad: true` is not accepted; pass the mode explicitly as `vad: 'silero'` or `vad: 'energy'`.
+`vad: true` is not accepted; pass the mode explicitly as `vad: 'silero'` or `vad: 'energy'`. The string shorthand uses the default threshold (0.5 for `'silero'`, 0.01 for `'energy'`) and a 300 ms holdoff; to tune them pass a config object: `vad: { model: 'silero', threshold: 0.6, holdoffMs: 200 }`. The `threshold` (`0`–`1`) and `holdoffMs` fields are optional and fall back to those defaults.
 
 ### Methods
 
@@ -120,7 +139,7 @@ The module-level `inputDevices()` and `version()` free functions are equivalent
 | `'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 |
+| `'silence'` | - | VAD: audio below threshold for the holdoff period |
 | `'end'` | - | Stream ended |
 | `'error'` | Error | An error occurred |
 
@@ -267,7 +286,7 @@ To verify playback in real browsers, open `examples/browser-speaker-test.html` (
 Lightweight RMS energy threshold. No model required.
 
 ```javascript
-const mic = new Microphone({ vad: 'energy', vadThreshold: 0.01 });
+const mic = new Microphone({ vad: { model: 'energy', threshold: 0.01 } });
 mic.on('speech', () => console.log('speaking'));
 mic.on('silence', () => console.log('silent'));
 ```
@@ -277,13 +296,59 @@ mic.on('silence', () => console.log('silent'));
 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 });
+const mic = new Microphone({ vad: { model: 'silero', threshold: 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. Silero mode is Node.js only.
 
+## decibri ACE (audio conditioning)
+
+decibri ACE (Audio Capture Engine) is decibri's opt-in audio front-end for speech. It is a conditioning chain that runs on the captured audio before it reaches your `'data'` handler. Every stage is off by default, runs on-device, and needs no API key. With nothing enabled the capture path is byte-identical to plain capture.
+
+The stages run in a fixed order. Enable any subset:
+
+| Stage | Option | Range |
+| --- | --- | --- |
+| DC removal | `dcRemoval: true` | boolean |
+| Denoise | `denoise: 'fastenhancer-t'` | the one bundled model |
+| High-pass | `highpass: 80` or `100` | Hz |
+| AGC | `agc: -18` | dBFS, -40 to -3 |
+| Limiter | `limiter: -1.0` | dBFS, -3.0 to 0.0 |
+
+```javascript
+const { Microphone } = require('decibri');
+
+const mic = new Microphone({
+  sampleRate: 16000,
+  denoise: 'fastenhancer-t',   // bundled speech-enhancement model
+  highpass: 80,                // remove low-frequency rumble
+  agc: -18,                    // target level in dBFS
+  limiter: -1.0,               // peak ceiling in dBFS
+  vad: { model: 'silero', threshold: 0.5 },
+});
+
+mic.on('data', (chunk) => { /* Buffer of conditioned Int16 PCM */ });
+mic.on('speech', () => console.log('speech'));
+mic.on('silence', () => console.log('silence'));
+setTimeout(() => mic.stop(), 5000);
+```
+
+VAD reads the signal before the chain, so `vadScore` and the `'speech'` / `'silence'` events are unaffected by which conditioning stages you enable. The conditioning chain runs in the native Node.js capture path; the browser build does not include it.
+
+## API: File (offline source)
+
+Everything a `Microphone` does to live audio, `File` does to audio you already have: the same conditioning options, the same Readable stream of conditioned chunks (finite: it ends at EOF), and the same opt-in `vad`. Because a `File` is a complete recording, it can also analyze the whole recording for speech.
+
+- `await File.open(path, options?)`: read a WAV off the event loop (recommended, like `Microphone.open`).
+- `new File(path, options?)`: the same result, synchronous (blocks on disk I/O; fine for scripts).
+- `File.buffer(samples, options)`: wrap a `Float32Array` of samples you already hold. `options.inputRate` is required (raw samples carry no header); a raw `Buffer` of bytes is rejected as ambiguous.
+- `await file.analyze()` (also spelled `analyse()`): consume the source and resolve to a `VadReport` of per-window `scores` (`{ start, end, vadScore, isSpeech }`) and merged speech `segments` (`{ start, end }`), in seconds of file time. Requires `vad: 'silero'`; a `File` opened without `vad` rejects with `analysis requires VAD`.
+- `file.vadScore`, `'speech'` / `'silence'` events: per-chunk VAD alongside the stream, with the holdoff measured in FILE time (sample positions), never wall-clock time, so processing speed does not change the reported events.
+
+Options mirror `Microphone` (`sampleRate`, `dtype`, `vad`, `dcRemoval`, `denoise`, `highpass`, `agc`, `limiter`); the live-capture options (`device`, `channels`, `framesPerBuffer`) do not apply. Iteration and analysis are separate single passes: construct one `File` per operation. Note: Node also has a global `File` (the web File API); import decibri's explicitly to avoid shadowing surprises.
+
 ## Device Selection
 
 ```javascript

package/examples/README.md

@@ -71,9 +71,10 @@ npx localtunnel --port 8080
 ### Regenerating the browser bundle
 
 `decibri.browser.js` is generated from the package's browser entry
-(`../src/browser/index.js`). Regenerate it after changing the browser source
-with any bundler that resolves the package's `browser` entry, for example:
+(`../src/browser/index.js`) with rolldown, the bundler used to produce the
+checked-in build. Regenerate it after changing the browser source so the
+bundle stays in sync:
 
 ```bash
-npx esbuild ../src/browser/index.js --bundle --format=iife --global-name=decibri --outfile=decibri.browser.js
+npx rolldown ../src/browser/index.js --format iife --name decibri --file decibri.browser.js
 ```

package/examples/decibri.browser.js

@@ -70,7 +70,7 @@ var decibri = (function() {
 	var require_decibri_browser = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		const { Emitter } = require_emitter();
 		const { WORKLET_SOURCE } = require_worklet_inline();
-		const VERSION = "4.2.0";
+		const VERSION = "5.1.0";
 		/**
 		* Browser microphone capture.
 		*
@@ -97,13 +97,27 @@ var decibri = (function() {
 				this._started = false;
 				this._starting = null;
 				this._stopRequested = false;
+				if (options.vadThreshold !== void 0 || options.vadHoldoff !== void 0) throw new TypeError("vadThreshold and vadHoldoff are no longer supported. Pass them on the vad config object: vad: { model: 'energy', threshold: 0.01, holdoffMs: 300 }.");
 				const vad = options.vad ?? false;
+				let vadThreshold = .01;
+				let vadHoldoff = 300;
 				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 ?? .01;
-				this._vadHoldoff = options.vadHoldoff ?? 300;
+				else if (vad !== null && typeof vad === "object" && !Array.isArray(vad)) {
+					if (vad.model !== "energy") throw new TypeError(`Invalid vad model: ${JSON.stringify(vad.model)}. Expected 'energy'.`);
+					this._vad = true;
+					if (vad.threshold !== void 0) {
+						if (vad.threshold < 0 || vad.threshold > 1) throw new TypeError(`threshold must be between 0 and 1, got ${vad.threshold}`);
+						vadThreshold = vad.threshold;
+					}
+					if (vad.holdoffMs !== void 0) {
+						if (vad.holdoffMs < 0) throw new TypeError(`holdoffMs must be >= 0, got ${vad.holdoffMs}`);
+						vadHoldoff = vad.holdoffMs;
+					}
+				} else throw new TypeError(`Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'energy', or a config object { model, threshold, holdoffMs }.`);
+				this._vadThreshold = vadThreshold;
+				this._vadHoldoff = vadHoldoff;
 				this._vadScore = 0;
 				this._isSpeaking = false;
 				this._silenceTimer = null;
@@ -119,8 +133,6 @@ var decibri = (function() {
 				if (this._channels < 1 || this._channels > 32) throw new TypeError(`channels must be between 1 and 32, got ${this._channels}`);
 				if (this._framesPerBuffer < 64 || this._framesPerBuffer > 65536) throw new TypeError(`frames per buffer must be between 64 and 65536, got ${this._framesPerBuffer}`);
 				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}`);
-				if (this._vadHoldoff < 0) throw new TypeError(`vadHoldoff must be >= 0, got ${this._vadHoldoff}`);
 			}
 			/**
 			* Start microphone capture.

package/index.d.ts

@@ -78,6 +78,52 @@ export declare class DecibriOutputBridge {
   static version(): VersionInfoJs
 }
 
+/**
+ * Native offline-source handle exposed to Node.js via napi-rs. The public
+ * `File` Readable lives in the JS wrapper; consumers construct that, not
+ * this handle, directly.
+ */
+export declare class FileHandle {
+  /**
+   * Open a WAV path as an offline source, synchronously (blocks on disk
+   * I/O; the JS wrapper's async `File.open` uses `openAsync` instead).
+   */
+  static open(path: string, options?: FileOptions | undefined | null): FileHandle
+  /**
+   * Open a WAV path without blocking the JS event loop: the disk read,
+   * WAV parse, and chain construction run on the libuv thread pool.
+   */
+  static openAsync(path: string, options?: FileOptions | undefined | null): Promise<unknown>
+  /**
+   * Wrap in-memory samples as an offline source. `samples` are mono f32 in
+   * [-1.0, 1.0]; `inputRate` is their native rate (raw samples carry no
+   * header). No I/O, so construction is synchronous.
+   */
+  static buffer(samples: Float32Array, inputRate: number, options?: FileOptions | undefined | null): FileHandle
+  /**
+   * Pull the next conditioned chunk, advancing the per-chunk VAD score on
+   * the pre-conditioning feed. Returns `null` once the source is fully
+   * delivered (after the end-of-stream tail) or already consumed.
+   */
+  readChunk(): Buffer | null
+  /**
+   * Consume the source with the core's whole-recording analysis, off the
+   * JS event loop. Resolves to the `VadReport`; a `File` built without VAD
+   * rejects with the core's typed error, never a silently constructed
+   * detector.
+   */
+  analyze(): Promise<unknown>
+  /** Release the source. Idempotent; a closed File reads as ended. */
+  close(): void
+  /**
+   * Most recent per-chunk VAD score (0.0 to 1.0), computed on the
+   * pre-conditioning feed. 0.0 before the first chunk or with VAD off.
+   */
+  get vadProbability(): number
+  /** The target output rate every delivered chunk carries. */
+  get sampleRate(): number
+}
+
 /**
  * Options passed from JS constructor.
  *
@@ -111,6 +157,40 @@ export interface DecibriOptions {
   device?: any
   vadMode?: string
   modelPath?: string
+  /**
+   * Capture DC-removal toggle. When `true`, removes a constant (DC) offset
+   * from the captured audio with a one-pole DC-blocking high-pass, applied
+   * first in the transform chain (before denoise). Absent or `false` leaves
+   * it off (the default), a byte-identical no-op. Pure DSP: no bundled file
+   * and no model path, like `highpass`.
+   */
+  dcRemoval?: boolean
+  /**
+   * Capture denoise model selector. The only accepted value is
+   * `'fastenhancer-t'`; absent leaves denoise off. The JS wrapper resolves
+   * the bundled model file and passes its path through `denoise_model_path`.
+   */
+  denoise?: string
+  /**
+   * Capture high-pass filter cutoff in Hz. The accepted values are `80` (an
+   * 80 Hz second-order Butterworth high-pass) and `100` (a 100 Hz one);
+   * absent leaves the high-pass off. Pure DSP: no bundled file and no model
+   * path, unlike `denoise`.
+   */
+  highpass?: number
+  /**
+   * Capture AGC target level in dBFS: an integer in `-40..=-3` (typical -18);
+   * absent leaves AGC off. Drives the captured level toward the target. Pure
+   * DSP: no bundled file and no model path, like `highpass`.
+   */
+  agc?: number
+  /**
+   * Capture limiter ceiling in dBFS (sample-peak): a number in `-3.0..=0.0`
+   * (typical -1.0); absent leaves the limiter off. Holds the captured signal
+   * at or below the ceiling, catching a peak the AGC would let through. Pure
+   * DSP: no bundled file and no model path, like `agc`.
+   */
+  limiter?: number
 }
 
 /** Options passed from JS constructor for output. */
@@ -136,6 +216,26 @@ export interface DeviceInfoJs {
   isDefault: boolean
 }
 
+/**
+ * Options passed from the JS `File` wrapper. The conditioning fields mirror
+ * `DecibriOptions` exactly; the live-capture-only fields (device, channels,
+ * framesPerBuffer) do not apply to an offline source. `vadThreshold` and
+ * `vadHoldoffMs` are internal plumbing (the user passes them on the `vad`
+ * config object; the wrapper resolves them), hidden from the generated
+ * TypeScript like `ortLibraryPath`.
+ */
+export interface FileOptions {
+  sampleRate?: number
+  format?: string
+  vadMode?: string
+  modelPath?: string
+  dcRemoval?: boolean
+  denoise?: string
+  highpass?: number
+  agc?: number
+  limiter?: number
+}
+
 /** Output device info returned to JS. */
 export interface OutputDeviceInfoJs {
   index: number
@@ -150,6 +250,32 @@ export interface OutputDeviceInfoJs {
   isDefault: boolean
 }
 
+/** One merged speech region of a recording, in seconds of file time. */
+export interface Segment {
+  start: number
+  end: number
+}
+
+/**
+ * The whole-recording analysis `File.analyze()` resolves to: per-window
+ * scores and merged speech segments, in file order.
+ */
+export interface VadReport {
+  scores: Array<VadWindow>
+  segments: Array<Segment>
+}
+
+/**
+ * One scored voice-activity window of a recording: `start` / `end` in
+ * seconds of file time, the speech probability, and the raw threshold test.
+ */
+export interface VadWindow {
+  start: number
+  end: number
+  vadScore: number
+  isSpeech: boolean
+}
+
 /** Version info returned to JS. */
 export interface VersionInfoJs {
   decibri: string