decibri 5.2.5 → 5.4.0

package/src/decibri.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { Readable } = require('stream');
+const { Readable, Writable } = require('stream');
 const path = require('path');
 const fs = require('fs');
 const { DecibriBridge, FileHandle } = require('../index.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}>}
@@ -587,19 +714,20 @@ function version() {
 
 class File extends Readable {
   /**
-   * Open a WAV file as an offline source, synchronously. Everything a
+   * Open an audio file as an offline source, synchronously. Everything a
    * `Microphone` does to live audio, a `File` does to audio you already
    * have: the same conditioning options, the same stream of conditioned
    * chunks, and (with `vad` set) the same per-chunk speech events, plus the
    * whole-file `analyze()` a live stream cannot offer.
    *
-   * The bare constructor reads the WAV inline, blocking the event loop on
+   * The bare constructor reads the file inline, blocking the event loop on
    * disk I/O; prefer `await File.open(path, options)` in servers and other
    * latency-sensitive code, exactly as `Microphone.open` is preferred over
    * `new Microphone`. Iteration and analysis are separate single passes:
    * each consumes the source once, so use one `File` per operation.
    *
-   * @param {string} filePath Path to a WAV file (16-bit PCM or 32-bit float).
+   * @param {string} filePath Path to a WAV, AIFF, AIFF-C or FLAC file. The
+   *   container is identified from the bytes, not from the extension.
    * @param {import('./decibri').FileOptions} [options]
    * @param {{ prepared: object, native: object }} [_internal] Internal: a
    *   pre-resolved options bundle and an already-constructed native handle,
@@ -805,8 +933,8 @@ class File extends Readable {
   }
 
   /**
-   * Open a WAV file without blocking the event loop: the disk read, WAV
-   * parse, and chain construction run on the native thread pool. The
+   * Open an audio file without blocking the event loop: the disk read,
+   * decode, and chain construction run on the native thread pool. The
    * recommended form in Node, mirroring `Microphone.open`. The synchronous
    * `new File(path)` remains available for scripts.
    *
@@ -1005,10 +1133,10 @@ class File extends Readable {
   }
 
   /**
-   * The source's own rate, taken from the WAV header or from the `inputRate`
-   * passed to `File.buffer`. Differs from `sampleRate` when the source was
-   * resampled. Readable for the life of the File, including after the source
-   * is consumed or closed.
+   * The source's own rate, taken from the file's header or from the
+   * `inputRate` passed to `File.buffer`. Differs from `sampleRate` when the
+   * source was resampled. Readable for the life of the File, including after
+   * the source is consumed or closed.
    * @returns {number}
    */
   get inputRate() {
@@ -1063,6 +1191,77 @@ class File extends Readable {
     return this.analyze();
   }
 
+  /**
+   * Validate the save options and resolve them into the native options
+   * object. Shared by `File.save` and `AudioWriter`, so the two spellings of
+   * a write accept and reject identically.
+   * @internal
+   * @param {import('./decibri').SaveOptions} options
+   */
+  static _prepareSaveOptions(options) {
+    const format = options.format;
+    if (format !== undefined && format !== 'wav' && format !== 'aiff' && format !== 'flac') {
+      throw new TypeError(
+        `Invalid format value: ${JSON.stringify(format)}. Expected 'wav', 'aiff', or 'flac'.`
+      );
+    }
+    const compression = options.compression;
+    if (compression !== undefined) {
+      if (typeof compression !== 'number' || Number.isNaN(compression)) {
+        throw new TypeError('compression must be a number');
+      }
+      if (compression < 0 || compression > 8) {
+        throw new RangeError('flac compression level must be between 0 and 8');
+      }
+    }
+    return { format, compression };
+  }
+
+  /**
+   * Write the conditioned recording to disk, off the event loop. Runs the
+   * recording once through the same conditioning pass iteration delivers,
+   * whole, and writes it as 16-bit PCM mono at `sampleRate`. Consumes the
+   * source: a save is a single pass, separate from iteration and analysis.
+   *
+   * The container comes from the path's extension (`.wav`, `.aiff`, `.aif`,
+   * `.aifc` or `.flac`), or from `options.format`: decibri reads a file by
+   * its content and writes one by its name. An extension it does not
+   * recognise rejects rather than defaulting. `options.compression` sets the
+   * FLAC compression level (0-8, default 5); it applies only to FLAC.
+   *
+   * Resolves to a `SaveReport`: `clippedSamples` counts finite samples
+   * outside full scale clamped to `[-1.0, 1.0]` (AGC or AEC without a
+   * limiter can overshoot, and 16-bit PCM cannot hold it), and
+   * `nonFiniteSamples` counts NaN samples written as silence and infinite
+   * samples written as full scale.
+   *
+   * 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.
+   *
+   * @param {string} filePath
+   * @param {import('./decibri').SaveOptions} [options]
+   * @returns {Promise<import('./decibri').SaveReport>}
+   */
+  async save(filePath, options = {}) {
+    // 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 (typeof filePath !== 'string') {
+      throw new TypeError('path must be a string');
+    }
+    const nativeOptions = File._prepareSaveOptions(options);
+    try {
+      return await this._native.save(filePath, nativeOptions);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
   /**
    * Release the source. Idempotent; a closed File reads as ended.
    */
@@ -1071,10 +1270,131 @@ class File extends Readable {
   }
 }
 
+// ─── AudioWriter (Writable): file sink ───────────────────────────────────────
+
+class AudioWriter extends Writable {
+  /**
+   * A file sink for PCM audio: the Writable to pair with decibri's Readable
+   * sources, and with any other stream of PCM bytes (a TTS engine, a decoded
+   * network stream). Collects the whole stream, then writes it as one audio
+   * file when the stream finishes, exactly as `File.save` writes: the same
+   * containers from the same extension rule, the same 16-bit PCM encoding,
+   * the same clamp and non-finite handling, the same bytes.
+   *
+   * Chunks are raw PCM bytes in `dtype` ('int16' little-endian by default,
+   * matching what a `File` or `Microphone` emits; 'float32' for raw f32
+   * bytes). Audio is written mono: `channels` may only be 1. `sampleRate` is
+   * required, because raw audio carries no header to read one from.
+   *
+   * The file is written when the stream finishes ('finish' fires after the
+   * file is on disk), and `report` then carries the `SaveReport` the write
+   * produced. A failure destroys the stream with the error.
+   *
+   * @param {string} filePath Path whose extension names the container,
+   *   unless `format` overrides it.
+   * @param {import('./decibri').AudioWriterOptions} options
+   */
+  constructor(filePath, options = {}) {
+    super({ highWaterMark: options.highWaterMark });
+    if (typeof filePath !== 'string') {
+      throw new TypeError('path must be a string');
+    }
+    const sampleRate = options.sampleRate;
+    if (typeof sampleRate !== 'number' || Number.isNaN(sampleRate)) {
+      throw new TypeError('sampleRate is required for AudioWriter (raw audio carries no header)');
+    }
+    if (sampleRate < 1000 || sampleRate > 384000) {
+      throw new RangeError('sample rate must be between 1000 and 384000');
+    }
+    const channels = options.channels;
+    if (channels !== undefined && channels !== 1) {
+      throw new RangeError('multichannel write is not supported; channels must be 1 (mono)');
+    }
+    const dtype = options.dtype ?? 'int16';
+    if (dtype !== 'int16' && dtype !== 'float32') {
+      throw new TypeError("dtype must be 'int16' or 'float32'");
+    }
+    // Validated now, so a bad option is a construction-time throw rather
+    // than a deferred 'error' event after the audio has been streamed.
+    this._saveOptions = File._prepareSaveOptions(options);
+    this._filePath = filePath;
+    this._sampleRate = sampleRate;
+    this._dtype = dtype;
+    this._chunks = [];
+    this._report = null;
+  }
+
+  /**
+   * The `SaveReport` of the completed write: `clippedSamples` and
+   * `nonFiniteSamples`, exactly as `File.save` resolves. `null` until
+   * 'finish' has fired.
+   * @returns {import('./decibri').SaveReport | null}
+   */
+  get report() {
+    return this._report;
+  }
+
+  /** @internal */
+  _write(chunk, encoding, callback) {
+    this._chunks.push(chunk);
+    callback();
+  }
+
+  /** @internal */
+  _final(callback) {
+    const bytes = Buffer.concat(this._chunks);
+    this._chunks = [];
+    const bytesPerSample = this._dtype === 'int16' ? 2 : 4;
+    if (bytes.length % bytesPerSample !== 0) {
+      callback(
+        new RangeError(
+          `audio bytes do not divide into whole ${this._dtype} samples; ` +
+            `${bytes.length % bytesPerSample} byte(s) over`
+        )
+      );
+      return;
+    }
+    const samples = new Float32Array(bytes.length / bytesPerSample);
+    if (this._dtype === 'int16') {
+      // The inverse of the int16 delivery encoding: value / 32768, so bytes
+      // that came from a decibri source re-quantise to the identical file.
+      for (let i = 0; i < samples.length; i++) {
+        samples[i] = bytes.readInt16LE(i * 2) / 32768;
+      }
+    } else {
+      for (let i = 0; i < samples.length; i++) {
+        samples[i] = bytes.readFloatLE(i * 4);
+      }
+    }
+    // The write is File.save on a source at the writer's own rate: the same
+    // encode path, so the two spellings produce the same bytes.
+    let file;
+    try {
+      file = File.buffer(samples, {
+        inputRate: this._sampleRate,
+        sampleRate: this._sampleRate,
+      });
+    } catch (err) {
+      callback(err);
+      return;
+    }
+    file
+      .save(this._filePath, this._saveOptions)
+      .then((report) => {
+        this._report = report;
+        callback();
+      })
+      .catch((err) => {
+        callback(err);
+      });
+  }
+}
+
 module.exports = {
   Microphone,
   Speaker,
   File,
+  AudioWriter,
   inputDevices,
   outputDevices,
   version,

package/src/errors.js

@@ -80,8 +80,12 @@ const RANGE_PREFIXES = [
   'frames per buffer must be between',
   'agc target level must be between',
   'limiter ceiling must be between',
+  'flac compression level 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 +93,8 @@ const RANGE_PREFIXES = [
 const TYPE_PREFIXES = [
   "dtype must be 'int16' or 'float32'",
   "format must be 'int16' or 'float32'",
+  'aec suppression must be',
+  'Invalid format value:',
 ];
 
 const DEVICE_CODES = [
@@ -126,8 +132,12 @@ 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'],
+  ['Failed to write audio file', 'FILE_WRITE_FAILED'],
+  ['unsupported audio format:', 'AUDIO_FORMAT_UNSUPPORTED'],
+  ['malformed audio file:', 'AUDIO_FILE_MALFORMED'],
+  ['truncated audio file:', 'AUDIO_FILE_TRUNCATED'],
   ['ONNX Runtime was initialized in pid', 'FORK_AFTER_ORT_INIT'],
   ['ONNX backend error from', 'ONNX_BACKEND_FAILED'],
   // Authored in the napi layer (bindings/node/src/lib.rs), not in