decibri 5.2.2 → 5.2.3

package/CHANGELOG.md

@@ -6,8 +6,36 @@ Changes to the decibri npm package, published to npmjs.com. Tags use the `npm-v*
 
 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)
+- Rust core: [crates/decibri/CHANGELOG.md](../../crates/decibri/CHANGELOG.md)
+- Python package: [bindings/python/CHANGELOG.md](../../bindings/python/CHANGELOG.md)
+
+## [5.2.3] - 2026-07-27
+
+### Added
+
+- `underrunCount`: a read-only accessor on `Speaker` exposing the core stream's silence-fill counter, in samples. 0 while the producer keeps the queue fed; a rising value means playback is papering over gaps with silence.
+- `File.sampleRate` and `File.inputRate`: read-only accessors reporting the rate every delivered chunk carries and the source's own rate, taken from the WAV header or from the `inputRate` passed to `File.buffer`. They differ when the source was resampled, which is the only way a caller learns that it was. Both read for the life of the `File`, including after the source is consumed or closed.
+
+### Changed
+
+- **The browser build rejects a non-numeric `vad` `threshold` or `holdoffMs`, which it accepted before.** A string, or any other non-number, was stored as given; every later score comparison against it evaluated false, so the detector never fired and nothing reported why. A non-numeric `holdoffMs` reached the silence timer directly. Both now raise a `TypeError`, with the Node build's messages: `vad threshold must be a number` and `vad holdoffMs must be a number`.
+- **The browser build raises `RangeError` where it raised `TypeError` for an out-of-range `threshold`, `holdoffMs` and `sampleRate`, and carries the Node build's messages.** The messages are now `vad threshold must be between 0 and 1`, `vad holdoffMs must be non-negative` and `sample rate must be between 1000 and 384000`; they previously read `threshold must be between 0 and 1, got <value>`, `holdoffMs must be >= 0, got <value>` and `sample rate must be between 1000 and 384000, got <value>`. Code that catches `TypeError` for these three options, or that matches the old message text, needs updating.
+
+- Every error that reaches a consumer is a `DecibriError` carrying a `code`. The `Microphone` `'error'` event and the `Speaker` `write()` and `end()` paths previously delivered the raw native error, which reported `name: 'Error'` and the native status string `'GenericFailure'` in `code` for a permission denial, a device loss and a failed open alike, and did not satisfy `instanceof DecibriError`.
+- A playback device that fails mid-stream is reported as `code: 'DEVICE_FAILED'` on the `Speaker` `'error'` event, or as a rejection from `writeAsync()` and `drainAsync()`, instead of the generic closed-stream error. It surfaces on the next write or drain, so a producer that has stopped writing is not told; `isPlaying` goes false immediately either way.
+- `end()` reports a device that failed while the queued tail was still playing, instead of resolving silently. The stream is still stopped and the device released on that path.
+
+- Every failure the core classifies as a `DecibriError` carries its own `code`. Ten failures that reported the generic `'DECIBRI_ERROR'` before now carry a distinct code: `'ALREADY_RUNNING'`, `'STREAM_OPEN_FAILED'`, `'STREAM_START_FAILED'`, `'PERMISSION_DENIED'`, `'MICROPHONE_STREAM_CLOSED'`, `'SPEAKER_STREAM_CLOSED'`, `'RESAMPLE_CONFIG_INVALID'`, `'FILE_READ_FAILED'`, `'WAV_INVALID'` and `'FORK_AFTER_ORT_INIT'`. Every code that existed before keeps its value, and `instanceof DecibriError` is unaffected for these ten. `'DECIBRI_ERROR'` remains the code for a failure decibri has not classified.
+- A bad `agc` target, a bad `limiter` ceiling, and a multichannel `channels` value now raise `RangeError` rather than a `DecibriError` with `code: 'DECIBRI_ERROR'`, matching what the wrapper's own checks already raise for the same inputs.
+
+### Fixed
+
+- A capture failure raised as `start()` is called (a failed device open, a denied permission) reaches the `'error'` event as a `DecibriError`, instead of escaping as a raw native error.
+- A missing Silero or denoise model file throws an `OrtError` carrying `code: 'VAD_MODEL_LOAD_FAILED'` or `'MODEL_LOAD_FAILED'`, instead of a plain `Error` with no `code` that was not a `DecibriError`. The message is unchanged.
+- `Microphone.devices()` and `Speaker.devices()` report an enumeration failure as a `DeviceError` with `code: 'DEVICE_ENUMERATION_FAILED'`, instead of letting the raw native error escape. The same applies to the enumeration performed when a numeric `device` index is resolved.
+- A conditioning failure during capture (a denoise or VAD stage that errors mid-stream) reaches the `'error'` event with its own code, instead of ending the stream with no event.
+- `File` opens WAV files using the WAVE_FORMAT_EXTENSIBLE container when their samples are 16-bit PCM or 32-bit float; they were rejected as an unsupported encoding.
+- `File` opens WAV files whose `data` chunk precedes their format chunk; they were rejected as missing the format chunk.
 
 ## [5.2.2] - 2026-07-25
 

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 = "5.2.2";
+		const VERSION = "5.2.3";
 		/**
 		* Browser microphone capture.
 		*
@@ -108,11 +108,13 @@ var decibri = (function() {
 					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}`);
