decibri 5.2.1 → 5.2.2

package/CHANGELOG.md

@@ -9,6 +9,22 @@ 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)
 
+## [5.2.2] - 2026-07-25
+
+### Added
+
+- The refused-analysis failure carries the dedicated `code` `'FILE_ENGAGED'` on a `DecibriError`.
+
+### Changed
+
+- `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.
+- A fully streamed `File` rejects an analysis with `'FILE_ENGAGED'` where it previously rejected with `'FILE_CONSUMED'`.
+
+### Fixed
+
+- 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.
+- 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.
+
 ## [5.2.1] - 2026-07-24
 
 ### Changed

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.1";
+		const VERSION = "5.2.2";
 		/**
 		* Browser microphone capture.
 		*

package/index.d.ts

@@ -111,6 +111,10 @@ export declare class FileHandle {
    * JS event loop. Resolves to the `VadReport`; a `File` built without VAD
    * rejects with the core's typed error, never a silently constructed
    * detector.
+   *
+   * Everything checkable is checked before the source is taken, so a
+   * rejected call leaves the File exactly as it was and the caller can fix
+   * the configuration and retry.
    */
   analyze(): Promise<unknown>
   /** Release the source. Idempotent; a closed File reads as ended. */

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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      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.`)
       }
       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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1' && 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.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         return binding
       } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decibri",
-  "version": "5.2.1",
+  "version": "5.2.2",
   "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.1",
-    "@decibri/decibri-darwin-arm64": "5.2.1",
-    "@decibri/decibri-linux-x64-gnu": "5.2.1",
-    "@decibri/decibri-linux-arm64-gnu": "5.2.1"
+    "@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"
   },
   "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.1';
+const VERSION = '5.2.2';
 
 /**
  * Browser microphone capture.

package/src/decibri.d.ts

@@ -479,6 +479,11 @@ export declare class File extends Readable {
    * pass). Requires `vad: 'silero'`: a File opened without `vad` rejects
    * with the core's "analysis requires VAD" error, and the energy mode has
    * no whole-file analysis.
+   *
+   * Requires a File that is not already being streamed: once the stream has
+   * been engaged this rejects with a `DecibriError` carrying the code
+   * `'FILE_ENGAGED'`. Every failure detected before the pass begins leaves
+   * the File usable; a failure during the pass consumes the source.
    */
   analyze(): Promise<VadReport>;
 

package/src/decibri.js

@@ -6,6 +6,7 @@ const fs = require('fs');
 const { DecibriBridge, FileHandle } = require('../index.js');
 const {
   wrapNativeError,
+  fileEngagedError,
   DecibriError,
   DeviceError,
   OrtError,
@@ -605,6 +606,10 @@ class File extends Readable {
     this._sampleRate = prepared.nativeOptions.sampleRate;
     this._bytesPerSample = prepared.dtype === 'int16' ? 2 : 4;
     this._ended = false;
+    // Set the moment the consumer asks the stream for data, which is earlier
+    // than the moment data arrives: `resume()` and a 'readable' listener both
+    // schedule the first `_read()` for a later tick. See _engage.
+    this._engaged = false;
 
     // ── Create or adopt native handle ───────────────────────────────────────
 
@@ -838,8 +843,64 @@ class File extends Readable {
     return new File(null, options, { prepared, native });
   }
 
+  /**
+   * @internal Mark the stream as engaged: the consumer has asked it for data,
+   * so `analyze()` is refused from here on. Every entry point that starts the
+   * flow marks synchronously with the consumer's own call; the read it
+   * schedules runs on a later tick.
+   */
+  _engage() {
+    this._engaged = true;
+  }
+
+  /**
+   * Start the flow of data. Also engages the stream: `analyze()` is refused
+   * once the recording is being streamed.
+   * @returns {this}
+   */
+  resume() {
+    this._engage();
+    return super.resume();
+  }
+
+  /**
+   * Pull from the stream's buffer. Also engages the stream: `analyze()` is
+   * refused once the recording is being read.
+   * @param {number} [size]
+   * @returns {Buffer|null}
+   */
+  read(size) {
+    this._engage();
+    return super.read(size);
+  }
+
+  /**
+   * Attach a listener. A 'data' or 'readable' listener starts the flow, so it
+   * engages the stream; listeners for the VAD, error, and end events do not.
+   * @param {string|symbol} event
+   * @param {Function} listener
+   * @returns {this}
+   */
+  on(event, listener) {
+    if (event === 'data' || event === 'readable') {
+      this._engage();
+    }
+    return super.on(event, listener);
+  }
+
+  /**
+   * Alias of `on`, kept in step so it engages the stream the same way.
+   * @param {string|symbol} event
+   * @param {Function} listener
+   * @returns {this}
+   */
+  addListener(event, listener) {
+    return this.on(event, listener);
+  }
+
   /** @internal */
   _read() {
+    this._engage();
     if (this._ended) {
       return;
     }
@@ -921,9 +982,22 @@ class File extends Readable {
    * whole-file analysis and rejects likewise. Never constructs a detector
    * silently.
    *
+   * Requires a `File` that is not already being streamed: once the stream has
+   * been engaged, this rejects with a `DecibriError` carrying the code
+   * `'FILE_ENGAGED'` rather than reporting on the part not yet read. Every
+   * failure detected before the pass begins leaves the `File` usable, so
+   * streaming it afterwards still works; a failure during the pass, such as
+   * the detector failing to load, consumes the source.
+   *
    * @returns {Promise<import('./decibri').VadReport>}
    */
   async analyze() {
+    // Checked before the native handle is touched: the rejection belongs to
+    // this call, and the source is never taken from a File that keeps
+    // streaming.
+    if (this._engaged) {
+      throw fileEngagedError();
+    }
     if (this._vad && this._vadMode === 'energy') {
       throw new RangeError(
         "analyze() requires vad: 'silero'; energy mode does not support whole-file analysis"

package/src/errors.js

@@ -78,6 +78,22 @@ const ORT_CODES = [
   ['Silero VAD inference failed', 'ORT_INFERENCE_FAILED'],
 ];
 
+// 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 =
+  'File iteration has begun; construct a new File to analyze the whole recording';
+
+/**
+ * The lifecycle error for analysing a File that is already being iterated.
+ * One place for the message and the code, shared by the wrapper's call-site
+ * check and the native classification below.
+ *
+ * @returns {DecibriError}
+ */
+function fileEngagedError() {
+  return new DecibriError(FILE_ENGAGED_MESSAGE, 'FILE_ENGAGED');
+}
+
 /**
  * Wrap an error thrown from a native DecibriBridge / DecibriOutputBridge call
  * into the appropriate JS error: a built-in for argument validation, or a
@@ -152,6 +168,12 @@ function wrapNativeError(err) {
   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');
+  }
 
   // Any other error from the native constructor is still a decibri error.
   return new DecibriError(msg, 'DECIBRI_ERROR');
@@ -162,5 +184,6 @@ module.exports = {
   DeviceError,
   OrtError,
   OrtPathError,
+  fileEngagedError,
   wrapNativeError,
 };