decibri 5.2.4 → 5.3.0

package/CHANGELOG.md

@@ -9,6 +9,22 @@ For other decibri packages, see:
 - Rust core: [crates/decibri/CHANGELOG.md](../../crates/decibri/CHANGELOG.md)
 - Python package: [bindings/python/CHANGELOG.md](../../bindings/python/CHANGELOG.md)
 
+## [5.3.0] - 2026-07-31
+
+### Added
+
+- `aec` option on `Microphone`: acoustic echo cancellation on the capture path. The short form names the model (`aec: 'tau'`); the object form takes `{ model, tailMs, suppression, referenceSampleRate }`. It runs before the detector tap, so `vadScore` and the `speech` / `silence` events read the echo-removed signal, and it requires `sampleRate` in 8000 to 48000. Native capture only: the browser entry keeps the platform's own `echoCancellation` constraint.
+- `Microphone.pushAecReference(data)`, which queues the far-end audio the canceller cancels against: the same input shapes `Speaker.write` accepts, mono, in played order, at the declared `referenceSampleRate`. It never blocks and never throws on a full queue. When it is pushed does not have to match when it plays: the queue is read at the rate the capture consumes it, so a greeting pushed before the first `data` event, or a whole utterance handed over in one call, is read out over the capture it echoes into and every sample of it is cancelled against. The queue holds two seconds, which bounds how far ahead of its own capture a caller may run.
+- `Microphone.aecMetrics()`, the canceller's transport and cancellation metrics merged with the reference queue's counters, or `null` while echo cancellation is off or capture is not running.
+
+Echo cancellation joins automatic gain control as a stage that can drive captured samples above full scale when the limiter is off, because it subtracts its estimate of the echo from the capture and exceeds the capture wherever that estimate is wrong in phase. The limiter runs after it and bounds the output to its ceiling; the `int16` sample format clamps, so an over-scale sample arrives as full scale rather than wrapping, and a `float32` consumer without the limiter should clamp its own output.
+
+## [5.2.5] - 2026-07-28
+
+### Changed
+
+- The packaged addon is rebuilt from the current core, and the bundle regenerate command in `examples/README.md` reproduces the committed file.
+
 ## [5.2.4] - 2026-07-28
 
 ### Added

package/examples/README.md

@@ -71,10 +71,15 @@ npx localtunnel --port 8080
 ### Regenerating the browser bundle
 
 `decibri.browser.js` is generated from the package's browser entry
-(`../src/browser/index.js`) with rolldown, the bundler used to produce the
-checked-in build. Regenerate it after changing the browser source so the
-bundle stays in sync:
+(`npm/decibri/src/browser/index.js`) with rolldown, the bundler used to produce
+the checked-in build. Regenerate it after changing the browser source so the
+bundle stays in sync.
+
+Run the command from the repository root, with both paths repo-root relative.
+Run from anywhere else and the bundle still builds, but it records the module
+paths relative to that directory instead. The `--banner` flag carries the
+generated file's first line:
 
 ```bash
-npx rolldown ../src/browser/index.js --format iife --name decibri --file decibri.browser.js
+npx rolldown npm/decibri/src/browser/index.js --format iife --name decibri --file npm/decibri/examples/decibri.browser.js --banner "// decibri browser bundle. GENERATED from src/browser/index.js. Do not edit by hand; see examples/README.md to regenerate."
 ```

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

package/index.d.ts

@@ -29,6 +29,21 @@ export declare class DecibriBridge {
    * number for any realistic count) to match the `vadProbability` getter.
    */
   get overrunCount(): number
+  /**
+   * Queue far-end reference audio for the echo canceller. `buffer` is mono
+   * PCM bytes in the bridge's configured format, at the declared reference
+   * rate, in played order. Never blocks and never fails: a full queue
+   * discards and counts rather than erroring, and a push with no active
+   * stream (not started, stopped, or echo cancellation off) is a no-op.
+   */
+  pushAecReference(buffer: Buffer): void
+  /**
+   * The echo canceller's transport and cancellation metrics, merged with the
+   * reference queue's own counters, or `null` when no stream is active or
+   * echo cancellation is off. Counters are returned as f64 (exact JS numbers
+   * for any realistic count), matching the `overrunCount` getter.
+   */
+  aecMetrics(): AecMetricsJs | null
   /** List all available audio input devices. */
   static devices(): Array<DeviceInfoJs>
   /** Version information. */
@@ -148,6 +163,62 @@ export declare class FileHandle {
   get inputRate(): number
 }
 
