decibri 5.3.0 → 5.5.0

package/src/decibri-output.js

@@ -67,9 +67,13 @@ class Speaker extends Writable {
       throw new RangeError('sample rate must be between 1000 and 384000');
     }
 
+    // Bounded below only. How many output channels can be carried is the
+    // device's answer, so any count above zero is passed through and a device
+    // that refuses it throws a DecibriError with code
+    // 'SPEAKER_CHANNELS_UNSUPPORTED' naming the count the device reports.
     const channels = options.channels ?? 1;
-    if (channels < 1 || channels > 32) {
-      throw new RangeError('channels must be between 1 and 32');
+    if (channels < 1) {
+      throw new RangeError('channels must be at least 1');
     }
 
     const dtype = options.dtype ?? 'int16';

package/src/decibri.d.ts

@@ -42,7 +42,7 @@ export interface VersionInfo {
 export interface VadOptions {
   /**
    * Which detector to run.
-   * - `'silero'`: Silero VAD v5 ML model (more accurate, ~1ms inference)
+   * - `'silero'`: Silero VAD v6.2 ML model (more accurate, ~1ms inference)
    * - `'energy'`: RMS energy threshold (lightweight, no model)
    */
   model: 'silero' | 'energy';
@@ -105,6 +105,32 @@ export interface AecOptions {
    * @range 1000 to 384000
    */
   referenceSampleRate?: number;
+
+  /**
+   * Number of channels in the far-end reference pushed through
+   * `pushAecReference`, frame-interleaved. When it names a count above 1,
+   * decibri averages each frame to one mono sample before the canceller sees
+   * it: a multichannel reference pushed without declaring the count cancels
+   * nothing and reports no error, so the collapse is decibri's rather than
+   * the caller's.
+   *
+   * The declared count must match the buffer actually pushed. The reference
+   * arrives as flat PCM whose true channel count is not recoverable from its
+   * length, so a mismatch is not detected and raises no error: the frames
+   * are misread, nothing is cancelled, and the observable signature is
+   * `aecMetrics().delaySamples` staying `null` while the canceller reports
+   * no fault.
+   *
+   * The canceller itself reads one mono reference. Against playback through
+   * more than one loudspeaker that is a cancellation ceiling: the echo
+   * reaching the microphone is the sum of different room responses driven by
+   * different signals, and a single-reference canceller models one response
+   * applied to their average, so a placement where those paths differ leaves
+   * a residual that no amount of adaptation removes.
+   * @default 1 (mono)
+   * @range at least 1; no upper bound
+   */
+  referenceChannels?: number;
 }
 
 /**
@@ -211,7 +237,7 @@ export interface MicrophoneOptions extends ReadableOptions {
   /**
    * Voice activity detection. One of:
    * - `false`: disabled (default)
-   * - `'silero'`: Silero VAD v5 ML model (more accurate, ~1ms inference)
+   * - `'silero'`: Silero VAD v6.2 ML model (more accurate, ~1ms inference)
    * - `'energy'`: RMS energy threshold (lightweight)
    * - a `VadOptions` config object `{ model, threshold?, holdoffMs? }` to tune
    *   the threshold and holdoff for the chosen model
@@ -371,8 +397,14 @@ export declare class Microphone extends Readable {
    * 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).
+   * `DataView` of PCM bytes in this microphone's `dtype`), at the declared
+   * `referenceSampleRate` (the capture rate when unset), interleaved at the
+   * declared `referenceChannels` (mono when unset). With `referenceChannels`
+   * above 1, each frame is averaged to one mono sample before the canceller
+   * sees it. The declared count must match this buffer's actual
+   * interleaving: a mismatch is not detected and raises no error, and shows
+   * up only as `aecMetrics().delaySamples` staying `null` with no fault
+   * reported.
    *
    * Never blocks and never throws on a full queue: samples that do not fit
    * are discarded and counted by `aecMetrics().referenceDropped`. Silence
@@ -423,7 +455,7 @@ export declare class Microphone extends Readable {
 export interface FileOptions extends ReadableOptions {
   /**
    * Target output rate in Hz: the rate every delivered chunk carries. The
-   * source's input rate (from the WAV header, or `inputRate` for
+   * source's input rate (from the file's header, or `inputRate` for
    * `File.buffer`) is resampled to this rate, so a 44.1 kHz recording comes
    * out at 16 kHz unless you set `sampleRate`. The same meaning the option
    * has on `Microphone`.
@@ -551,6 +583,46 @@ export interface VadReport {
   segments: Segment[];
 }
 
+/** Options for `File.save` (also accepted by `AudioWriter`). */
+export interface SaveOptions {
+  /**
+   * The container format to write. When not given it comes from the path's
+   * extension: `.wav`, `.aiff`, `.aif`, `.aifc` or `.flac`. decibri reads a
+   * file by its content and writes one by its name; an extension it does not
+   * recognise is an error, never a silent default.
+   */
+  format?: 'wav' | 'aiff' | 'flac';
+
+  /**
+   * FLAC compression level. Higher levels search harder for a smaller file;
+   * every level decodes to identical audio. Applies only to FLAC; ignored
+   * for WAV and AIFF.
+   * @default 5
+   * @range 0 to 8
+   */
+  compression?: number;
+}
+
+/**
+ * What a save did to the samples on their way into the file, resolved by
+ * `File.save` and carried by `AudioWriter.report`.
+ */
+export interface SaveReport {
+  /**
+   * Finite samples outside full scale, clamped to [-1.0, 1.0]. Conditioned
+   * audio can exceed full scale (AGC or AEC without a limiter), and 16-bit
+   * PCM cannot hold that, so the overshoot clips and this count says how
+   * much. The count is a statement about integer encodings: a float encoding
+   * would preserve the overshoot instead, and would report zero.
+   */
+  clippedSamples: number;
+  /**
+   * Non-finite samples replaced before writing: NaN with silence, an
+   * infinity with full scale. The same replacement on every format.
+   */
+  nonFiniteSamples: number;
+}
+
 /**
  * Offline audio source: conditions a recording or in-memory samples through
  * the same chain as the live `Microphone`, delivered as a finite Readable
@@ -559,7 +631,7 @@ export interface VadReport {
  * analyze the whole recording for speech with `analyze()` / `analyse()`,
  * which a live stream cannot do.
  *
- * Construction: `new File(path)` reads the WAV synchronously (fine for a
+ * Construction: `new File(path)` reads the file synchronously (fine for a
  * script; it blocks the event loop on disk I/O), `await File.open(path)` reads
  * it off the event loop (the recommended form, mirroring `Microphone.open`),
  * and `File.buffer(samples, { inputRate })` wraps a `Float32Array` of samples
@@ -586,15 +658,16 @@ export interface VadReport {
  */
 export declare class File extends Readable {
   /**
-   * Open a WAV file synchronously (blocks on disk I/O; prefer `File.open`
-   * in servers). Supports 16-bit PCM and 32-bit float WAV files; the input
-   * rate and channel count come from the header.
+   * Open an audio file synchronously (blocks on disk I/O; prefer `File.open`
+   * in servers). Reads WAV, AIFF, AIFF-C and FLAC, identified from the
+   * file's own bytes rather than its extension; the input rate and channel
+   * count come from the header.
    */
   constructor(path: string, options?: FileOptions);
 
   /**
-   * 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, mirroring `Microphone.open`.
    */
   static open(path: string, options?: FileOptions): Promise<File>;
@@ -622,7 +695,7 @@ export declare class File extends Readable {
   readonly sampleRate: number;
 
   /**
-   * The source's own rate, taken from the WAV header or from the
+   * 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.
    */
@@ -646,6 +719,26 @@ export declare class File extends Readable {
   /** The same whole-recording analysis under the international spelling. */
   analyse(): Promise<VadReport>;
 
+  /**
+   * 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`. 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. Consumes the source (a `File` is a single
+   * pass).
+   *
+   * Resolves to a `SaveReport`: how many samples were clamped to full scale
+   * and how many non-finite samples were replaced (NaN as silence, an
+   * infinity 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.
+   */
+  save(path: string, options?: SaveOptions): Promise<SaveReport>;
+
   /** Release the source. Idempotent; a closed File reads as ended. */
   close(): void;
 
@@ -666,6 +759,61 @@ export declare class File extends Readable {
   once(event: string | symbol, listener: (...args: any[]) => void): this;
 }
 
+/** Constructor options for `AudioWriter`: the save options plus the stream's own description. */
+export interface AudioWriterOptions extends SaveOptions, WritableOptions {
+  /**
+   * The rate of the incoming samples in Hz, written into the file's header.
+   * Required: raw audio carries no header to read a rate from.
+   * @range 1000 to 384000
+   */
+  sampleRate: number;
+
+  /**
+   * Number of channels. Audio is written mono; only `1` is accepted.
+   * @default 1
+   */
+  channels?: 1;
+
+  /**
+   * Sample encoding of the incoming bytes.
+   * - `'int16'`: 16-bit signed integer, little-endian, what a `File` or
+   *   `Microphone` emits by default
+   * - `'float32'`: 32-bit IEEE 754 float, little-endian
+   * @default 'int16'
+   */
+  dtype?: 'int16' | 'float32';
+}
+
+/**
+ * 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.
+ *
+ * `'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.
+ *
+ * @example
+ * const { pipeline } = require('node:stream/promises');
+ * const { File, AudioWriter } = require('decibri');
+ * await pipeline(
+ *   new File('noisy.wav', { denoise: 'fastenhancer-t' }),
+ *   new AudioWriter('clean.flac', { sampleRate: 16000 }),
+ * );
+ */
+export declare class AudioWriter extends Writable {
+  constructor(path: string, options: AudioWriterOptions);
+
+  /**
+   * The `SaveReport` of the completed write, exactly as `File.save` resolves
+   * it. `null` until `'finish'` has fired.
+   */
+  readonly report: SaveReport | null;
+}
+
 export interface SpeakerInfo {
   /** Device index (pass to constructor as `device`). */
   index: number;
@@ -694,9 +842,11 @@ export interface SpeakerOptions extends WritableOptions {
   sampleRate?: number;
 
   /**
-   * Number of output channels.
+   * Number of output channels. The maximum is the device's: a count the device
+   * cannot serve throws a `DecibriError` with code
+   * `'SPEAKER_CHANNELS_UNSUPPORTED'` naming the count the device reports.
    * @default 1
-   * @range 1–32
+   * @range 1 or more
    */
   channels?: number;
 

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');
@@ -151,7 +151,7 @@ class Microphone extends Readable {
     // additive. The `channels` option is kept for that forward compatibility.
     const channels = options.channels ?? 1;
     if (channels < 1) {
-      throw new RangeError('channels must be between 1 and 32');
+      throw new RangeError('channels must be at least 1');
     }
     if (channels > 1) {
       throw new RangeError('multichannel capture is not supported; channels must be 1 (mono)');
@@ -345,8 +345,8 @@ class Microphone extends Readable {
     // ── 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
+    // { model, tailMs, suppression, referenceSampleRate, referenceChannels }
+    // 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
@@ -360,11 +360,12 @@ class Microphone extends Readable {
     let aecTailMs;
     let aecSuppression;
     let aecReferenceSampleRate;
+    let aecReferenceChannels;
     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;
+        const { model, tailMs, suppression, referenceSampleRate, referenceChannels } = aec;
         if (typeof model !== 'string') {
           throw new TypeError(
             `Invalid aec model: ${JSON.stringify(model)}. Expected a model name string such as 'tau'.`
@@ -397,9 +398,18 @@ class Microphone extends Readable {
           }
           aecReferenceSampleRate = referenceSampleRate;
         }
+        if (referenceChannels !== undefined) {
+          if (typeof referenceChannels !== 'number' || Number.isNaN(referenceChannels)) {
+            throw new TypeError('aec referenceChannels must be a number');
+          }
+          if (referenceChannels < 1) {
+            throw new RangeError('aec referenceChannels must be at least 1');
+          }
+          aecReferenceChannels = referenceChannels;
+        }
       } 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 }.`
+          `Invalid aec value: ${JSON.stringify(aec)}. Expected a model name such as 'tau', or a config object { model, tailMs, suppression, referenceSampleRate, referenceChannels }.`
         );
       }
     }
@@ -443,6 +453,7 @@ class Microphone extends Readable {
         aecTailMs,
         aecSuppression,
         aecReferenceSampleRate,
+        aecReferenceChannels,
       },
     };
   }
@@ -605,8 +616,15 @@ class Microphone extends Readable {
    * 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).
+   * `DataView` of PCM bytes in this microphone's `dtype`), at the declared
+   * `referenceSampleRate` (the capture rate when unset), interleaved at the
+   * declared `referenceChannels` (mono when unset). With `referenceChannels`
+   * above 1, each frame is averaged to one mono sample before the canceller
+   * sees it; a multichannel reference pushed without declaring the count
+   * cancels nothing and reports no error. The declared count must match this
+   * buffer's actual interleaving: a mismatch is not detected and raises no
+   * error, and shows up only as `aecMetrics().delaySamples` staying `null`
+   * with no fault reported.
    *
    * Never blocks and never throws on a full queue: samples that do not fit
    * are discarded and counted by `aecMetrics().referenceDropped`, and the
@@ -714,19 +732,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,
@@ -932,8 +951,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.
    *
@@ -1132,10 +1151,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() {
@@ -1190,6 +1209,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.
    */
@@ -1198,10 +1288,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

@@ -75,13 +75,15 @@ class OrtPathError extends OrtError {
 // the core ever sees it).
 const RANGE_PREFIXES = [
   'sample rate must be between',
-  'channels must be between',
+  'channels must be at least',
   'multichannel capture is not supported',
   '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',
+  'aec referenceChannels must be at',
   'Silero VAD only supports',
   'VAD threshold must be between',
   'echo cancellation only supports',
@@ -93,6 +95,7 @@ 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 = [
@@ -123,6 +126,7 @@ const BASE_CODES = [
   ['audio stream is already running', 'ALREADY_RUNNING'],
   ['Failed to open audio stream', 'STREAM_OPEN_FAILED'],
   ['Failed to start audio stream', 'STREAM_START_FAILED'],
+  ['the output device does not support', 'SPEAKER_CHANNELS_UNSUPPORTED'],
   ['Microphone permission denied.', 'PERMISSION_DENIED'],
   ['Microphone stream is closed', 'MICROPHONE_STREAM_CLOSED'],
   ['Speaker stream is closed', 'SPEAKER_STREAM_CLOSED'],
@@ -132,7 +136,10 @@ const BASE_CODES = [
   ['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