+						if (typeof vad.threshold !== "number" || Number.isNaN(vad.threshold)) throw new TypeError("vad threshold must be a number");
+						if (vad.threshold < 0 || vad.threshold > 1) throw new RangeError("vad threshold must be between 0 and 1");
 						vadThreshold = vad.threshold;
 					}
 					if (vad.holdoffMs !== void 0) {
-						if (vad.holdoffMs < 0) throw new TypeError(`holdoffMs must be >= 0, got ${vad.holdoffMs}`);
+						if (typeof vad.holdoffMs !== "number" || Number.isNaN(vad.holdoffMs)) throw new TypeError("vad holdoffMs must be a number");
+						if (vad.holdoffMs < 0) throw new RangeError("vad holdoffMs must be non-negative");
 						vadHoldoff = vad.holdoffMs;
 					}
 				} else throw new TypeError(`Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'energy', or a config object { model, threshold, holdoffMs }.`);
@@ -129,7 +131,7 @@ var decibri = (function() {
 				this._echoCancellation = options.echoCancellation ?? true;
 				this._noiseSuppression = options.noiseSuppression ?? true;
 				this._workletUrl = options.workletUrl;
-				if (this._sampleRate < 1e3 || this._sampleRate > 384e3) throw new TypeError(`sample rate must be between 1000 and 384000, got ${this._sampleRate}`);
+				if (this._sampleRate < 1e3 || this._sampleRate > 384e3) throw new RangeError("sample rate must be between 1000 and 384000");
 				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'");

package/index.d.ts

@@ -59,7 +59,14 @@ export declare class DecibriOutputBridge {
    * Empty buffers resolve immediately. The synchronous `write` is unchanged.
    */
   writeAsync(buffer: Buffer): Promise<unknown>
-  /** Graceful drain: blocks until all queued samples have been played. */
+  /**
+   * Graceful drain: blocks until all queued samples have been played.
+   *
+   * Fails when the device died while the audio was still queued: the drain
+   * returns early once the stream stops running, which covers a deliberate
+   * stop and a driver failure alike, and only the failure stashes a typed
+   * cause. An empty slot therefore leaves a normal drain silent.
+   */
   drain(): void
   /**
    * Non-blocking drain: the poll loop that waits for the cpal callback to play
@@ -72,6 +79,14 @@ export declare class DecibriOutputBridge {
   stop(): void
   /** Whether audio is currently being output. */
   get isPlaying(): boolean
+  /**
+   * Number of samples emitted as silence fill because the playback queue
+   * ran dry (the core stream's underrun counter). Returns 0 while the
+   * producer keeps the queue fed or when no stream is active. Returned as
+   * f64 (an exact JS number for any realistic count) to match the
+   * microphone bridge's `overrunCount` getter.
+   */
+  get underrunCount(): number
   /** List all available audio output devices. */
   static devices(): Array<OutputDeviceInfoJs>
   /** Version information. */
@@ -126,6 +141,11 @@ export declare class FileHandle {
   get vadProbability(): number
   /** The target output rate every delivered chunk carries. */
   get sampleRate(): number
+  /**
+   * The source's native rate, from the WAV header or the explicit
+   * `inputRate` of `buffer`.
+   */
+  get inputRate(): number
 }
 
 /**

package/index.js

@@ -77,8 +77,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-android-arm64')
         const bindingPackageVersion = require('@decibri/decibri-android-arm64/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -93,8 +93,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-android-arm-eabi')
         const bindingPackageVersion = require('@decibri/decibri-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -114,8 +114,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-win32-x64-gnu')
         const bindingPackageVersion = require('@decibri/decibri-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -130,8 +130,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-win32-x64-msvc')
         const bindingPackageVersion = require('@decibri/decibri-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -147,8 +147,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-win32-ia32-msvc')
         const bindingPackageVersion = require('@decibri/decibri-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -163,8 +163,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-win32-arm64-msvc')
         const bindingPackageVersion = require('@decibri/decibri-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -182,8 +182,8 @@ function requireNative() {
     try {
       const binding = require('@decibri/decibri-darwin-universal')
       const bindingPackageVersion = require('@decibri/decibri-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -198,8 +198,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-darwin-x64')
         const bindingPackageVersion = require('@decibri/decibri-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -214,8 +214,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-darwin-arm64')
         const bindingPackageVersion = require('@decibri/decibri-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-freebsd-x64')
         const bindingPackageVersion = require('@decibri/decibri-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -250,8 +250,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-freebsd-arm64')
         const bindingPackageVersion = require('@decibri/decibri-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -271,8 +271,8 @@ function requireNative() {
         try {
           const binding = require('@decibri/decibri-linux-x64-musl')
           const bindingPackageVersion = require('@decibri/decibri-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -287,8 +287,8 @@ function requireNative() {
         try {
           const binding = require('@decibri/decibri-linux-x64-gnu')
           const bindingPackageVersion = require('@decibri/decibri-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -305,8 +305,8 @@ function requireNative() {
         try {
           const binding = require('@decibri/decibri-linux-arm64-musl')
           const bindingPackageVersion = require('@decibri/decibri-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -321,8 +321,8 @@ function requireNative() {
         try {
           const binding = require('@decibri/decibri-linux-arm64-gnu')
           const bindingPackageVersion = require('@decibri/decibri-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -339,8 +339,8 @@ function requireNative() {
         try {
           const binding = require('@decibri/decibri-linux-arm-musleabihf')
           const bindingPackageVersion = require('@decibri/decibri-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -355,8 +355,8 @@ function requireNative() {
         try {
           const binding = require('@decibri/decibri-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@decibri/decibri-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -373,8 +373,8 @@ function requireNative() {
         try {
           const binding = require('@decibri/decibri-linux-loong64-musl')
           const bindingPackageVersion = require('@decibri/decibri-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -389,8 +389,8 @@ function requireNative() {
         try {
           const binding = require('@decibri/decibri-linux-loong64-gnu')
           const bindingPackageVersion = require('@decibri/decibri-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -407,8 +407,8 @@ function requireNative() {
         try {
           const binding = require('@decibri/decibri-linux-riscv64-musl')
           const bindingPackageVersion = require('@decibri/decibri-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -423,8 +423,8 @@ function requireNative() {
         try {
           const binding = require('@decibri/decibri-linux-riscv64-gnu')
           const bindingPackageVersion = require('@decibri/decibri-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -440,8 +440,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-linux-ppc64-gnu')
         const bindingPackageVersion = require('@decibri/decibri-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -456,8 +456,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-linux-s390x-gnu')
         const bindingPackageVersion = require('@decibri/decibri-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-openharmony-arm64')
         const bindingPackageVersion = require('@decibri/decibri-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-openharmony-x64')
         const bindingPackageVersion = require('@decibri/decibri-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -508,8 +508,8 @@ function requireNative() {
       try {
         const binding = require('@decibri/decibri-openharmony-arm')
         const bindingPackageVersion = require('@decibri/decibri-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '5.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 5.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decibri",
-  "version": "5.2.2",
+  "version": "5.2.3",
   "description": "Cross-platform audio capture, playback, and processing for Node.js and browsers",
   "main": "src/decibri.js",
   "types": "src/decibri.d.ts",
@@ -72,10 +72,10 @@
     "MIGRATION.md"
   ],
   "optionalDependencies": {
-    "@decibri/decibri-win32-x64-msvc": "5.2.2",
-    "@decibri/decibri-darwin-arm64": "5.2.2",
-    "@decibri/decibri-linux-x64-gnu": "5.2.2",
-    "@decibri/decibri-linux-arm64-gnu": "5.2.2"
+    "@decibri/decibri-win32-x64-msvc": "5.2.3",
+    "@decibri/decibri-darwin-arm64": "5.2.3",
+    "@decibri/decibri-linux-x64-gnu": "5.2.3",
+    "@decibri/decibri-linux-arm64-gnu": "5.2.3"
   },
   "devDependencies": {
     "@napi-rs/cli": "^3.7.0"

package/src/browser/decibri-browser.js

@@ -6,7 +6,7 @@ const { WORKLET_SOURCE } = require('./worklet-inline.js');
 // Browser build version. Keep in sync with package.json on each release; the
 // browser bundle cannot read package.json at runtime the way the Node wrapper
 // does, so this is a maintained constant.
-const VERSION = '5.2.2';
+const VERSION = '5.2.3';
 
 /**
  * Browser microphone capture.
@@ -62,15 +62,23 @@ class Microphone extends Emitter {
         throw new TypeError(`Invalid vad model: ${JSON.stringify(vad.model)}. Expected 'energy'.`);
       }
       this._vad = true;
+      // The guards, the error classes and the messages are the node entry's,
+      // so the same option value is rejected the same way in both runtimes.
       if (vad.threshold !== undefined) {
+        if (typeof vad.threshold !== 'number' || Number.isNaN(vad.threshold)) {
+          throw new TypeError('vad threshold must be a number');
+        }
         if (vad.threshold < 0 || vad.threshold > 1) {
-          throw new TypeError(`threshold must be between 0 and 1, got ${vad.threshold}`);
+          throw new RangeError('vad threshold must be between 0 and 1');
         }
         vadThreshold = vad.threshold;
       }
       if (vad.holdoffMs !== undefined) {
+        if (typeof vad.holdoffMs !== 'number' || Number.isNaN(vad.holdoffMs)) {
+          throw new TypeError('vad holdoffMs must be a number');
+        }
         if (vad.holdoffMs < 0) {
-          throw new TypeError(`holdoffMs must be >= 0, got ${vad.holdoffMs}`);
+          throw new RangeError('vad holdoffMs must be non-negative');
         }
         vadHoldoff = vad.holdoffMs;
       }
@@ -95,7 +103,7 @@ class Microphone extends Emitter {
 
     // ── Validate ──────────────────────────────────────────────────────────
     if (this._sampleRate < 1000 || this._sampleRate > 384000) {
-      throw new TypeError(`sample rate must be between 1000 and 384000, got ${this._sampleRate}`);
+      throw new RangeError('sample rate must be between 1000 and 384000');
     }
     if (this._channels < 1 || this._channels > 32) {
       throw new TypeError(`channels must be between 1 and 32, got ${this._channels}`);

package/src/browser/decibri-output-browser.js

@@ -100,7 +100,7 @@ class Speaker {
     this._dtype = options.dtype ?? 'int16';
     this._workletUrl = options.workletUrl;
 
-    // ── Validate (mirrors the browser Microphone error style: TypeError) ────
+    // ── Validate ──────────────────────────────────────────────────────────
     if (this._sampleRate < 1000 || this._sampleRate > 384000) {
       throw new TypeError(`sample rate must be between 1000 and 384000, got ${this._sampleRate}`);
     }

package/src/decibri-output.js

@@ -10,6 +10,14 @@ const PACKAGE_VERSION = require('../package.json').version;
 
 // ─── Speaker (Writable) ─────────────────────────────────────────────────────
 
+/**
+ * A playback device that fails mid-stream (USB unplug, driver reset) surfaces
+ * on the next write or drain, as a `DecibriError` with `code === 'DEVICE_FAILED'`
+ * on the `'error'` event (or as a rejection from `writeAsync()` / `drainAsync()`).
+ * A producer that has stopped writing is not told; `isPlaying` goes false
+ * immediately either way. A deliberate `stop()` is never reported as a device
+ * failure.
+ */
 class Speaker extends Writable {
   /**
    * @param {import('./decibri').SpeakerOptions} [options]
@@ -78,7 +86,9 @@ class Speaker extends Writable {
     // for a clean Node-side RangeError without a round-trip.
     let resolvedDevice = options.device;
     if (typeof options.device === 'number') {
-      const devices = DecibriOutputBridge.devices();
+      // Through the static so an enumeration failure raised while resolving an
+      // index carries the same DeviceError the public listing does.
+      const devices = Speaker.devices();
       if (options.device < 0 || options.device >= devices.length) {
         throw new RangeError('device index out of range. Call Speaker.devices() to list available devices');
       }
@@ -143,24 +153,31 @@ class Speaker extends Writable {
       this._native.write(chunk);
       callback();
     } catch (err) {
-      callback(err);
+      callback(wrapNativeError(err));
     }
   }
 
   /** @internal Called by end() after all buffered writes complete. */
   _final(callback) {
+    // end() is terminal: flush all queued audio, then stop. drain() blocks
+    // until everything queued has played (it is a non-terminal flush in the
+    // core), and stop() then ends the stream so isPlaying is false once the
+    // audio has finished. The flush-then-stop order plays the tail to
+    // completion before stopping; reversing it would truncate the audio.
+    // A drain that reports a device failure still has to stop, so the device is
+    // released on the failing path exactly as it is on the clean one.
+    let failure;
     try {
-      // end() is terminal: flush all queued audio, then stop. drain() blocks
-      // until everything queued has played (it is a non-terminal flush in the
-      // core), and stop() then ends the stream so isPlaying is false once the
-      // audio has finished. The flush-then-stop order plays the tail to
-      // completion before stopping; reversing it would truncate the audio.
       this._native.drain();
+    } catch (err) {
+      failure = wrapNativeError(err);
+    }
+    try {
       this._native.stop();
-      callback();
     } catch (err) {
-      callback(err);
+      failure = failure || wrapNativeError(err);
     }
+    callback(failure);
   }
 
   /**
@@ -228,12 +245,26 @@ class Speaker extends Writable {
     return this._native.isPlaying;
   }
 
+  /**
+   * Number of samples emitted as silence fill because the playback queue ran
+   * dry. 0 while the producer keeps the queue fed, or before playback starts.
+   * A rising value means the output is papering over gaps with silence.
+   * @returns {number}
+   */
+  get underrunCount() {
+    return this._native.underrunCount;
+  }
+
   /**
    * List all available output devices on the system.
    * @returns {Array<{index: number, name: string, maxOutputChannels: number, defaultSampleRate: number, isDefault: boolean}>}
    */
   static devices() {
-    return DecibriOutputBridge.devices();
+    try {
+      return DecibriOutputBridge.devices();
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
   }
 
   /**

package/src/decibri.d.ts

@@ -472,6 +472,19 @@ export declare class File extends Readable {
    */
   readonly vadScore: number;
 
+  /**
+   * The rate every delivered chunk carries: the `sampleRate` option, or
+   * 16000 when it was not given.
+   */
+  readonly sampleRate: number;
+
+  /**
+   * The source's own rate, taken from the WAV header or from the
+   * `inputRate` passed to `File.buffer`. Differs from `sampleRate` when the
+   * source was resampled.
+   */
+  readonly inputRate: number;
+
   /**
    * Analyze the whole recording for speech, off the event loop. Resolves to
    * a `VadReport` with per-window `scores` and merged speech `segments`,
@@ -623,6 +636,13 @@ export declare class Speaker extends Writable {
   /** Whether audio is currently being output. */
   readonly isPlaying: boolean;
 
+  /**
+   * Number of samples emitted as silence fill because the playback queue ran
+   * dry. 0 while the producer keeps the queue fed, or before playback starts.
+   * A rising value means the output is papering over gaps with silence.
+   */
+  readonly underrunCount: number;
+
   /** List all available audio output devices. */
   static devices(): SpeakerInfo[];
 

package/src/decibri.js

@@ -75,6 +75,12 @@ function resolveBundledOrtPath() {
 
 // ─── Microphone (Readable) ──────────────────────────────────────────────────
 
+/**
+ * Failures that reach the consumer arrive on the `'error'` event as a
+ * `DecibriError` carrying a `code`: a failed open or a denied permission when
+ * capture starts, and a device lost mid-capture (`code === 'DEVICE_FAILED'`).
+ * A deliberate `stop()` ends the stream cleanly and raises nothing.
+ */
 class Microphone extends Readable {
   /**
    * @param {import('./decibri').MicrophoneOptions} [options]
@@ -170,7 +176,9 @@ class Microphone extends Readable {
     // for a clean Node-side RangeError without a round-trip.
     let resolvedDevice = options.device;
     if (typeof options.device === 'number') {
-      const devices = DecibriBridge.devices();
+      // Through the static so an enumeration failure raised while resolving an
+      // index carries the same DeviceError the public listing does.
+      const devices = Microphone.devices();
       if (options.device < 0 || options.device >= devices.length) {
         throw new RangeError('device index out of range. Call Microphone.devices() to list available devices');
       }
@@ -256,11 +264,15 @@ class Microphone extends Readable {
       );
     }
 
+    // The existence pre-check runs before the native bridge is constructed, so
+    // it never passes through wrapNativeError. It raises the same class and
+    // code the deep load failure would, so the detection point differs between
+    // a missing file and an unloadable one but the identity does not.
     let modelPath = undefined;
     if (vadEnabled && vadMode === 'silero') {
       modelPath = options.modelPath || path.join(__dirname, '..', 'models', 'silero_vad.onnx');
       if (!fs.existsSync(modelPath)) {
-        throw new Error(`Silero VAD model not found at ${modelPath}. Ensure the models/ directory is included in your installation.`);
+        throw new OrtError(`Silero VAD model not found at ${modelPath}. Ensure the models/ directory is included in your installation.`, 'VAD_MODEL_LOAD_FAILED');
       }
     }
 
@@ -289,7 +301,7 @@ class Microphone extends Readable {
       }
       denoiseModelPath = path.join(__dirname, '..', 'models', 'fastenhancer_t.onnx');
       if (!fs.existsSync(denoiseModelPath)) {
-        throw new Error(`Denoise model not found at ${denoiseModelPath}. Ensure the models/ directory is included in your installation.`);
+        throw new OrtError(`Denoise model not found at ${denoiseModelPath}. Ensure the models/ directory is included in your installation.`, 'MODEL_LOAD_FAILED');
       }
     }
 
@@ -408,39 +420,45 @@ class Microphone extends Readable {
     if (this._started || this._stopped) return;
     this._started = true;
 
-    this._native.start((err, chunk) => {
-      if (err) {
-        this._started = false;
-        // A start()-time failure is delivered here as the raw native error (not
-        // via wrapNativeError), so no decibri `code` is attached on the 'error'
-        // event, as with device-open failures; the dedicated MODEL_LOAD_FAILED
-        // code is reachable through wrapNativeError, not on this streaming path.
-        this.destroy(err);
-        return;
-      }
+    // Both exits from start() reach the consumer on the 'error' event, so both
+    // carry a decibri class and `code`: the synchronous throw below (a failed
+    // device open, a denied permission) and the streaming failure delivered to
+    // the callback (a device lost mid-capture).
+    try {
+      this._native.start((err, chunk) => {
+        if (err) {
+          this._started = false;
+          this.destroy(wrapNativeError(err));
+          return;
+        }
 
-      // On close the native pump flushes the buffered tail; that final data
-      // callback can run after stop() has begun ending the stream. Once the
-      // end-of-stream push(null) has been issued (or the stream was destroyed),
-      // drop any straggler rather than pushing past EOF.
-      if (this._ended || this.destroyed) {
-        return;
-      }
+        // On close the native pump flushes the buffered tail; that final data
+        // callback can run after stop() has begun ending the stream. Once the
+        // end-of-stream push(null) has been issued (or the stream was
+        // destroyed), drop any straggler rather than pushing past EOF.
+        if (this._ended || this.destroyed) {
+          return;
+        }
 
-      // push returns false when the consumer is slow. We can't pause a mic,
-      // but we surface the backpressure warning so callers can react.
-      if (!this.push(chunk)) {
-        this.emit('backpressure');
-      }
+        // push returns false when the consumer is slow. We can't pause a mic,
+        // but we surface the backpressure warning so callers can react.
+        if (!this.push(chunk)) {
+          this.emit('backpressure');
+        }
 
-      if (this._vad) {
-        // Both modes read the score from native: the Silero speech probability
-        // or, in energy mode, the RMS of the pre-enhancement signal. The native
-        // pump computes both on the signal before the opt-in enhancement step,
-        // so enabling enhancement does not change detection in either mode.
-        this._processVadValue(this._native.vadProbability);
-      }
-    });
+        if (this._vad) {
+          // Both modes read the score from native: the Silero speech
+          // probability or, in energy mode, the RMS of the pre-enhancement
+          // signal. The native pump computes both on the signal before the
+          // opt-in enhancement step, so enabling enhancement does not change
+          // detection in either mode.
+          this._processVadValue(this._native.vadProbability);
+        }
+      });
+    } catch (err) {
+      this._started = false;
+      this.destroy(wrapNativeError(err));
+    }
   }
 
   /** @internal Common speech/silence state machine */
@@ -522,7 +540,11 @@ class Microphone extends Readable {
    * @returns {Array<{index: number, name: string, id: string, maxInputChannels: number, defaultSampleRate: number, isDefault: boolean}>}
    */
   static devices() {
-    return DecibriBridge.devices();
+    try {
+      return DecibriBridge.devices();
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
   }
 
   /**
@@ -705,11 +727,13 @@ class File extends Readable {
       );
     }
 
+    // Same pre-check and same identity as Microphone: a missing model file
+    // reports the class and code its load failure would.
     let modelPath = undefined;
     if (vadEnabled && vadMode === 'silero') {
       modelPath = options.modelPath || path.join(__dirname, '..', 'models', 'silero_vad.onnx');
       if (!fs.existsSync(modelPath)) {
-        throw new Error(`Silero VAD model not found at ${modelPath}. Ensure the models/ directory is included in your installation.`);
+        throw new OrtError(`Silero VAD model not found at ${modelPath}. Ensure the models/ directory is included in your installation.`, 'VAD_MODEL_LOAD_FAILED');
       }
     }
 
@@ -727,7 +751,7 @@ class File extends Readable {
       }
       denoiseModelPath = path.join(__dirname, '..', 'models', 'fastenhancer_t.onnx');
       if (!fs.existsSync(denoiseModelPath)) {
-        throw new Error(`Denoise model not found at ${denoiseModelPath}. Ensure the models/ directory is included in your installation.`);
+        throw new OrtError(`Denoise model not found at ${denoiseModelPath}. Ensure the models/ directory is included in your installation.`, 'MODEL_LOAD_FAILED');
       }
     }
 
@@ -970,6 +994,27 @@ class File extends Readable {
     return this._vadScore;
   }
 
+  /**
+   * The rate every delivered chunk carries: the `sampleRate` option, or 16000
+   * when it was not given. Readable for the life of the File, including after
+   * the source is consumed or closed.
+   * @returns {number}
+   */
+  get sampleRate() {
+    return this._native.sampleRate;
+  }
+
+  /**
+   * The source's own rate, taken from the WAV header or from the `inputRate`
+   * passed to `File.buffer`. Differs from `sampleRate` when the source was
+   * resampled. Readable for the life of the File, including after the source
+   * is consumed or closed.
+   * @returns {number}
+   */
+  get inputRate() {
+    return this._native.inputRate;
+  }
+
   /**
    * Analyze the whole recording for speech. Runs the recording once through
    * the conditioning pass off the event loop and resolves to a `VadReport`:

package/src/errors.js

@@ -58,6 +58,38 @@ class OrtPathError extends OrtError {
 // variant's Display string (see bindings/node/src/lib.rs to_napi_error), so the
 // message text is the only thing left to classify on. The prefixes below match
 // the frozen core messages in crates/decibri/src/error.rs.
+//
+// The codes are the core's own: DecibriError::code() assigns one per variant
+// from an exhaustive match, and the catalog check in tests/test-ci.js walks
+// every variant compiled into the addon and asserts the table below reaches
+// the same identity. A reworded core message, a new variant, or a prefix that
+// collides with an existing one all fail that check.
+//
+// Prefix matching stays because some messages never cross the FFI boundary:
+// the napi-authored `File already consumed`, and the model pre-checks in
+// decibri.js, which are classified here without a native round-trip.
+
+// Argument validation the core also names. These keep Node's built-ins rather
+// than a decibri class, so the class matches the wrapper's own pre-check for
+// the same input (decibri.js raises RangeError for a bad agc or limiter before
+// the core ever sees it).
+const RANGE_PREFIXES = [
+  'sample rate must be between',
+  'channels must be between',
+  'multichannel capture is not supported',
+  'frames per buffer must be between',
+  'agc target level must be between',
+  'limiter ceiling must be between',
+  'Silero VAD only supports',
+  'VAD threshold must be between',
+  'device index out of range',
+  'analysis requires VAD',
+];
+
+const TYPE_PREFIXES = [
+  "dtype must be 'int16' or 'float32'",
+  "format must be 'int16' or 'float32'",
+];
 
 const DEVICE_CODES = [
   ['No microphone found matching', 'MICROPHONE_NOT_FOUND'],
@@ -78,6 +110,32 @@ const ORT_CODES = [
   ['Silero VAD inference failed', 'ORT_INFERENCE_FAILED'],
 ];
 
+// Failures that carry a base DecibriError plus their own code: stream
+// lifecycle, runtime device and driver faults, offline file reads, and the
+// two ONNX failures that are not ORT setup failures. Matches the Python
+// binding, where each of these is a direct DecibriError subclass rather than
+// a member of the DeviceError or OrtError family.
+const BASE_CODES = [
+  ['audio stream is already running', 'ALREADY_RUNNING'],
+  ['Failed to open audio stream', 'STREAM_OPEN_FAILED'],
+  ['Failed to start audio stream', 'STREAM_START_FAILED'],
+  ['Microphone permission denied.', 'PERMISSION_DENIED'],
+  ['Microphone stream is closed', 'MICROPHONE_STREAM_CLOSED'],
+  ['Speaker stream is closed', 'SPEAKER_STREAM_CLOSED'],
+  ['decibri: audio device error:', 'DEVICE_FAILED'],
+  ['the requested sample rate conversion is not supported', 'RESAMPLE_CONFIG_INVALID'],
+  ['Failed to read audio file', 'FILE_READ_FAILED'],
+  ['invalid WAV file:', 'WAV_INVALID'],
+  ['ONNX Runtime was initialized in pid', 'FORK_AFTER_ORT_INIT'],
+  ['ONNX backend error from', 'ONNX_BACKEND_FAILED'],
+  // Authored in the napi layer (bindings/node/src/lib.rs), not in
+  // crates/decibri/src/error.rs: reusing a File after its single pass.
+  ['File already consumed', 'FILE_CONSUMED'],
+  // The offline counterpart of a closed stream: analysing a File whose
+  // iteration has begun.
+  ['File iteration has begun', 'FILE_ENGAGED'],
+];
+
 // The core's message for analysing a File whose iteration has begun. The
 // wrapper raises it at the call site, before the native handle is touched.
 const FILE_ENGAGED_MESSAGE =
@@ -109,22 +167,11 @@ function wrapNativeError(err) {
   // Argument validation stays as Node built-ins. `device index out of range`
   // is kept here (RangeError) so the index error type is the same whether it
   // is raised by the client-side bounds check or by the core.
-  if (
-    msg.startsWith('sample rate must be between') ||
-    msg.startsWith('channels must be between') ||
-    msg.startsWith('frames per buffer must be between') ||
-    msg.startsWith('Silero VAD only supports') ||
-    msg.startsWith('VAD threshold must be between') ||
-    msg.startsWith('device index out of range') ||
-    msg.startsWith('analysis requires VAD')
-  ) {
-    return new RangeError(msg);
+  for (const prefix of RANGE_PREFIXES) {
+    if (msg.startsWith(prefix)) return new RangeError(msg);
   }
-  if (
-    msg.startsWith("dtype must be 'int16' or 'float32'") ||
-    msg.startsWith("format must be 'int16' or 'float32'")
-  ) {
-    return new TypeError(msg);
+  for (const prefix of TYPE_PREFIXES) {
+    if (msg.startsWith(prefix)) return new TypeError(msg);
   }
 
   // Device enumeration / selection failures.
@@ -148,31 +195,12 @@ function wrapNativeError(err) {
     return new OrtError(msg, 'ORT_TENSOR_EXTRACT_FAILED');
   }
 
-  // Runtime device/driver failure during streaming. Distinct from the
+  // Stream lifecycle, runtime device/driver faults, offline file reads, and the
+  // ONNX failures outside the ORT setup family. Distinct from the
   // enumeration/selection DeviceError family above (which mirrors the core's
-  // "Device errors"): this is the core's "Stream errors" DeviceFailed, surfaced
-  // as a base DecibriError with a dedicated code.
-  if (msg.startsWith('decibri: audio device error:')) {
-    return new DecibriError(msg, 'DEVICE_FAILED');
-  }
-  // Non-ORT ONNX backend failure: the reserved backend catch-all, surfaced as a
-  // base DecibriError with a dedicated code (not an OrtError).
-  if (msg.startsWith('ONNX backend error from')) {
-    return new DecibriError(msg, 'ONNX_BACKEND_FAILED');
-  }
-  // Reusing a File after its single pass (analysis or iteration consumed the
-  // source) is a lifecycle failure, the offline counterpart of a closed stream:
-  // a base DecibriError with a dedicated code, not the RangeError reserved for
-  // argument validation. Unlike the prefixes above, this message is authored in
-  // the napi layer (bindings/node/src/lib.rs), not in crates/decibri/src/error.rs.
-  if (msg.startsWith('File already consumed')) {
-    return new DecibriError(msg, 'FILE_CONSUMED');
-  }
-  // Analysing a File whose iteration has begun. The companion lifecycle
-  // failure to FILE_CONSUMED, and authored in crates/decibri/src/error.rs
-  // rather than the napi layer.
-  if (msg.startsWith('File iteration has begun')) {
-    return new DecibriError(msg, 'FILE_ENGAGED');
+  // "Device errors").
+  for (const [prefix, code] of BASE_CODES) {
+    if (msg.startsWith(prefix)) return new DecibriError(msg, code);
   }
 
   // Any other error from the native constructor is still a decibri error.