+/**
+ * Echo-cancellation metrics returned to JS by `aecMetrics()`. One object
+ * carries the canceller's own report and the reference queue's counters, so a
+ * caller reads one surface for the whole diagnosis.
+ */
+export interface AecMetricsJs {
+  /**
+   * The active delay alignment in samples, or `null` while the estimator is
+   * still searching. Staying `null` while `acquisitionParked` climbs is the
+   * signature of a canceller with no usable reference: none pushed, not at
+   * the declared rate, or not the signal that produced the echo.
+   */
+  delaySamples?: number
+  /**
+   * Smoothed echo-return-loss-enhancement estimate in dB: how much echo the
+   * canceller is currently removing. 0 before the filter has converged.
+   */
+  erleDb: number
+  /**
+   * Whether the double-talk detector currently believes the near-end talker
+   * is active; adaptation is held while true.
+   */
+  doubleTalk: boolean
+  /**
+   * Near-end samples the canceller could find no far-end sample for while an
+   * alignment was active. The core keeps the far-end stream level with the
+   * capture, so this stays 0 for a caller who simply stops pushing; a
+   * non-zero count means the caller ran further ahead of the capture than
+   * the canceller's far-end history reaches.
+   */
+  referenceStarved: number
+  /**
+   * Near-end samples processed while no delay alignment was active: the
+   * searching span, not a transport failure.
+   */
+  acquisitionParked: number
+  /**
+   * Times the canceller inferred a capture discontinuity and rebuilt its
+   * alignment from the reference frontier.
+   */
+  referenceReanchors: number
+  /**
+   * Far-end samples discarded because a single push exceeded the reference
+   * queue's bound, at the declared reference rate. The span they occupied is
+   * still represented as silence, so a discard costs the cancellation of
+   * that span alone.
+   */
+  referenceDropped: number
+  /**
+   * Far-end samples the core supplied as silence because the caller had
+   * pushed none for them, at the capture rate. An accounting figure, not a
+   * fault: while nothing is playing, the far end is silence.
+   */
+  referenceSilence: number
+}
+
 /**
  * Options passed from JS constructor.
  *
@@ -215,6 +286,34 @@ export interface DecibriOptions {
    * DSP: no bundled file and no model path, like `agc`.
    */
   limiter?: number
+  /**
+   * Echo canceller model name. The accepted set is owned by the canceller
+   * (`AecModel::from_str`); today it is `'tau'`. Absent leaves echo
+   * cancellation off. The JS wrapper resolves both public forms (the string
+   * shorthand and the `AecOptions` object) into this field and the three
+   * below. Pure DSP: no bundled file and no model path, like `highpass`.
+   */
+  aec?: string
+  /**
+   * Echo canceller filter tail in milliseconds: an integer in `16..=500`.
+   * Absent takes the canceller's own default. Consulted only when `aec`
+   * names a model.
+   */
+  aecTailMs?: number
+  /**
+   * Residual-suppression policy for the echo canceller: `'conservative'` or
+   * `'off'`. Absent takes the canceller's own default. Consulted only when
+   * `aec` names a model.
+   */
+  aecSuppression?: string
+  /**
+   * Sample rate in Hz of the far-end reference pushed through
+   * `pushAecReference`, in `1000..=384000`. Absent means the reference is
+   * already at the capture rate; when it names a different rate, the core
+   * converts the reference before the canceller sees it. Consulted only
+   * when `aec` names a model.
+   */
+  aecReferenceSampleRate?: number
 }
 
 /** Options passed from JS constructor for output. */

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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4' && 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.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '5.3.0' && 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.3.0 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.4",
+  "version": "5.3.0",
   "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.4",
-    "@decibri/decibri-darwin-arm64": "5.2.4",
-    "@decibri/decibri-linux-x64-gnu": "5.2.4",
-    "@decibri/decibri-linux-arm64-gnu": "5.2.4"
+    "@decibri/decibri-win32-x64-msvc": "5.3.0",
+    "@decibri/decibri-darwin-arm64": "5.3.0",
+    "@decibri/decibri-linux-x64-gnu": "5.3.0",
+    "@decibri/decibri-linux-arm64-gnu": "5.3.0"
   },
   "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.4';
