decibri 5.2.5 → 5.4.0

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[];
 
@@ -280,7 +423,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`.
@@ -408,6 +551,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
@@ -416,7 +599,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
@@ -443,15 +626,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>;
@@ -479,7 +663,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.
    */
@@ -503,6 +687,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;
 
@@ -523,6 +727,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;