decibri 5.2.1 → 5.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/CHANGELOG.md +46 -2
  2. package/examples/decibri.browser.js +6 -4
  3. package/index.d.ts +25 -1
  4. package/index.js +52 -52
  5. package/package.json +5 -5
  6. package/src/browser/decibri-browser.js +12 -4
  7. package/src/browser/decibri-output-browser.js +1 -1
  8. package/src/decibri-output.js +41 -10
  9. package/src/decibri.d.ts +25 -0
  10. package/src/decibri.js +155 -36
  11. package/src/errors.js +84 -33
package/CHANGELOG.md CHANGED
@@ -6,8 +6,52 @@ Changes to the decibri npm package, published to npmjs.com. Tags use the `npm-v*
6
6
 
7
7
  For other decibri packages, see:
8
8
 
9
- - Rust crate: [crates/decibri/CHANGELOG.md](../../crates/decibri/CHANGELOG.md)
10
- - Python wheel: [bindings/python/CHANGELOG.md](../../bindings/python/CHANGELOG.md)
9
+ - Rust core: [crates/decibri/CHANGELOG.md](../../crates/decibri/CHANGELOG.md)
10
+ - Python package: [bindings/python/CHANGELOG.md](../../bindings/python/CHANGELOG.md)
11
+
12
+ ## [5.2.3] - 2026-07-27
13
+
14
+ ### Added
15
+
16
+ - `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.
17
+ - `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.
18
+
19
+ ### Changed
20
+
21
+ - **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`.
22
+ - **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.
23
+
24
+ - 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`.
25
+ - 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.
26
+ - `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.
27
+
28
+ - 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.
29
+ - 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.
30
+
31
+ ### Fixed
32
+
33
+ - 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.
34
+ - 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.
35
+ - `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.
36
+ - 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.
37
+ - `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.
38
+ - `File` opens WAV files whose `data` chunk precedes their format chunk; they were rejected as missing the format chunk.
39
+
40
+ ## [5.2.2] - 2026-07-25
41
+
42
+ ### Added
43
+
44
+ - The refused-analysis failure carries the dedicated `code` `'FILE_ENGAGED'` on a `DecibriError`.
45
+
46
+ ### Changed
47
+
48
+ - `File.analyze()` and `File.analyse()` reject once the stream has been engaged, instead of resolving to a report of the part not yet read timed from the start of the recording. Any route that starts the flow counts: `resume()`, a `'data'` or `'readable'` listener, `read()`, `pipe()`, and async iteration. Construct a second `File` to both stream a recording and analyze it.
49
+ - A fully streamed `File` rejects an analysis with `'FILE_ENGAGED'` where it previously rejected with `'FILE_CONSUMED'`.
50
+
51
+ ### Fixed
52
+
53
+ - A `File.analyze()` rejected before the pass begins leaves the `File` usable, so correcting the call and streaming the recording still works. A `File` analyzed without `vad` was previously consumed by the rejected call. A failure during the pass, such as the detector failing to load, still consumes the source.
54
+ - Analysing a `File` whose stream has been engaged no longer raises from the stream's own read machinery, where an `'error'` event with no listener terminates the process. The rejection now arrives from the `analyze()` call itself.
11
55
 
12
56
  ## [5.2.1] - 2026-07-24
13
57
 