+const VERSION = '5.3.0';
 
 /**
  * Browser microphone capture.

package/src/decibri.d.ts

@@ -61,6 +61,108 @@ export interface VadOptions {
   holdoffMs?: number;
 }
 
+/**
+ * Acoustic echo cancellation config object, passed on the `aec` option to tune
+ * the canceller. The bare `aec: 'tau'` shorthand selects the model with its
+ * defaults; pass this object to override them.
+ *
+ * The canceller's behaviour while a lost delay alignment is being reacquired
+ * is fixed: decibri applies the canceller's graded output transition and does
+ * not expose a setting for it.
+ */
+export interface AecOptions {
+  /**
+   * Which echo canceller model to run. The accepted set is owned by the
+   * canceller and grows the way `denoise` grows; today it is `'tau'`, a
+   * classical adaptive canceller with no model file. An unknown name is
+   * rejected with the canceller's own message naming the accepted set.
+   */
+  model: 'tau';
+
+  /**
+   * Adaptive filter tail length in milliseconds: how much echo delay spread
+   * the canceller can model.
+   * @default the canceller's own default (200)
+   * @range 16 to 500
+   */
+  tailMs?: number;
+
+  /**
+   * Residual echo suppression policy. `'conservative'` attenuates the residual
+   * echo the linear canceller leaves behind while keeping the near-end voice
+   * intact; `'off'` delivers the linear canceller output as-is.
+   * @default 'conservative'
+   */
+  suppression?: 'conservative' | 'off';
+
+  /**
+   * Sample rate in Hz of the far-end reference pushed through
+   * `pushAecReference`. When it names a rate other than `sampleRate`, decibri
+   * converts the reference before the canceller sees it: a reference at an
+   * undeclared different rate cancels nothing and reports no error, so the
+   * conversion is decibri's rather than the caller's.
+   * @default the capture `sampleRate`
+   * @range 1000 to 384000
+   */
+  referenceSampleRate?: number;
+}
+
+/**
+ * The echo canceller's transport and cancellation metrics, returned by
+ * `Microphone.aecMetrics()`. One object carries the canceller's own report and
+ * the reference queue's counters.
+ */
+export interface AecMetrics {
+  /**
+   * The active delay alignment in samples, or `null` while the estimator is
+   * still searching. Staying `null` while `acquisitionParked` climbs is the
+   * signature of a canceller with no usable reference: none pushed, not at the
+   * declared rate, or not the signal that produced the echo.
+   */
+  delaySamples: number | null;
+  /**
+   * Smoothed echo-return-loss-enhancement estimate in dB: how much echo the
+   * canceller is currently removing. 0 before the filter has converged.
+   */
+  erleDb: number;
+  /**
+   * Whether the double-talk detector currently believes the near-end talker is
+   * active; adaptation is held while true.
+   */
+  doubleTalk: boolean;
+  /**
+   * Near-end samples the canceller could find no far-end sample for while an
+   * alignment was active. decibri keeps the far-end stream level with the
+   * capture, so this stays 0 for a caller who simply stops pushing; a non-zero
+   * count means the caller ran further ahead of the capture than the
+   * canceller's far-end history reaches.
+   */
+  referenceStarved: number;
+  /**
+   * Near-end samples processed while no delay alignment was active: the
+   * searching span, not a transport failure.
+   */
+  acquisitionParked: number;
+  /**
+   * Times the canceller inferred a capture discontinuity and rebuilt its
+   * alignment from the reference frontier.
+   */
+  referenceReanchors: number;
+  /**
+   * Far-end samples discarded because a single push exceeded the reference
+   * queue's bound, at the declared reference rate. The span they occupied is
+   * still represented as silence, so a discard costs the cancellation of that
+   * span alone.
+   */
+  referenceDropped: number;
+  /**
+   * Far-end samples decibri supplied as silence because the caller had pushed
+   * none for them, at the capture rate. An accounting figure, not a fault:
+   * while nothing is playing, the far end is silence.
+   */
+  referenceSilence: number;
+}
+
 /** Constructor options for `Microphone`. */
 export interface MicrophoneOptions extends ReadableOptions {
   /**
@@ -186,6 +288,26 @@ export interface MicrophoneOptions extends ReadableOptions {
    * @default undefined
    */
   limiter?: number;
+
+  /**
+   * Acoustic echo cancellation applied to the captured audio, removing the
+   * echo of far-end audio the caller pushes through `pushAecReference`. The
+   * `'tau'` shorthand names the model; an `AecOptions` object tunes it. Omit
+   * to leave echo cancellation off (the default), which keeps the capture
+   * path unchanged.
+   *
+   * Runs before the detector tap: with it on, `vadScore` and the `speech` /
+   * `silence` events read the echo-removed signal, so playback stops
+   * triggering detection. Requires `sampleRate` in 8000 to 48000, narrower
+   * than the range the option otherwise accepts. With no reference pushed,
+   * the captured audio passes through unchanged.
+   *
+   * Native capture only: the browser entry does not take this option, because
+   * browser capture already carries the platform's own echo cancellation
+   * through its `echoCancellation` constraint, on by default.
+   * @default undefined
+   */
+  aec?: 'tau' | AecOptions;
 }
 
 /**
@@ -245,6 +367,27 @@ export declare class Microphone extends Readable {
    */
   readonly overrunCount: number;
 
+  /**
+   * Queue far-end reference audio for the echo canceller: the audio being
+   * played out, pushed as it is played, in played order. Accepts the same
+   * input shapes `Speaker.write` accepts (a `Buffer`, any TypedArray, or a
+   * `DataView` of PCM bytes in this microphone's `dtype`), mono, at the
+   * declared `referenceSampleRate` (the capture rate when unset).
+   *
+   * Never blocks and never throws on a full queue: samples that do not fit
+   * are discarded and counted by `aecMetrics().referenceDropped`. Silence
+   * between played audio need not be pushed. A push while capture is not
+   * running, or with the `aec` option unset, is a no-op.
+   */
+  pushAecReference(data: Buffer | NodeJS.ArrayBufferView): void;
+
+  /**
+   * The echo canceller's transport and cancellation metrics, merged with the
+   * reference queue's counters, or `null` when the `aec` option is unset or
+   * capture is not running.
+   */
+  aecMetrics(): AecMetrics | null;
+
   /** List all available audio input devices. */
   static devices(): MicrophoneInfo[];
 

package/src/decibri.js

@@ -342,6 +342,68 @@ class Microphone extends Readable {
       throw new RangeError('limiter ceiling must be between -3.0 and 0.0');
     }
 
+    // ── Validate AEC ─────────────────────────────────────────────────────────
+
+    // Echo cancellation: the 'tau' shorthand names the model, or an
+    // { model, tailMs, suppression, referenceSampleRate } object tunes it;
+    // absence leaves it off. The model name is deliberately NOT checked
+    // against a list here: the canceller owns the accepted set, so the native
+    // layer parses it (AecModel::from_str) and an unknown name is rejected by
+    // the native constructor with the canceller's own message (a DecibriError
+    // with code 'AEC_CONFIG_INVALID'). The three tuning fields are checked
+    // here with the same RangeError / TypeError classes the other
+    // conditioning options use; the native layer backstops the same checks.
+    // The capture-rate window (8000..=48000 with AEC on) is guarded by the
+    // core, surfacing as a RangeError from the native constructor.
+    const aec = options.aec;
+    let aecModel;
+    let aecTailMs;
+    let aecSuppression;
+    let aecReferenceSampleRate;
+    if (aec !== undefined) {
+      if (typeof aec === 'string') {
+        aecModel = aec;
+      } else if (aec !== null && typeof aec === 'object' && !Array.isArray(aec)) {
+        const { model, tailMs, suppression, referenceSampleRate } = aec;
+        if (typeof model !== 'string') {
+          throw new TypeError(
+            `Invalid aec model: ${JSON.stringify(model)}. Expected a model name string such as 'tau'.`
+          );
+        }
+        aecModel = model;
+        if (tailMs !== undefined) {
+          if (typeof tailMs !== 'number' || Number.isNaN(tailMs)) {
+            throw new TypeError('aec tailMs must be a number');
+          }
+          if (tailMs < 16 || tailMs > 500) {
+            throw new RangeError('aec tailMs must be between 16 and 500');
+          }
+          aecTailMs = tailMs;
+        }
+        if (suppression !== undefined) {
+          if (suppression !== 'conservative' && suppression !== 'off') {
+            throw new TypeError(
+              `aec suppression must be 'conservative' or 'off'; got ${JSON.stringify(suppression)}`
+            );
+          }
+          aecSuppression = suppression;
+        }
+        if (referenceSampleRate !== undefined) {
+          if (typeof referenceSampleRate !== 'number' || Number.isNaN(referenceSampleRate)) {
+            throw new TypeError('aec referenceSampleRate must be a number');
+          }
+          if (referenceSampleRate < 1000 || referenceSampleRate > 384000) {
+            throw new RangeError('aec referenceSampleRate must be between 1000 and 384000');
+          }
+          aecReferenceSampleRate = referenceSampleRate;
+        }
+      } else {
+        throw new TypeError(
+          `Invalid aec value: ${JSON.stringify(aec)}. Expected a model name such as 'tau', or a config object { model, tailMs, suppression, referenceSampleRate }.`
+        );
+      }
+    }
+
     // Internal plumbing: inject the bundled ORT dylib path into the napi
     // constructor whenever an ONNX stage loads (Silero VAD or denoise). If
     // resolution fails (unknown platform, platform package not installed), this