package/examples/decibri.browser.js CHANGED
@@ -70,7 +70,7 @@ var decibri = (function() {
70
70
  var require_decibri_browser = /* @__PURE__ */ __commonJSMin(((exports, module) => {
71
71
  const { Emitter } = require_emitter();
72
72
  const { WORKLET_SOURCE } = require_worklet_inline();
73
- const VERSION = "5.2.1";
73
+ const VERSION = "5.2.3";
74
74
  /**
75
75
  * Browser microphone capture.
76
76
  *
@@ -108,11 +108,13 @@ var decibri = (function() {
108
108
  if (vad.model !== "energy") throw new TypeError(`Invalid vad model: ${JSON.stringify(vad.model)}. Expected 'energy'.`);
109
109
  this._vad = true;
110
110
  if (vad.threshold !== void 0) {
111
- if (vad.threshold < 0 || vad.threshold > 1) throw new TypeError(`threshold must be between 0 and 1, got ${vad.threshold}`);
111
+ if (typeof vad.threshold !== "number" || Number.isNaN(vad.threshold)) throw new TypeError("vad threshold must be a number");
112
+ if (vad.threshold < 0 || vad.threshold > 1) throw new RangeError("vad threshold must be between 0 and 1");
112
113
  vadThreshold = vad.threshold;
113
114
  }
114
115
  if (vad.holdoffMs !== void 0) {
115
- if (vad.holdoffMs < 0) throw new TypeError(`holdoffMs must be >= 0, got ${vad.holdoffMs}`);
116
+ if (typeof vad.holdoffMs !== "number" || Number.isNaN(vad.holdoffMs)) throw new TypeError("vad holdoffMs must be a number");
117
+ if (vad.holdoffMs < 0) throw new RangeError("vad holdoffMs must be non-negative");
116
118
  vadHoldoff = vad.holdoffMs;
117
119
  }
118
120
  } 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() {
129
131
  this._echoCancellation = options.echoCancellation ?? true;
130
132
  this._noiseSuppression = options.noiseSuppression ?? true;
131
133
  this._workletUrl = options.workletUrl;
132
- if (this._sampleRate < 1e3 || this._sampleRate > 384e3) throw new TypeError(`sample rate must be between 1000 and 384000, got ${this._sampleRate}`);
134
+ if (this._sampleRate < 1e3 || this._sampleRate > 384e3) throw new RangeError("sample rate must be between 1000 and 384000");
133
135
  if (this._channels < 1 || this._channels > 32) throw new TypeError(`channels must be between 1 and 32, got ${this._channels}`);
134
136
  if (this._framesPerBuffer < 64 || this._framesPerBuffer > 65536) throw new TypeError(`frames per buffer must be between 64 and 65536, got ${this._framesPerBuffer}`);
135
137
  if (this._dtype !== "int16" && this._dtype !== "float32") throw new TypeError("dtype must be 'int16' or 'float32'");
package/index.d.ts CHANGED
@@ -59,7 +59,14 @@ export declare class DecibriOutputBridge {
59
59
  * Empty buffers resolve immediately. The synchronous `write` is unchanged.
60
60
  */
61
61
  writeAsync(buffer: Buffer): Promise<unknown>
62
- /** Graceful drain: blocks until all queued samples have been played. */
62
+ /**
63
+ * Graceful drain: blocks until all queued samples have been played.
64
+ *
65
+ * Fails when the device died while the audio was still queued: the drain
66
+ * returns early once the stream stops running, which covers a deliberate
67
+ * stop and a driver failure alike, and only the failure stashes a typed
68
+ * cause. An empty slot therefore leaves a normal drain silent.
69
+ */
63
70
  drain(): void
64
71
  /**
65
72
  * Non-blocking drain: the poll loop that waits for the cpal callback to play
@@ -72,6 +79,14 @@ export declare class DecibriOutputBridge {
72
79
  stop(): void
73
80
  /** Whether audio is currently being output. */
74
81
  get isPlaying(): boolean
82
+ /**
83
+ * Number of samples emitted as silence fill because the playback queue
84
+ * ran dry (the core stream's underrun counter). Returns 0 while the
85
+ * producer keeps the queue fed or when no stream is active. Returned as
86
+ * f64 (an exact JS number for any realistic count) to match the
87
+ * microphone bridge's `overrunCount` getter.
88
+ */
89
+ get underrunCount(): number
75
90
  /** List all available audio output devices. */
76
91
  static devices(): Array<OutputDeviceInfoJs>
77
92
  /** Version information. */
@@ -111,6 +126,10 @@ export declare class FileHandle {
111
126
  * JS event loop. Resolves to the `VadReport`; a `File` built without VAD
112
127
  * rejects with the core's typed error, never a silently constructed
113
128
  * detector.
129
+ *
130
+ * Everything checkable is checked before the source is taken, so a
131
+ * rejected call leaves the File exactly as it was and the caller can fix
132
+ * the configuration and retry.
114
133
  */
115
134
  analyze(): Promise<unknown>
116
135
  /** Release the source. Idempotent; a closed File reads as ended. */
@@ -122,6 +141,11 @@ export declare class FileHandle {
122
141
  get vadProbability(): number
123
142
  /** The target output rate every delivered chunk carries. */
124
143
  get sampleRate(): number
144
+ /**
145
+ * The source's native rate, from the WAV header or the explicit
146
+ * `inputRate` of `buffer`.
147
+ */
148
+ get inputRate(): number
125
149
  }
126
150
 
127
151
  /**
package/index.js CHANGED
@@ -77,8 +77,8 @@ function requireNative() {
77
77
  try {
78
78
  const binding = require('@decibri/decibri-android-arm64')
79
79
  const bindingPackageVersion = require('@decibri/decibri-android-arm64/package.json').version
80
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
81
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
80
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
81
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
82
82
  }
83
83
  return binding
84
84
  } catch (e) {
@@ -93,8 +93,8 @@ function requireNative() {
93
93
  try {
94
94
  const binding = require('@decibri/decibri-android-arm-eabi')
95
95
  const bindingPackageVersion = require('@decibri/decibri-android-arm-eabi/package.json').version
96
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
97
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
96
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
97
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
98
98
  }
99
99
  return binding
100
100
  } catch (e) {
@@ -114,8 +114,8 @@ function requireNative() {
114
114
  try {
115
115
  const binding = require('@decibri/decibri-win32-x64-gnu')
116
116
  const bindingPackageVersion = require('@decibri/decibri-win32-x64-gnu/package.json').version
117
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
118
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
117
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
118
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
119
119
  }
120
120
  return binding
121
121
  } catch (e) {
@@ -130,8 +130,8 @@ function requireNative() {
130
130
  try {
131
131
  const binding = require('@decibri/decibri-win32-x64-msvc')
132
132
  const bindingPackageVersion = require('@decibri/decibri-win32-x64-msvc/package.json').version
133
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
134
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
133
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
134
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
135
135
  }
136
136
  return binding
137
137
  } catch (e) {
@@ -147,8 +147,8 @@ function requireNative() {
147
147
  try {
148
148
  const binding = require('@decibri/decibri-win32-ia32-msvc')
149
149
  const bindingPackageVersion = require('@decibri/decibri-win32-ia32-msvc/package.json').version
150
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
151
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
150
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
151
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
152
152
  }
153
153
  return binding
154
154
  } catch (e) {
@@ -163,8 +163,8 @@ function requireNative() {
163
163
  try {
164
164
  const binding = require('@decibri/decibri-win32-arm64-msvc')
165
165
  const bindingPackageVersion = require('@decibri/decibri-win32-arm64-msvc/package.json').version
166
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
167
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
166
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
167
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
168
168
  }
169
169
  return binding
170
170
  } catch (e) {
@@ -182,8 +182,8 @@ function requireNative() {
182
182
  try {
183
183
  const binding = require('@decibri/decibri-darwin-universal')
184
184
  const bindingPackageVersion = require('@decibri/decibri-darwin-universal/package.json').version
185
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
186
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
185
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
186
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
187
187
  }
188
188
  return binding
189
189
  } catch (e) {
@@ -198,8 +198,8 @@ function requireNative() {
198
198
  try {
199
199
  const binding = require('@decibri/decibri-darwin-x64')
200
200
  const bindingPackageVersion = require('@decibri/decibri-darwin-x64/package.json').version
201
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
202
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
201
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
202
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
203
203
  }
204
204
  return binding
205
205
  } catch (e) {
@@ -214,8 +214,8 @@ function requireNative() {
214
214
  try {
215
215
  const binding = require('@decibri/decibri-darwin-arm64')
216
216
  const bindingPackageVersion = require('@decibri/decibri-darwin-arm64/package.json').version
217
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
218
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
217
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
218
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
219
219
  }
220
220
  return binding
221
221
  } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
234
234
  try {
235
235
  const binding = require('@decibri/decibri-freebsd-x64')
236
236
  const bindingPackageVersion = require('@decibri/decibri-freebsd-x64/package.json').version
237
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
238
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
237
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
238
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
239
239
  }
240
240
  return binding
241
241
  } catch (e) {
@@ -250,8 +250,8 @@ function requireNative() {
250
250
  try {
251
251
  const binding = require('@decibri/decibri-freebsd-arm64')
252
252
  const bindingPackageVersion = require('@decibri/decibri-freebsd-arm64/package.json').version
253
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
254
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
253
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
254
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
255
255
  }
256
256
  return binding
257
257
  } catch (e) {
@@ -271,8 +271,8 @@ function requireNative() {
271
271
  try {
272
272
  const binding = require('@decibri/decibri-linux-x64-musl')
273
273
  const bindingPackageVersion = require('@decibri/decibri-linux-x64-musl/package.json').version
274
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
275
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
274
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
275
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
276
276
  }
277
277
  return binding
278
278
  } catch (e) {
@@ -287,8 +287,8 @@ function requireNative() {
287
287
  try {
288
288
  const binding = require('@decibri/decibri-linux-x64-gnu')
289
289
  const bindingPackageVersion = require('@decibri/decibri-linux-x64-gnu/package.json').version
290
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
291
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
290
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
291
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
292
292
  }
293
293
  return binding
294
294
  } catch (e) {
@@ -305,8 +305,8 @@ function requireNative() {
305
305
  try {
306
306
  const binding = require('@decibri/decibri-linux-arm64-musl')
307
307
  const bindingPackageVersion = require('@decibri/decibri-linux-arm64-musl/package.json').version
308
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
309
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
308
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
309
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
310
310
  }
311
311
  return binding
312
312
  } catch (e) {
@@ -321,8 +321,8 @@ function requireNative() {
321
321
  try {
322
322
  const binding = require('@decibri/decibri-linux-arm64-gnu')
323
323
  const bindingPackageVersion = require('@decibri/decibri-linux-arm64-gnu/package.json').version
324
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
325
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
324
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
325
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
326
326
  }
327
327
  return binding
328
328
  } catch (e) {
@@ -339,8 +339,8 @@ function requireNative() {
339
339
  try {
340
340
  const binding = require('@decibri/decibri-linux-arm-musleabihf')
341
341
  const bindingPackageVersion = require('@decibri/decibri-linux-arm-musleabihf/package.json').version
342
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
343
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
342
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
343
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
344
344
  }
345
345
  return binding
346
346
  } catch (e) {
@@ -355,8 +355,8 @@ function requireNative() {
355
355
  try {
356
356
  const binding = require('@decibri/decibri-linux-arm-gnueabihf')
357
357
  const bindingPackageVersion = require('@decibri/decibri-linux-arm-gnueabihf/package.json').version
358
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
359
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
358
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
359
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
360
360
  }
361
361
  return binding
362
362
  } catch (e) {
@@ -373,8 +373,8 @@ function requireNative() {
373
373
  try {
374
374
  const binding = require('@decibri/decibri-linux-loong64-musl')
375
375
  const bindingPackageVersion = require('@decibri/decibri-linux-loong64-musl/package.json').version
376
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
377
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
376
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
377
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
378
378
  }
379
379
  return binding
380
380
  } catch (e) {
@@ -389,8 +389,8 @@ function requireNative() {
389
389
  try {
390
390
  const binding = require('@decibri/decibri-linux-loong64-gnu')
391
391
  const bindingPackageVersion = require('@decibri/decibri-linux-loong64-gnu/package.json').version
392
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
393
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
392
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
393
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
394
394
  }
395
395
  return binding
396
396
  } catch (e) {
@@ -407,8 +407,8 @@ function requireNative() {
407
407
  try {
408
408
  const binding = require('@decibri/decibri-linux-riscv64-musl')
409
409
  const bindingPackageVersion = require('@decibri/decibri-linux-riscv64-musl/package.json').version
410
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
411
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
410
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
411
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
412
412
  }
413
413
  return binding
414
414
  } catch (e) {
@@ -423,8 +423,8 @@ function requireNative() {
423
423
  try {
424
424
  const binding = require('@decibri/decibri-linux-riscv64-gnu')
425
425
  const bindingPackageVersion = require('@decibri/decibri-linux-riscv64-gnu/package.json').version
426
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
427
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
426
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
427
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
428
428
  }
429
429
  return binding
430
430
  } catch (e) {
@@ -440,8 +440,8 @@ function requireNative() {
440
440
  try {
441
441
  const binding = require('@decibri/decibri-linux-ppc64-gnu')
442
442
  const bindingPackageVersion = require('@decibri/decibri-linux-ppc64-gnu/package.json').version
443
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
444
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
443
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
444
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
445
445
  }
446
446
  return binding
447
447
  } catch (e) {
@@ -456,8 +456,8 @@ function requireNative() {
456
456
  try {
457
457
  const binding = require('@decibri/decibri-linux-s390x-gnu')
458
458
  const bindingPackageVersion = require('@decibri/decibri-linux-s390x-gnu/package.json').version
459
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
460
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
459
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
460
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
461
461
  }
462
462
  return binding
463
463
  } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
476
476
  try {
477
477
  const binding = require('@decibri/decibri-openharmony-arm64')
478
478
  const bindingPackageVersion = require('@decibri/decibri-openharmony-arm64/package.json').version
479
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
480
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
479
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
480
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
481
481
  }
482
482
  return binding
483
483
  } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
492
492
  try {
493
493
  const binding = require('@decibri/decibri-openharmony-x64')
494
494
  const bindingPackageVersion = require('@decibri/decibri-openharmony-x64/package.json').version
495
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
496
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
495
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
496
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
497
497
  }
498
498
  return binding
499
499
  } catch (e) {
@@ -508,8 +508,8 @@ function requireNative() {
508
508
  try {
509
509
  const binding = require('@decibri/decibri-openharmony-arm')
510
510
  const bindingPackageVersion = require('@decibri/decibri-openharmony-arm/package.json').version
511
- if (bindingPackageVersion !== '5.2.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
512
- throw new Error(`Native binding package version mismatch, expected 5.2.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
511
+ if (bindingPackageVersion !== '5.2.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
512
+ throw new Error(`Native binding package version mismatch, expected 5.2.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
513
513
  }
514
514
  return binding
515
515
  } catch (e) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "decibri",
3
- "version": "5.2.1",
3
+ "version": "5.2.3",
4
4
  "description": "Cross-platform audio capture, playback, and processing for Node.js and browsers",
5
5
  "main": "src/decibri.js",
6
6
  "types": "src/decibri.d.ts",
@@ -72,10 +72,10 @@
72
72
  "MIGRATION.md"
73
73
  ],
74
74
  "optionalDependencies": {
75
- "@decibri/decibri-win32-x64-msvc": "5.2.1",
76
- "@decibri/decibri-darwin-arm64": "5.2.1",
77
- "@decibri/decibri-linux-x64-gnu": "5.2.1",
78
- "@decibri/decibri-linux-arm64-gnu": "5.2.1"
75
+ "@decibri/decibri-win32-x64-msvc": "5.2.3",
76
+ "@decibri/decibri-darwin-arm64": "5.2.3",
77
+ "@decibri/decibri-linux-x64-gnu": "5.2.3",
78
+ "@decibri/decibri-linux-arm64-gnu": "5.2.3"
79
79
  },
80
80
  "devDependencies": {
81
81
  "@napi-rs/cli": "^3.7.0"
package/src/browser/decibri-browser.js CHANGED
@@ -6,7 +6,7 @@ const { WORKLET_SOURCE } = require('./worklet-inline.js');
6
6
  // Browser build version. Keep in sync with package.json on each release; the
7
7
  // browser bundle cannot read package.json at runtime the way the Node wrapper
8
8
  // does, so this is a maintained constant.
9
- const VERSION = '5.2.1';
9
+ const VERSION = '5.2.3';
10
10
 
11
11
  /**
12
12
  * Browser microphone capture.
@@ -62,15 +62,23 @@ class Microphone extends Emitter {
62
62
  throw new TypeError(`Invalid vad model: ${JSON.stringify(vad.model)}. Expected 'energy'.`);
63
63
  }
64
64
  this._vad = true;
65
+ // The guards, the error classes and the messages are the node entry's,
66
+ // so the same option value is rejected the same way in both runtimes.
65
67
  if (vad.threshold !== undefined) {
68
+ if (typeof vad.threshold !== 'number' || Number.isNaN(vad.threshold)) {
69
+ throw new TypeError('vad threshold must be a number');
70
+ }
66
71
  if (vad.threshold < 0 || vad.threshold > 1) {
67
- throw new TypeError(`threshold must be between 0 and 1, got ${vad.threshold}`);
72
+ throw new RangeError('vad threshold must be between 0 and 1');
68
73
  }
69
74
  vadThreshold = vad.threshold;
70
75
  }
71
76
  if (vad.holdoffMs !== undefined) {
77
+ if (typeof vad.holdoffMs !== 'number' || Number.isNaN(vad.holdoffMs)) {
78
+ throw new TypeError('vad holdoffMs must be a number');
79
+ }
72
80
  if (vad.holdoffMs < 0) {
73
- throw new TypeError(`holdoffMs must be >= 0, got ${vad.holdoffMs}`);
81
+ throw new RangeError('vad holdoffMs must be non-negative');
74
82
  }
75
83
  vadHoldoff = vad.holdoffMs;
76
84
  }
@@ -95,7 +103,7 @@ class Microphone extends Emitter {
95
103
 
96
104
  // ── Validate ──────────────────────────────────────────────────────────
97
105
  if (this._sampleRate < 1000 || this._sampleRate > 384000) {
98
- throw new TypeError(`sample rate must be between 1000 and 384000, got ${this._sampleRate}`);
106
+ throw new RangeError('sample rate must be between 1000 and 384000');
99
107
  }
100
108
  if (this._channels < 1 || this._channels > 32) {
101
109
  throw new TypeError(`channels must be between 1 and 32, got ${this._channels}`);
package/src/browser/decibri-output-browser.js CHANGED
@@ -100,7 +100,7 @@ class Speaker {
100
100
  this._dtype = options.dtype ?? 'int16';
101
101
  this._workletUrl = options.workletUrl;
102
102
 
103
- // ── Validate (mirrors the browser Microphone error style: TypeError) ────
103
+ // ── Validate ──────────────────────────────────────────────────────────
104
104
  if (this._sampleRate < 1000 || this._sampleRate > 384000) {
105
105
  throw new TypeError(`sample rate must be between 1000 and 384000, got ${this._sampleRate}`);
106
106
  }
package/src/decibri-output.js CHANGED
@@ -10,6 +10,14 @@ const PACKAGE_VERSION = require('../package.json').version;
10
10
 
11
11
  // ─── Speaker (Writable) ─────────────────────────────────────────────────────
12
12
 
13
+ /**
14
+ * A playback device that fails mid-stream (USB unplug, driver reset) surfaces
15
+ * on the next write or drain, as a `DecibriError` with `code === 'DEVICE_FAILED'`
16
+ * on the `'error'` event (or as a rejection from `writeAsync()` / `drainAsync()`).
17
+ * A producer that has stopped writing is not told; `isPlaying` goes false
18
+ * immediately either way. A deliberate `stop()` is never reported as a device
19
+ * failure.
20
+ */
13
21
  class Speaker extends Writable {
14
22
  /**
15
23
  * @param {import('./decibri').SpeakerOptions} [options]
@@ -78,7 +86,9 @@ class Speaker extends Writable {
78
86
  // for a clean Node-side RangeError without a round-trip.
79
87
  let resolvedDevice = options.device;
80
88
  if (typeof options.device === 'number') {
81
- const devices = DecibriOutputBridge.devices();
89
+ // Through the static so an enumeration failure raised while resolving an
90
+ // index carries the same DeviceError the public listing does.
91
+ const devices = Speaker.devices();
82
92
  if (options.device < 0 || options.device >= devices.length) {
83
93
  throw new RangeError('device index out of range. Call Speaker.devices() to list available devices');
84
94
  }
@@ -143,24 +153,31 @@ class Speaker extends Writable {
143
153
  this._native.write(chunk);
144
154
  callback();
145
155
  } catch (err) {
146
- callback(err);
156
+ callback(wrapNativeError(err));
147
157
  }
148
158
  }
149
159
 
150
160
  /** @internal Called by end() after all buffered writes complete. */
151
161
  _final(callback) {
162
+ // end() is terminal: flush all queued audio, then stop. drain() blocks
163
+ // until everything queued has played (it is a non-terminal flush in the
164
+ // core), and stop() then ends the stream so isPlaying is false once the
165
+ // audio has finished. The flush-then-stop order plays the tail to
166
+ // completion before stopping; reversing it would truncate the audio.
167
+ // A drain that reports a device failure still has to stop, so the device is
168
+ // released on the failing path exactly as it is on the clean one.
169
+ let failure;
152
170
  try {
153
- // end() is terminal: flush all queued audio, then stop. drain() blocks
154
- // until everything queued has played (it is a non-terminal flush in the
155
- // core), and stop() then ends the stream so isPlaying is false once the
156
- // audio has finished. The flush-then-stop order plays the tail to
157
- // completion before stopping; reversing it would truncate the audio.
158
171
  this._native.drain();
172
+ } catch (err) {
173
+ failure = wrapNativeError(err);
174
+ }
175
+ try {
159
176
  this._native.stop();
160
- callback();
161
177
  } catch (err) {
162
- callback(err);
178
+ failure = failure || wrapNativeError(err);
163
179
  }
180
+ callback(failure);
164
181
  }
165
182
 
166
183
  /**
@@ -228,12 +245,26 @@ class Speaker extends Writable {
228
245
  return this._native.isPlaying;
229
246
  }
230
247
 
248
+ /**
249
+ * Number of samples emitted as silence fill because the playback queue ran
250
+ * dry. 0 while the producer keeps the queue fed, or before playback starts.
251
+ * A rising value means the output is papering over gaps with silence.
252
+ * @returns {number}
253
+ */
254
+ get underrunCount() {
255
+ return this._native.underrunCount;
256
+ }
257
+
231
258
  /**
232
259
  * List all available output devices on the system.
233
260
  * @returns {Array<{index: number, name: string, maxOutputChannels: number, defaultSampleRate: number, isDefault: boolean}>}
234
261
  */
235
262
  static devices() {
236
- return DecibriOutputBridge.devices();
263
+ try {
264
+ return DecibriOutputBridge.devices();
265
+ } catch (err) {
266
+ throw wrapNativeError(err);
267
+ }
237
268
  }
238
269
 
239
270
  /**
package/src/decibri.d.ts CHANGED
@@ -472,6 +472,19 @@ export declare class File extends Readable {
472
472
  */
473
473
  readonly vadScore: number;
474
474
 
475
+ /**
476
+ * The rate every delivered chunk carries: the `sampleRate` option, or
477
+ * 16000 when it was not given.
478
+ */
479
+ readonly sampleRate: number;
480
+
481
+ /**
482
+ * The source's own rate, taken from the WAV header or from the
483
+ * `inputRate` passed to `File.buffer`. Differs from `sampleRate` when the
484
+ * source was resampled.
485
+ */
486
+ readonly inputRate: number;
487
+
475
488
  /**
476
489
  * Analyze the whole recording for speech, off the event loop. Resolves to
477
490
  * a `VadReport` with per-window `scores` and merged speech `segments`,
@@ -479,6 +492,11 @@ export declare class File extends Readable {
479
492
  * pass). Requires `vad: 'silero'`: a File opened without `vad` rejects
480
493
  * with the core's "analysis requires VAD" error, and the energy mode has
481
494
  * no whole-file analysis.
495
+ *
496
+ * Requires a File that is not already being streamed: once the stream has
497
+ * been engaged this rejects with a `DecibriError` carrying the code
498
+ * `'FILE_ENGAGED'`. Every failure detected before the pass begins leaves
499
+ * the File usable; a failure during the pass consumes the source.
482
500
  */
483
501
  analyze(): Promise<VadReport>;
484
502
 
@@ -618,6 +636,13 @@ export declare class Speaker extends Writable {
618
636
  /** Whether audio is currently being output. */
619
637
  readonly isPlaying: boolean;
620
638
 
639
+ /**
640
+ * Number of samples emitted as silence fill because the playback queue ran
641
+ * dry. 0 while the producer keeps the queue fed, or before playback starts.
642
+ * A rising value means the output is papering over gaps with silence.
643
+ */
644
+ readonly underrunCount: number;
645
+
621
646
  /** List all available audio output devices. */
622
647
  static devices(): SpeakerInfo[];
623
648
 
package/src/decibri.js CHANGED
@@ -6,6 +6,7 @@ const fs = require('fs');
6
6
  const { DecibriBridge, FileHandle } = require('../index.js');
7
7
  const {
8
8
  wrapNativeError,
9
+ fileEngagedError,
9
10
  DecibriError,
10
11
  DeviceError,
11
12
  OrtError,
@@ -74,6 +75,12 @@ function resolveBundledOrtPath() {
74
75
 
75
76
  // ─── Microphone (Readable) ──────────────────────────────────────────────────
76
77
 
78
+ /**
79
+ * Failures that reach the consumer arrive on the `'error'` event as a
80
+ * `DecibriError` carrying a `code`: a failed open or a denied permission when
81
+ * capture starts, and a device lost mid-capture (`code === 'DEVICE_FAILED'`).
82
+ * A deliberate `stop()` ends the stream cleanly and raises nothing.
83
+ */
77
84
  class Microphone extends Readable {
78
85
  /**
79
86
  * @param {import('./decibri').MicrophoneOptions} [options]
@@ -169,7 +176,9 @@ class Microphone extends Readable {
169
176
  // for a clean Node-side RangeError without a round-trip.
170
177
  let resolvedDevice = options.device;
171
178
  if (typeof options.device === 'number') {
172
- const devices = DecibriBridge.devices();
179
+ // Through the static so an enumeration failure raised while resolving an
180
+ // index carries the same DeviceError the public listing does.
181
+ const devices = Microphone.devices();
173
182
  if (options.device < 0 || options.device >= devices.length) {
174
183
  throw new RangeError('device index out of range. Call Microphone.devices() to list available devices');
175
184
  }
@@ -255,11 +264,15 @@ class Microphone extends Readable {
255
264
  );
256
265
  }
257
266
 
267
+ // The existence pre-check runs before the native bridge is constructed, so
268
+ // it never passes through wrapNativeError. It raises the same class and
269
+ // code the deep load failure would, so the detection point differs between
270
+ // a missing file and an unloadable one but the identity does not.
258
271
  let modelPath = undefined;
259
272
  if (vadEnabled && vadMode === 'silero') {
260
273
  modelPath = options.modelPath || path.join(__dirname, '..', 'models', 'silero_vad.onnx');
261
274
  if (!fs.existsSync(modelPath)) {
262
- throw new Error(`Silero VAD model not found at ${modelPath}. Ensure the models/ directory is included in your installation.`);
275
+ throw new OrtError(`Silero VAD model not found at ${modelPath}. Ensure the models/ directory is included in your installation.`, 'VAD_MODEL_LOAD_FAILED');
263
276
  }
264
277
  }
265
278
 
@@ -288,7 +301,7 @@ class Microphone extends Readable {
288
301
  }
289
302
  denoiseModelPath = path.join(__dirname, '..', 'models', 'fastenhancer_t.onnx');
290
303
  if (!fs.existsSync(denoiseModelPath)) {
291
- throw new Error(`Denoise model not found at ${denoiseModelPath}. Ensure the models/ directory is included in your installation.`);
304
+ throw new OrtError(`Denoise model not found at ${denoiseModelPath}. Ensure the models/ directory is included in your installation.`, 'MODEL_LOAD_FAILED');
292
305
  }
293
306
  }
294
307
 
@@ -407,39 +420,45 @@ class Microphone extends Readable {
407
420
  if (this._started || this._stopped) return;
408
421
  this._started = true;
409
422
 
410
- this._native.start((err, chunk) => {
411
- if (err) {
412
- this._started = false;
413
- // A start()-time failure is delivered here as the raw native error (not
414
- // via wrapNativeError), so no decibri `code` is attached on the 'error'
415
- // event, as with device-open failures; the dedicated MODEL_LOAD_FAILED
416
- // code is reachable through wrapNativeError, not on this streaming path.
417
- this.destroy(err);
418
- return;
419
- }
423
+ // Both exits from start() reach the consumer on the 'error' event, so both
424
+ // carry a decibri class and `code`: the synchronous throw below (a failed
425
+ // device open, a denied permission) and the streaming failure delivered to
426
+ // the callback (a device lost mid-capture).
427
+ try {
428
+ this._native.start((err, chunk) => {
429
+ if (err) {
430
+ this._started = false;
431
+ this.destroy(wrapNativeError(err));
432
+ return;
433
+ }
420
434
 
421
- // On close the native pump flushes the buffered tail; that final data
422
- // callback can run after stop() has begun ending the stream. Once the
423
- // end-of-stream push(null) has been issued (or the stream was destroyed),
424
- // drop any straggler rather than pushing past EOF.
425
- if (this._ended || this.destroyed) {
426
- return;
427
- }
435
+ // On close the native pump flushes the buffered tail; that final data
436
+ // callback can run after stop() has begun ending the stream. Once the
437
+ // end-of-stream push(null) has been issued (or the stream was
438
+ // destroyed), drop any straggler rather than pushing past EOF.
439
+ if (this._ended || this.destroyed) {
440
+ return;
441
+ }
428
442
 
429
- // push returns false when the consumer is slow. We can't pause a mic,
430
- // but we surface the backpressure warning so callers can react.
431
- if (!this.push(chunk)) {
432
- this.emit('backpressure');
433
- }
443
+ // push returns false when the consumer is slow. We can't pause a mic,
444
+ // but we surface the backpressure warning so callers can react.
445
+ if (!this.push(chunk)) {
446
+ this.emit('backpressure');
447
+ }
434
448
 
435
- if (this._vad) {
436
- // Both modes read the score from native: the Silero speech probability
437
- // or, in energy mode, the RMS of the pre-enhancement signal. The native
438
- // pump computes both on the signal before the opt-in enhancement step,
439
- // so enabling enhancement does not change detection in either mode.
440
- this._processVadValue(this._native.vadProbability);
441
- }
442
- });
449
+ if (this._vad) {
450
+ // Both modes read the score from native: the Silero speech
451
+ // probability or, in energy mode, the RMS of the pre-enhancement
452
+ // signal. The native pump computes both on the signal before the
453
+ // opt-in enhancement step, so enabling enhancement does not change
454
+ // detection in either mode.
455
+ this._processVadValue(this._native.vadProbability);
456
+ }
457
+ });
458
+ } catch (err) {
459
+ this._started = false;
460
+ this.destroy(wrapNativeError(err));
461
+ }
443
462
  }
444
463
 
445
464
  /** @internal Common speech/silence state machine */
@@ -521,7 +540,11 @@ class Microphone extends Readable {
521
540
  * @returns {Array<{index: number, name: string, id: string, maxInputChannels: number, defaultSampleRate: number, isDefault: boolean}>}
522
541
  */
523
542
  static devices() {
524
- return DecibriBridge.devices();
543
+ try {
544
+ return DecibriBridge.devices();
545
+ } catch (err) {
546
+ throw wrapNativeError(err);
547
+ }
525
548
  }
526
549
 
527
550
  /**
@@ -605,6 +628,10 @@ class File extends Readable {
605
628
  this._sampleRate = prepared.nativeOptions.sampleRate;
606
629
  this._bytesPerSample = prepared.dtype === 'int16' ? 2 : 4;
607
630
  this._ended = false;
631
+ // Set the moment the consumer asks the stream for data, which is earlier
632
+ // than the moment data arrives: `resume()` and a 'readable' listener both
633
+ // schedule the first `_read()` for a later tick. See _engage.
634
+ this._engaged = false;
608
635
 
609
636
  // ── Create or adopt native handle ───────────────────────────────────────
610
637
 
@@ -700,11 +727,13 @@ class File extends Readable {
700
727
  );
701
728
  }
702
729
 
730
+ // Same pre-check and same identity as Microphone: a missing model file
731
+ // reports the class and code its load failure would.
703
732
  let modelPath = undefined;
704
733
  if (vadEnabled && vadMode === 'silero') {
705
734
  modelPath = options.modelPath || path.join(__dirname, '..', 'models', 'silero_vad.onnx');
706
735
  if (!fs.existsSync(modelPath)) {
707
- throw new Error(`Silero VAD model not found at ${modelPath}. Ensure the models/ directory is included in your installation.`);
736
+ throw new OrtError(`Silero VAD model not found at ${modelPath}. Ensure the models/ directory is included in your installation.`, 'VAD_MODEL_LOAD_FAILED');
708
737
  }
709
738
  }
710
739
 
@@ -722,7 +751,7 @@ class File extends Readable {
722
751
  }
723
752
  denoiseModelPath = path.join(__dirname, '..', 'models', 'fastenhancer_t.onnx');
724
753
  if (!fs.existsSync(denoiseModelPath)) {
725
- throw new Error(`Denoise model not found at ${denoiseModelPath}. Ensure the models/ directory is included in your installation.`);
754
+ throw new OrtError(`Denoise model not found at ${denoiseModelPath}. Ensure the models/ directory is included in your installation.`, 'MODEL_LOAD_FAILED');
726
755
  }
727
756
  }
728
757
 
@@ -838,8 +867,64 @@ class File extends Readable {
838
867
  return new File(null, options, { prepared, native });
839
868
  }
840
869
 
870
+ /**
871
+ * @internal Mark the stream as engaged: the consumer has asked it for data,
872
+ * so `analyze()` is refused from here on. Every entry point that starts the
873
+ * flow marks synchronously with the consumer's own call; the read it
874
+ * schedules runs on a later tick.
875
+ */
876
+ _engage() {
877
+ this._engaged = true;
878
+ }
879
+
880
+ /**
881
+ * Start the flow of data. Also engages the stream: `analyze()` is refused
882
+ * once the recording is being streamed.
883
+ * @returns {this}
884
+ */
885
+ resume() {
886
+ this._engage();
887
+ return super.resume();
888
+ }
889
+
890
+ /**
891
+ * Pull from the stream's buffer. Also engages the stream: `analyze()` is
892
+ * refused once the recording is being read.
893
+ * @param {number} [size]
894
+ * @returns {Buffer|null}
895
+ */
896
+ read(size) {
897
+ this._engage();
898
+ return super.read(size);
899
+ }
900
+
901
+ /**
902
+ * Attach a listener. A 'data' or 'readable' listener starts the flow, so it
903
+ * engages the stream; listeners for the VAD, error, and end events do not.
904
+ * @param {string|symbol} event
905
+ * @param {Function} listener
906
+ * @returns {this}
907
+ */
908
+ on(event, listener) {
909
+ if (event === 'data' || event === 'readable') {
910
+ this._engage();
911
+ }
912
+ return super.on(event, listener);
913
+ }
914
+
915
+ /**
916
+ * Alias of `on`, kept in step so it engages the stream the same way.
917
+ * @param {string|symbol} event
918
+ * @param {Function} listener
919
+ * @returns {this}
920
+ */
921
+ addListener(event, listener) {
922
+ return this.on(event, listener);
923
+ }
924
+
841
925
  /** @internal */
842
926
  _read() {
927
+ this._engage();
843
928
  if (this._ended) {
844
929
  return;
845
930
  }
@@ -909,6 +994,27 @@ class File extends Readable {
909
994
  return this._vadScore;
910
995
  }
911
996
 
997
+ /**
998
+ * The rate every delivered chunk carries: the `sampleRate` option, or 16000
999
+ * when it was not given. Readable for the life of the File, including after
1000
+ * the source is consumed or closed.
1001
+ * @returns {number}
1002
+ */
1003
+ get sampleRate() {
1004
+ return this._native.sampleRate;
1005
+ }
1006
+
1007
+ /**
1008
+ * The source's own rate, taken from the WAV header or from the `inputRate`
1009
+ * passed to `File.buffer`. Differs from `sampleRate` when the source was
1010
+ * resampled. Readable for the life of the File, including after the source
1011
+ * is consumed or closed.
1012
+ * @returns {number}
1013
+ */
1014
+ get inputRate() {
1015
+ return this._native.inputRate;
1016
+ }
1017
+
912
1018
  /**
913
1019
  * Analyze the whole recording for speech. Runs the recording once through
914
1020
  * the conditioning pass off the event loop and resolves to a `VadReport`:
@@ -921,9 +1027,22 @@ class File extends Readable {
921
1027
  * whole-file analysis and rejects likewise. Never constructs a detector
922
1028
  * silently.
923
1029
  *
1030
+ * Requires a `File` that is not already being streamed: once the stream has
1031
+ * been engaged, this rejects with a `DecibriError` carrying the code
1032
+ * `'FILE_ENGAGED'` rather than reporting on the part not yet read. Every
1033
+ * failure detected before the pass begins leaves the `File` usable, so
1034
+ * streaming it afterwards still works; a failure during the pass, such as
1035
+ * the detector failing to load, consumes the source.
1036
+ *
924
1037
  * @returns {Promise<import('./decibri').VadReport>}
925
1038
  */
926
1039
  async analyze() {
1040
+ // Checked before the native handle is touched: the rejection belongs to
1041
+ // this call, and the source is never taken from a File that keeps
1042
+ // streaming.
1043
+ if (this._engaged) {
1044
+ throw fileEngagedError();
1045
+ }
927
1046
  if (this._vad && this._vadMode === 'energy') {
928
1047
  throw new RangeError(
929
1048
  "analyze() requires vad: 'silero'; energy mode does not support whole-file analysis"
package/src/errors.js CHANGED
@@ -58,6 +58,38 @@ class OrtPathError extends OrtError {
58
58
  // variant's Display string (see bindings/node/src/lib.rs to_napi_error), so the
59
59
  // message text is the only thing left to classify on. The prefixes below match
60
60
  // the frozen core messages in crates/decibri/src/error.rs.
61
+ //
62
+ // The codes are the core's own: DecibriError::code() assigns one per variant
63
+ // from an exhaustive match, and the catalog check in tests/test-ci.js walks
64
+ // every variant compiled into the addon and asserts the table below reaches
65
+ // the same identity. A reworded core message, a new variant, or a prefix that
66
+ // collides with an existing one all fail that check.
67
+ //
68
+ // Prefix matching stays because some messages never cross the FFI boundary:
69
+ // the napi-authored `File already consumed`, and the model pre-checks in
70
+ // decibri.js, which are classified here without a native round-trip.
71
+
72
+ // Argument validation the core also names. These keep Node's built-ins rather
73
+ // than a decibri class, so the class matches the wrapper's own pre-check for
74
+ // the same input (decibri.js raises RangeError for a bad agc or limiter before
75
+ // the core ever sees it).
76
+ const RANGE_PREFIXES = [
77
+ 'sample rate must be between',
78
+ 'channels must be between',
79
+ 'multichannel capture is not supported',
80
+ 'frames per buffer must be between',
81
+ 'agc target level must be between',
82
+ 'limiter ceiling must be between',
83
+ 'Silero VAD only supports',
84
+ 'VAD threshold must be between',
85
+ 'device index out of range',
86
+ 'analysis requires VAD',
87
+ ];
88
+
89
+ const TYPE_PREFIXES = [
90
+ "dtype must be 'int16' or 'float32'",
91
+ "format must be 'int16' or 'float32'",
92
+ ];
61
93
 
62
94
  const DEVICE_CODES = [
63
95
  ['No microphone found matching', 'MICROPHONE_NOT_FOUND'],
@@ -78,6 +110,48 @@ const ORT_CODES = [
78
110
  ['Silero VAD inference failed', 'ORT_INFERENCE_FAILED'],
79
111
  ];
80
112
 
113
+ // Failures that carry a base DecibriError plus their own code: stream
114
+ // lifecycle, runtime device and driver faults, offline file reads, and the
115
+ // two ONNX failures that are not ORT setup failures. Matches the Python
116
+ // binding, where each of these is a direct DecibriError subclass rather than
117
+ // a member of the DeviceError or OrtError family.
118
+ const BASE_CODES = [
119
+ ['audio stream is already running', 'ALREADY_RUNNING'],
120
+ ['Failed to open audio stream', 'STREAM_OPEN_FAILED'],
121
+ ['Failed to start audio stream', 'STREAM_START_FAILED'],
122
+ ['Microphone permission denied.', 'PERMISSION_DENIED'],
123
+ ['Microphone stream is closed', 'MICROPHONE_STREAM_CLOSED'],
124
+ ['Speaker stream is closed', 'SPEAKER_STREAM_CLOSED'],
125
+ ['decibri: audio device error:', 'DEVICE_FAILED'],
126
+ ['the requested sample rate conversion is not supported', 'RESAMPLE_CONFIG_INVALID'],
127
+ ['Failed to read audio file', 'FILE_READ_FAILED'],
128
+ ['invalid WAV file:', 'WAV_INVALID'],
129
+ ['ONNX Runtime was initialized in pid', 'FORK_AFTER_ORT_INIT'],
130
+ ['ONNX backend error from', 'ONNX_BACKEND_FAILED'],
131
+ // Authored in the napi layer (bindings/node/src/lib.rs), not in
132
+ // crates/decibri/src/error.rs: reusing a File after its single pass.
133
+ ['File already consumed', 'FILE_CONSUMED'],
134
+ // The offline counterpart of a closed stream: analysing a File whose
135
+ // iteration has begun.
136
+ ['File iteration has begun', 'FILE_ENGAGED'],
137
+ ];
138
+
139
+ // The core's message for analysing a File whose iteration has begun. The
140
+ // wrapper raises it at the call site, before the native handle is touched.
141
+ const FILE_ENGAGED_MESSAGE =
142
+ 'File iteration has begun; construct a new File to analyze the whole recording';
143
+
144
+ /**
145
+ * The lifecycle error for analysing a File that is already being iterated.
146
+ * One place for the message and the code, shared by the wrapper's call-site
147
+ * check and the native classification below.
148
+ *
149
+ * @returns {DecibriError}
150
+ */
151
+ function fileEngagedError() {
152
+ return new DecibriError(FILE_ENGAGED_MESSAGE, 'FILE_ENGAGED');
153
+ }
154
+
81
155
  /**
82
156
  * Wrap an error thrown from a native DecibriBridge / DecibriOutputBridge call
83
157
  * into the appropriate JS error: a built-in for argument validation, or a
@@ -93,22 +167,11 @@ function wrapNativeError(err) {
93
167
  // Argument validation stays as Node built-ins. `device index out of range`
94
168
  // is kept here (RangeError) so the index error type is the same whether it
95
169
  // is raised by the client-side bounds check or by the core.
96
- if (
97
- msg.startsWith('sample rate must be between') ||
98
- msg.startsWith('channels must be between') ||
99
- msg.startsWith('frames per buffer must be between') ||
100
- msg.startsWith('Silero VAD only supports') ||
101
- msg.startsWith('VAD threshold must be between') ||
102
- msg.startsWith('device index out of range') ||
103
- msg.startsWith('analysis requires VAD')
104
- ) {
105
- return new RangeError(msg);
170
+ for (const prefix of RANGE_PREFIXES) {
171
+ if (msg.startsWith(prefix)) return new RangeError(msg);
106
172
  }
107
- if (
108
- msg.startsWith("dtype must be 'int16' or 'float32'") ||
109
- msg.startsWith("format must be 'int16' or 'float32'")
110
- ) {
111
- return new TypeError(msg);
173
+ for (const prefix of TYPE_PREFIXES) {
174
+ if (msg.startsWith(prefix)) return new TypeError(msg);
112
175
  }
113
176
 
114
177
  // Device enumeration / selection failures.
@@ -132,25 +195,12 @@ function wrapNativeError(err) {
132
195
  return new OrtError(msg, 'ORT_TENSOR_EXTRACT_FAILED');
133
196
  }
134
197
 
135
- // Runtime device/driver failure during streaming. Distinct from the
198
+ // Stream lifecycle, runtime device/driver faults, offline file reads, and the
199
+ // ONNX failures outside the ORT setup family. Distinct from the
136
200
  // enumeration/selection DeviceError family above (which mirrors the core's
137
- // "Device errors"): this is the core's "Stream errors" DeviceFailed, surfaced
138
- // as a base DecibriError with a dedicated code.
139
- if (msg.startsWith('decibri: audio device error:')) {
140
- return new DecibriError(msg, 'DEVICE_FAILED');
141
- }
142
- // Non-ORT ONNX backend failure: the reserved backend catch-all, surfaced as a
143
- // base DecibriError with a dedicated code (not an OrtError).
144
- if (msg.startsWith('ONNX backend error from')) {
145
- return new DecibriError(msg, 'ONNX_BACKEND_FAILED');
146
- }
147
- // Reusing a File after its single pass (analysis or iteration consumed the
148
- // source) is a lifecycle failure, the offline counterpart of a closed stream:
149
- // a base DecibriError with a dedicated code, not the RangeError reserved for
150
- // argument validation. Unlike the prefixes above, this message is authored in
151
- // the napi layer (bindings/node/src/lib.rs), not in crates/decibri/src/error.rs.
152
- if (msg.startsWith('File already consumed')) {
153
- return new DecibriError(msg, 'FILE_CONSUMED');
201
+ // "Device errors").
202
+ for (const [prefix, code] of BASE_CODES) {
203
+ if (msg.startsWith(prefix)) return new DecibriError(msg, code);
154
204
  }
155
205
 
156
206
  // Any other error from the native constructor is still a decibri error.
@@ -162,5 +212,6 @@ module.exports = {
162
212
  DeviceError,
163
213
  OrtError,
164
214
  OrtPathError,
215
+ fileEngagedError,
165
216
  wrapNativeError,
166
217
  };