@@ -377,6 +439,10 @@ class Microphone extends Readable {
         highpass,
         agc,
         limiter,
+        aec: aecModel,
+        aecTailMs,
+        aecSuppression,
+        aecReferenceSampleRate,
       },
     };
   }
@@ -535,6 +601,67 @@ class Microphone extends Readable {
     return this._native.overrunCount;
   }
 
+  /**
+   * Queue far-end reference audio for the echo canceller: the audio being
+   * played out, pushed as it is played, in played order. Accepts the same
+   * input shapes `Speaker.write` accepts (a `Buffer`, any TypedArray, or a
+   * `DataView` of PCM bytes in this microphone's `dtype`), mono, at the
+   * declared `referenceSampleRate` (the capture rate when unset).
+   *
+   * Never blocks and never throws on a full queue: samples that do not fit
+   * are discarded and counted by `aecMetrics().referenceDropped`, and the
+   * span they occupied is represented as silence. Silence between played
+   * audio need not be pushed; a caller that stops pushing has said nothing is
+   * playing. A push while capture is not running, or with the `aec` option
+   * unset, is a no-op.
+   *
+   * @param {Buffer | NodeJS.ArrayBufferView} data PCM samples in the
+   *   configured `dtype`.
+   */
+  pushAecReference(data) {
+    let buf;
+    if (Buffer.isBuffer(data)) {
+      buf = data;
+    } else if (ArrayBuffer.isView(data)) {
+      // Any TypedArray or DataView: view the same bytes, no copy, exactly as
+      // the stream machinery normalizes a typed-array write to a Speaker.
+      buf = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    } else {
+      throw new TypeError(
+        'pushAecReference requires a Buffer, TypedArray, or DataView of PCM samples in the configured dtype'
+      );
+    }
+    this._native.pushAecReference(buf);
+  }
+
+  /**
+   * The echo canceller's transport and cancellation metrics, merged with the
+   * reference queue's counters, or `null` when the `aec` option is unset or
+   * capture is not running.
+   *
+   * `delaySamples` staying `null` while `acquisitionParked` climbs is the
+   * signature of a canceller with no usable reference: none pushed, not at
+   * the declared rate, or not the signal that produced the echo. A climbing
+   * `referenceDropped` means single pushes are exceeding the reference
+   * queue's bound.
+   *
+   * @returns {import('./decibri').AecMetrics | null}
+   */
+  aecMetrics() {
+    const m = this._native.aecMetrics();
+    if (m === null || m === undefined) return null;
+    return {
+      delaySamples: m.delaySamples ?? null,
+      erleDb: m.erleDb,
+      doubleTalk: m.doubleTalk,
+      referenceStarved: m.referenceStarved,
+      acquisitionParked: m.acquisitionParked,
+      referenceReanchors: m.referenceReanchors,
+      referenceDropped: m.referenceDropped,
+      referenceSilence: m.referenceSilence,
+    };
+  }
+
   /**
    * List all available input devices on the system.
    * @returns {Array<{index: number, name: string, id: string, maxInputChannels: number, defaultSampleRate: number, isDefault: boolean}>}

package/src/errors.js

@@ -80,8 +80,11 @@ const RANGE_PREFIXES = [
   'frames per buffer must be between',
   'agc target level must be between',
   'limiter ceiling must be between',
+  'aec tailMs must be between',
+  'aec referenceSampleRate must be between',
   'Silero VAD only supports',
   'VAD threshold must be between',
+  'echo cancellation only supports',
   'device index out of range',
   'analysis requires VAD',
 ];
@@ -89,6 +92,7 @@ const RANGE_PREFIXES = [
 const TYPE_PREFIXES = [
   "dtype must be 'int16' or 'float32'",
   "format must be 'int16' or 'float32'",
+  'aec suppression must be',
 ];
 
 const DEVICE_CODES = [
@@ -126,6 +130,7 @@ const BASE_CODES = [
   ['the requested sample rate conversion is not supported', 'RESAMPLE_CONFIG_INVALID'],
   ['the resample chain was fed after it was flushed', 'RESAMPLE_AFTER_FLUSH'],
   ['resampler error:', 'RESAMPLE_FAILED'],
+  ['echo canceller configuration error:', 'AEC_CONFIG_INVALID'],
   ['Failed to read audio file', 'FILE_READ_FAILED'],
   ['invalid WAV file:', 'WAV_INVALID'],
   ['ONNX Runtime was initialized in pid', 'FORK_AFTER_ORT_INIT'],