decibri 5.5.0 → 5.6.0

package/src/browser/index.d.ts

@@ -35,6 +35,16 @@ export interface VadOptions {
    * @default 300
    */
   holdoffMs?: number;
+  /**
+   * The 0-based DELIVERED channel the detector reads: the position within
+   * the delivered interleaved frames, after any `channelMap` is applied (a
+   * `channelMap` names device channels; `source` names the delivered
+   * position). Must be below the delivered channel count, which is its only
+   * ceiling; no fixed maximum exists. Affects only the detector score; the
+   * delivered audio is untouched.
+   * @default the frame average of every delivered channel
+   */
+  source?: number;
 }
 
 /** Constructor options for the browser `Microphone` class. */
@@ -47,17 +57,54 @@ export interface MicrophoneOptions {
   sampleRate?: number;
 
   /**
-   * Number of input channels. Mono only: the only accepted value is `1`, and a
-   * value greater than `1` throws a `RangeError` (multichannel capture is not
-   * supported) rather than being silently downmixed. The option is kept for
-   * forward compatibility: a future release may accept a value greater than `1`
-   * by delivering true interleaved multichannel.
+   * Number of channels the stream delivers, interleaved frame by frame in the
+   * emitted chunks. Bounded below at `1` (the default); bounded above by the
+   * granted track alone, which reports its own count when the stream starts.
+   * No fixed maximum exists.
+   *
+   * The capture itself asks the browser for every channel it will grant (the
+   * Web Audio specification's 32-channel floor, with ideal semantics), and
+   * decibri derives the delivered channels from the grant. Without a
+   * `channelMap`: `1` delivers the documented average of every granted
+   * channel; a count equal to the granted count delivers every granted
+   * channel in granted order; a count above the grant fails `start()` with
+   * an `Error` reading `the input device does not support N delivered
+   * channels; it reports M`; and a count above `1` and below the grant fails
+   * it with `a channel map is required to deliver N of the device's M input
+   * channels`, because which channels it means has no single answer, so
+   * `channelMap` names them. Where the browser does not report the granted
+   * channel count, the same `Error` is emitted on `'error'` and the capture
+   * stops as soon as the audio graph reports its true channel count.
    * @default 1
    */
   channels?: number;
 
+  /**
+   * Optional list of 0-based device channel indices selecting which granted
+   * channels feed the delivered channels: delivered channel `j` carries device
+   * channel `channelMap[j]`. The length must equal `channels`. Entries may
+   * repeat and may appear in any order, so a map both selects and permutes,
+   * and may name more delivered channels than the grant carries. Absent
+   * derives the delivered channels from `channels` as documented there.
+   *
+   * The same shape as the Node entry's `channelMap`, validated with the same
+   * classes and messages. Entries are checked against the granted track's own
+   * report: where the browser reports the granted channel count, `start()`
+   * rejects with an `Error` whose message names the entry and the granted
+   * count; where it does not, the same `Error` is emitted on `'error'` and
+   * the capture stops as soon as the audio graph reports its true channel
+   * count. The granted report is the only ceiling; no fixed maximum exists.
+   *
+   * A browser typically grants a single processed channel while
+   * `echoCancellation` or `noiseSuppression` is enabled, so a multichannel
+   * grant generally requires both disabled.
+   * @default undefined (the derivation `channels` documents)
+   */
+  channelMap?: number[];
+
   /**
    * Frames per audio chunk. Controls chunk size and delivery interval.
+   * A chunk holds this many frames of the delivered channel count.
    * @default 1600
    * @range 64–65536
    */
@@ -81,8 +128,9 @@ export interface MicrophoneOptions {
    * Voice activity detection. One of:
    * - `false`: disabled (default)
    * - `'energy'`: RMS energy threshold
-   * - a `VadOptions` config object `{ model: 'energy', threshold?, holdoffMs? }`
-   *   to tune the threshold and holdoff
+   * - a `VadOptions` config object
+   *   `{ model: 'energy', threshold?, holdoffMs?, source? }` to tune the
+   *   threshold, holdoff, and detector source
    *
    * The browser runs energy VAD only; Silero is Node-only. The string shorthand
    * uses a 0.01 threshold and a 300 ms holdoff; pass a `VadOptions` object to
@@ -147,6 +195,9 @@ export declare class Microphone {
   /**
    * Most recent VAD score: the normalized RMS of the last chunk in `'energy'`
    * mode, or 0 when VAD is disabled or before the first chunk is processed.
+   * A chunk carrying more than one channel is collapsed to the average of its
+   * channels before the RMS, or read at the one delivered channel the vad
+   * `source` names when it is set, so the score reflects one channel's level.
    */
   readonly vadScore: number;
 

package/src/browser/worklet-inline.js

@@ -7,8 +7,8 @@
  * The readable version is in worklet-processor.js (documentation/reference only).
  * If worklet-processor.js logic changes, this string MUST be regenerated.
  *
- * Generated from decibri-web v0.1.1 build output. Logic identical to worklet-processor.js.
+ * Logic identical to worklet-processor.js.
  */
-const WORKLET_SOURCE = "var u=class extends AudioWorkletProcessor{constructor(r){super();let e=r.processorOptions;this.framesPerBuffer=e.framesPerBuffer,this.format=e.format,this.ratio=e.nativeSampleRate/e.targetSampleRate,this.needsResample=e.nativeSampleRate!==e.targetSampleRate,this.position=0,this.buffer=new Float32Array(this.framesPerBuffer),this.bufferIndex=0}process(r,e,s){let t=r[0]?.[0];if(!t||t.length===0)return!0;let f;this.needsResample?f=this.resample(t):f=t;let a=0;for(;a<f.length;){let i=this.framesPerBuffer-this.bufferIndex,o=f.length-a,n=Math.min(i,o);this.buffer.set(f.subarray(a,a+n),this.bufferIndex),this.bufferIndex+=n,a+=n,this.bufferIndex>=this.framesPerBuffer&&this.flush()}return!0}resample(r){let e=r.length,s=0,t=this.position;for(;t<e-1;)s++,t+=this.ratio;let f=new Float32Array(s);t=this.position;for(let a=0;a<s;a++){let i=Math.floor(t),o=t-i;f[a]=r[i]*(1-o)+r[i+1]*o,t+=this.ratio}return this.position=Math.max(0,t-e),f}flush(){let r;if(this.format===\"int16\"){let e=new Int16Array(this.framesPerBuffer);for(let s=0;s<this.framesPerBuffer;s++)e[s]=Math.max(-32768,Math.min(32767,Math.round(this.buffer[s]*32768)));r=e.buffer}else r=this.buffer.slice(0,this.framesPerBuffer).buffer;this.port.postMessage(r,[r]),this.buffer=new Float32Array(this.framesPerBuffer),this.bufferIndex=0}};registerProcessor(\"decibri-processor\",u);\n";
+const WORKLET_SOURCE = "var e=class extends AudioWorkletProcessor{constructor(e){super();let t=e.processorOptions;this.framesPerBuffer=t.framesPerBuffer,this.format=t.format,this.ratio=t.nativeSampleRate/t.targetSampleRate,this.needsResample=t.nativeSampleRate!==t.targetSampleRate,this.channelMap=t.channelMap??null,this.channels=this.channelMap?this.channelMap.length:t.channels??1,this.channelError=!1,this.position=0,this.samplesPerChunk=this.framesPerBuffer*this.channels,this.buffer=new Float32Array(this.samplesPerChunk),this.bufferIndex=0}process(e,t,n){let r=e[0];if(!r||r.length===0||!r[0]||r[0].length===0)return!0;if(this.channelError)return!1;let i=r.length,a;if(this.channelMap){for(let e=0;e<this.channelMap.length;e++)if(this.channelMap[e]>=i)return this.refuse(`the channel map names device channel `+this.channelMap[e]+`; the device reports `+i+` input channels`);a=[];for(let e=0;e<this.channelMap.length;e++)a.push(r[this.channelMap[e]])}else if(this.channels===1)if(i===1)a=[r[0]];else{let e=r[0].length,t=new Float32Array(e);for(let n=0;n<e;n++){let e=0;for(let t=0;t<i;t++)e=Math.fround(e+r[t][n]);t[n]=e/i}a=[t]}else if(this.channels===i){a=[];for(let e=0;e<i;e++)a.push(r[e])}else if(this.channels>i)return this.refuse(`the input device does not support `+this.channels+` delivered channels; it reports `+i);else return this.refuse(`a channel map is required to deliver `+this.channels+` of the device's `+i+` input channels`);this.needsResample&&(a=this.resample(a));let o=a[0].length;for(let e=0;e<o;e++){for(let t=0;t<this.channels;t++)this.buffer[this.bufferIndex++]=a[t][e];this.bufferIndex>=this.samplesPerChunk&&this.flush()}return!0}refuse(e){return this.channelError=!0,this.port.postMessage({type:`error`,message:e}),!1}resample(e){let t=e[0].length,n=0,r=this.position;for(;r<t-1;)n++,r+=this.ratio;let i=e.map(()=>new Float32Array(n));r=this.position;for(let t=0;t<n;t++){let n=Math.floor(r),a=r-n;for(let r=0;r<e.length;r++)i[r][t]=e[r][n]*(1-a)+e[r][n+1]*a;r+=this.ratio}return this.position=Math.max(0,r-t),i}flush(){let e;if(this.format===`int16`){let t=new Int16Array(this.samplesPerChunk);for(let e=0;e<this.samplesPerChunk;e++)t[e]=Math.max(-32768,Math.min(32767,Math.round(this.buffer[e]*32768)));e=t.buffer}else e=this.buffer.slice(0,this.samplesPerChunk).buffer;this.port.postMessage(e,[e]),this.buffer=new Float32Array(this.samplesPerChunk),this.bufferIndex=0}};registerProcessor(`decibri-processor`,e);";
 
 module.exports = { WORKLET_SOURCE };

package/src/browser/worklet-processor.js

@@ -6,9 +6,11 @@
  * If you change logic here, you MUST regenerate worklet-inline.js.
  *
  * Runs in a dedicated audio thread. Receives Float32 samples at the
- * browser's native sample rate, resamples to the target rate via linear
- * interpolation, optionally converts to Int16, and posts chunks to the
- * main thread.
+ * browser's native sample rate, derives the delivered channels from the
+ * granted ones (the average of every channel, every channel in granted
+ * order, or the channels the map selects), resamples each channel to the
+ * target rate via linear interpolation, interleaves frame by frame,
+ * optionally converts to Int16, and posts chunks to the main thread.
  *
  * This file cannot import other modules (AudioWorklet restriction).
  *
@@ -23,35 +25,102 @@ class DecibriProcessor extends AudioWorkletProcessor {
     this.format = opts.format;
     this.ratio = opts.nativeSampleRate / opts.targetSampleRate;
     this.needsResample = opts.nativeSampleRate !== opts.targetSampleRate;
+    // Optional list of 0-based channel indices into the granted track's
+    // channels; delivered channel j carries granted channel channelMap[j].
+    // null derives the delivered channels from the count alone: 1 delivers
+    // the average of every granted channel, the granted count delivers every
+    // granted channel in granted order, and any other count is refused in
+    // process(). Where the browser reports the granted channel count, the
+    // main thread checked all of this before this worklet was built; the
+    // per-block guard in process() is the authority where it does not.
+    this.channelMap = opts.channelMap ?? null;
+    // The delivered channel count. A map carries one entry per delivered
+    // channel, so its length is the count when one is present.
+    this.channels = this.channelMap ? this.channelMap.length : (opts.channels ?? 1);
+    this.channelError = false;
     this.position = 0;
-    this.buffer = new Float32Array(this.framesPerBuffer);
+    // The accumulation buffer holds framesPerBuffer frames of the delivered
+    // count, interleaved frame by frame; bufferIndex counts samples. Chunks
+    // are flushed at whole frames only.
+    this.samplesPerChunk = this.framesPerBuffer * this.channels;
+    this.buffer = new Float32Array(this.samplesPerChunk);
     this.bufferIndex = 0;
   }
 
   process(inputs, _outputs, _parameters) {
-    const input = inputs[0]?.[0];
-    if (!input || input.length === 0) return true;
-
-    let samples;
-
-    if (this.needsResample) {
-      samples = this.resample(input);
+    const input = inputs[0];
+    if (!input || input.length === 0 || !input[0] || input[0].length === 0) return true;
+    if (this.channelError) return false;
+
+    const granted = input.length;
+    // The delivered channels, planar: one Float32Array per delivered
+    // channel, equal lengths. Gathered here, resampled per channel in
+    // lockstep, interleaved at accumulation.
+    let planar;
+
+    if (this.channelMap) {
+      // The granted track's channel count is the only ceiling. A map entry
+      // the block cannot serve is reported once and stops the processor; it
+      // is never silently substituted.
+      for (let j = 0; j < this.channelMap.length; j++) {
+        if (this.channelMap[j] >= granted) {
+          return this.refuse('the channel map names device channel ' + this.channelMap[j] +
+            '; the device reports ' + granted + ' input channels');
+        }
+      }
+      // Delivered channel j is granted channel channelMap[j], in map order.
+      // Entries may repeat and may appear in any order, so a map both
+      // selects and permutes.
+      planar = [];
+      for (let j = 0; j < this.channelMap.length; j++) {
+        planar.push(input[this.channelMap[j]]);
+      }
+    } else if (this.channels === 1) {
+      if (granted === 1) {
+        planar = [input[0]];
+      } else {
+        // The documented average of every granted channel: each frame's
+        // arithmetic mean, accumulated at single precision (Math.fround per
+        // step) and stored as f32, matching the engine's average sample for
+        // sample.
+        const frames = input[0].length;
+        const mono = new Float32Array(frames);
+        for (let i = 0; i < frames; i++) {
+          let sum = 0;
+          for (let c = 0; c < granted; c++) {
+            sum = Math.fround(sum + input[c][i]);
+          }
+          mono[i] = sum / granted;
+        }
+        planar = [mono];
+      }
+    } else if (this.channels === granted) {
+      // Every granted channel, in granted order: the unmapped identity.
+      planar = [];
+      for (let c = 0; c < granted; c++) planar.push(input[c]);
+    } else if (this.channels > granted) {
+      return this.refuse('the input device does not support ' + this.channels +
+        ' delivered channels; it reports ' + granted);
     } else {
-      samples = input;
+      // An unmapped strict subset above one: which of the granted channels
+      // it means has no single answer, so the map has to name them.
+      return this.refuse('a channel map is required to deliver ' + this.channels +
+        " of the device's " + granted + ' input channels');
     }
 
-    // Accumulate resampled frames into the buffer
-    let offset = 0;
-    while (offset < samples.length) {
-      const remaining = this.framesPerBuffer - this.bufferIndex;
-      const available = samples.length - offset;
-      const toCopy = Math.min(remaining, available);
-
-      this.buffer.set(samples.subarray(offset, offset + toCopy), this.bufferIndex);
-      this.bufferIndex += toCopy;
-      offset += toCopy;
+    if (this.needsResample) {
+      planar = this.resample(planar);
+    }
 
-      if (this.bufferIndex >= this.framesPerBuffer) {
+    // Interleave the planar channels into the accumulation buffer frame by
+    // frame, flushing at whole chunks, so every posted chunk is a whole
+    // number of frames.
+    const frames = planar[0].length;
+    for (let i = 0; i < frames; i++) {
+      for (let c = 0; c < this.channels; c++) {
+        this.buffer[this.bufferIndex++] = planar[c][i];
+      }
+      if (this.bufferIndex >= this.samplesPerChunk) {
         this.flush();
       }
     }
@@ -59,10 +128,23 @@ class DecibriProcessor extends AudioWorkletProcessor {
     return true;
   }
 
-  resample(input) {
-    const inputLength = input.length;
+  /**
+   * Report a channel configuration no block can serve, once, with the
+   * engine's message for the same condition, and stop the processor: the
+   * failure is terminal and never silently substituted.
+   */
+  refuse(message) {
+    this.channelError = true;
+    this.port.postMessage({ type: 'error', message });
+    return false;
+  }
+
+  resample(planar) {
+    const inputLength = planar[0].length;
 
-    // Calculate how many output samples we can produce
+    // Calculate how many output frames we can produce. One position shared
+    // by every channel: the channels advance in lockstep, so a delivered
+    // frame stays a frame.
     let count = 0;
     let pos = this.position;
     while (pos < inputLength - 1) {
@@ -70,13 +152,15 @@ class DecibriProcessor extends AudioWorkletProcessor {
       pos += this.ratio;
     }
 
-    const output = new Float32Array(count);
+    const output = planar.map(() => new Float32Array(count));
     pos = this.position;
 
     for (let i = 0; i < count; i++) {
       const idx = Math.floor(pos);
       const frac = pos - idx;
-      output[i] = input[idx] * (1 - frac) + input[idx + 1] * frac;
+      for (let c = 0; c < planar.length; c++) {
+        output[c][i] = planar[c][idx] * (1 - frac) + planar[c][idx + 1] * frac;
+      }
       pos += this.ratio;
     }
 
@@ -90,19 +174,19 @@ class DecibriProcessor extends AudioWorkletProcessor {
     let transferBuffer;
 
     if (this.format === 'int16') {
-      const int16 = new Int16Array(this.framesPerBuffer);
-      for (let i = 0; i < this.framesPerBuffer; i++) {
+      const int16 = new Int16Array(this.samplesPerChunk);
+      for (let i = 0; i < this.samplesPerChunk; i++) {
         int16[i] = Math.max(-32768, Math.min(32767, Math.round(this.buffer[i] * 32768)));
       }
       transferBuffer = int16.buffer;
     } else {
-      transferBuffer = this.buffer.slice(0, this.framesPerBuffer).buffer;
+      transferBuffer = this.buffer.slice(0, this.samplesPerChunk).buffer;
     }
 
     this.port.postMessage(transferBuffer, [transferBuffer]);
 
     // Reset accumulation buffer
-    this.buffer = new Float32Array(this.framesPerBuffer);
+    this.buffer = new Float32Array(this.samplesPerChunk);
     this.bufferIndex = 0;
   }
 }

package/src/decibri.d.ts

@@ -8,10 +8,12 @@ export interface MicrophoneInfo {
   name: string;
   /**
    * Stable per-host device ID. Pass via `device: { id: ... }` for selection
-   * that survives across enumerations.
-   * - Windows (WASAPI): endpoint ID
-   * - macOS (CoreAudio): device UID
-   * - Linux (ALSA): PCM identifier
+   * that survives across enumerations. The lowercase host name, a colon, then
+   * the platform device identifier:
+   * - Windows (WASAPI): `wasapi:` then the endpoint ID (e.g.
+   *   `wasapi:{0.0.1.00000000}.{...}`)
+   * - macOS (CoreAudio): `coreaudio:` then the device UID
+   * - Linux (ALSA): `alsa:` then the PCM identifier
    * Empty string if cpal cannot produce a stable ID for this device.
    */
   id: string;
@@ -59,6 +61,17 @@ export interface VadOptions {
    * @default 300
    */
   holdoffMs?: number;
+
+  /**
+   * The 0-based DELIVERED channel the detector reads: the position within
+   * the delivered interleaved frames, after any `channelMap` is applied (a
+   * `channelMap` names device channels; `source` names the delivered
+   * position). Must be below the delivered channel count, which is its only
+   * ceiling; no fixed maximum exists. Affects only the detector feed; the
+   * delivered audio is untouched.
+   * @default the frame average of every delivered channel
+   */
+  source?: number;
 }
 
 /**
@@ -133,10 +146,56 @@ export interface AecOptions {
   referenceChannels?: number;
 }
 
+/**
+ * One delivered channel's canceller report, one entry of
+ * `AecMetrics.channels`. Engine-level fields only: the reference queue's
+ * counters (`referenceDropped`, `referenceSilence`) describe the shared queue
+ * and stay on `AecMetrics` itself.
+ */
+export interface AecChannelMetrics {
+  /**
+   * This channel's active delay alignment in samples, or `null` while its
+   * estimator is still searching. The offset from the reference frontier as
+   * the feeding established it, not a measurement of the room's echo path.
+   */
+  delaySamples: number | null;
+  /**
+   * This channel's smoothed echo-return-loss-enhancement estimate in dB. Not
+   * a quality ranking across channels: ERLE rises with echo distance, because
+   * a weaker echo is easier to reduce in ratio terms, so a far microphone
+   * routinely reports a higher figure than a near one while removing less
+   * echo in absolute terms. Compare a channel against its own history, not
+   * against its neighbours.
+   */
+  erleDb: number;
+  /**
+   * Whether this channel's double-talk detector currently believes the
+   * near-end talker is active; its adaptation is held while true.
+   */
+  doubleTalk: boolean;
+  /**
+   * Near-end samples this channel's canceller could find no far-end sample
+   * for while an alignment was active.
+   */
+  referenceStarved: number;
+  /**
+   * Near-end samples this channel processed while no delay alignment was
+   * active: the searching span, not a transport failure.
+   */
+  acquisitionParked: number;
+  /**
+   * Times this channel's canceller inferred a capture discontinuity and
+   * rebuilt its alignment from the reference frontier.
+   */
+  referenceReanchors: 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.
+ * the reference queue's counters. The top-level engine fields report the first
+ * delivered channel's canceller; `channels` carries every delivered channel's
+ * report, so the two agree on a single-channel stream.
  */
 export interface AecMetrics {
   /**
@@ -175,10 +234,10 @@ export interface AecMetrics {
    */
   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.
+   * Far-end samples discarded, at the declared reference rate: a single push
+   * exceeded the reference queue's bound, or the push arrived while capture
+   * was not running. The span an oversized push occupied is still represented
+   * as silence, so that discard costs the cancellation of the span alone.
    */
   referenceDropped: number;
   /**
@@ -187,6 +246,15 @@ export interface AecMetrics {
    * while nothing is playing, the far end is silence.
    */
   referenceSilence: number;
+  /**
+   * Every delivered channel's canceller report, in delivered order, one entry
+   * per channel. One canceller engine runs per delivered channel, each fed
+   * the same pushed reference and each finding its own channel's echo delay,
+   * so the entries differ where the channels' acoustic paths differ. On a
+   * single-channel stream this holds one entry agreeing with the top-level
+   * fields.
+   */
+  channels: AecChannelMetrics[];
 }
 
 /** Constructor options for `Microphone`. */
@@ -199,17 +267,50 @@ export interface MicrophoneOptions extends ReadableOptions {
   sampleRate?: number;
 
   /**
-   * Number of input channels. Mono only: the only accepted value is `1`, and a
-   * value greater than `1` throws a `RangeError` (multichannel capture is not
-   * supported) rather than being silently downmixed. The option is kept for
-   * forward compatibility: a future release may accept a value greater than `1`
-   * by delivering true interleaved multichannel.
+   * Number of channels the stream delivers, interleaved frame by frame in the
+   * emitted chunks. Bounded below at `1` (the default); bounded above by the
+   * resolved device alone, which reports its own count when the stream
+   * starts. No fixed maximum exists.
+   *
+   * The device itself is opened at its own native channel count, exactly as
+   * it is opened at its native rate, and decibri derives the delivered
+   * channels from it. Without a `channelMap`: `1` delivers the documented
+   * average of every opened channel; a count equal to the device's own
+   * delivers every device channel in device order; a count above the
+   * device's own fails `start()` with a `DecibriError` carrying the code
+   * `'MICROPHONE_CHANNELS_UNSUPPORTED'`; and a count above `1` and below the
+   * device's own fails it with `'CHANNEL_SELECTION_AMBIGUOUS'`, because
+   * which channels it means has no single answer, so `channelMap` names
+   * them. With `aec` set, one canceller runs per delivered channel, and
+   * `aecMetrics().channels` reports each delivered channel's canceller in
+   * delivered order.
    * @default 1
    */
   channels?: number;
 
+  /**
+   * Optional list of 0-based device channel indices selecting which device
+   * channels feed the delivered channels: delivered channel `j` carries device
+   * channel `channelMap[j]`. The length must equal `channels`. Entries may
+   * repeat and may appear in any order, so a map both selects and permutes,
+   * and may name more delivered channels than the device has. Absent derives
+   * the delivered channels from `channels` as documented there.
+   *
+   * The same shape as CoreAudio AUHAL's channel map
+   * (`kAudioOutputUnitProperty_ChannelMap`: an array of device channel
+   * indices, one entry per client channel). NOT miniaudio's `channelMap`,
+   * which names a spatial layout. Entries are validated against the resolved
+   * device's own report when the stream starts: an entry the device does not
+   * have throws a `DecibriError` with code `'CHANNEL_MAP_OUT_OF_RANGE'` naming
+   * the entry and the count the device reports. The device's report is the
+   * only ceiling; no fixed maximum exists.
+   * @default undefined (the derivation `channels` documents)
+   */
+  channelMap?: number[];
+
   /**
    * Frames per audio callback buffer. Controls chunk size and delivery interval.
+   * A chunk holds this many frames of the delivered channel count.
    * At 16 kHz mono, 1600 frames = 100 ms chunks of 3200 bytes (int16).
    * @default 1600
    * @range 64–65536
@@ -239,8 +340,8 @@ export interface MicrophoneOptions extends ReadableOptions {
    * - `false`: disabled (default)
    * - `'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
+   * - a `VadOptions` config object `{ model, threshold?, holdoffMs?, source? }`
+   *   to tune the threshold, holdoff, and detector source for the chosen model
    *
    * The string shorthand uses the mode's default threshold (0.5 for `'silero'`,
    * 0.01 for `'energy'`) and a 300 ms holdoff; pass a `VadOptions` object to
@@ -388,8 +489,10 @@ export declare class Microphone extends Readable {
 
   /**
    * Number of capture buffers dropped because the consumer could not keep pace.
-   * 0 while the consumer keeps up, or before capture starts. A rising value
-   * means audio is being dropped to bound memory.
+   * 0 while the consumer keeps up, before capture starts, and after `stop()`,
+   * which releases the stream the counter lives on. Read it before stopping to
+   * see a session's total. A rising value means audio is being dropped to
+   * bound memory.
    */
   readonly overrunCount: number;
 
@@ -409,7 +512,11 @@ export declare class Microphone extends Readable {
    * 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.
+   * running is discarded and counted by `referenceDropped`, read once
+   * capture runs; a push with the `aec` option unset is a no-op. A typed
+   * array carrying a sample dtype other than the configured `dtype` throws
+   * a `TypeError`, whatever the capture state; `Buffer`, `Uint8Array`, and
+   * `DataView` are format-agnostic byte carriers.
    */
   pushAecReference(data: Buffer | NodeJS.ArrayBufferView): void;
 
@@ -464,6 +571,41 @@ export interface FileOptions extends ReadableOptions {
    */
   sampleRate?: number;
 
+  /**
+   * Number of channels the File delivers, interleaved frame by frame in the
+   * emitted chunks. Bounded below at `1` (the default); bounded above by the
+   * source's own channel count alone, read from the container's header (or
+   * `inputChannels` for `File.buffer`). No fixed maximum exists. The same
+   * meaning the option has on `Microphone`, with the source's count standing
+   * where the device's report stands.
+   *
+   * Without a `channelMap`: `1` delivers the documented average of every
+   * source channel; a count equal to the source's own delivers every source
+   * channel in source order; a count above the source's own throws a
+   * `DecibriError` carrying the code `'FILE_CHANNELS_UNSUPPORTED'`; and a
+   * count above `1` and below the source's own throws one with
+   * `'FILE_CHANNEL_SELECTION_AMBIGUOUS'`, because which channels it means
+   * has no single answer, so `channelMap` names them.
+   * @default 1
+   */
+  channels?: number;
+
+  /**
+   * Optional list of 0-based source channel indices selecting which source
+   * channels feed the delivered channels: delivered channel `j` carries
+   * source channel `channelMap[j]`. The length must equal `channels`.
+   * Entries may repeat and may appear in any order, so a map both selects
+   * and permutes, and may name more delivered channels than the source has.
+   * Absent derives the delivered channels from `channels` as documented
+   * there. The same shape and semantics as the `Microphone` option, with
+   * source channels in the device channels' place. An entry the source does
+   * not have throws a `DecibriError` with code
+   * `'FILE_CHANNEL_MAP_OUT_OF_RANGE'` naming the entry and the source's own
+   * count. The source's count is the only ceiling; no fixed maximum exists.
+   * @default undefined (the derivation `channels` documents)
+   */
+  channelMap?: number[];
+
   /**
    * Sample encoding data type of the delivered chunks.
    * - `'int16'`: 16-bit signed integer, little-endian (2 bytes per sample)
@@ -527,7 +669,7 @@ export interface FileOptions extends ReadableOptions {
   limiter?: number;
 }
 
-/** Options for `File.buffer`: `FileOptions` plus the samples' native rate. */
+/** Options for `File.buffer`: `FileOptions` plus the samples' own shape. */
 export interface FileBufferOptions extends FileOptions {
   /**
    * The native rate of the in-memory samples in Hz. Required: raw samples
@@ -536,6 +678,18 @@ export interface FileBufferOptions extends FileOptions {
    * @range 1000–384000
    */
   inputRate: number;
+
+  /**
+   * The interleave of the in-memory samples: how many channels each frame
+   * carries. Raw samples carry no header to read a count from, so above
+   * mono it is stated here, the channel counterpart of `inputRate`. The
+   * samples' length must be a whole number of frames at this count. Applies
+   * to `File.buffer` alone: a file's count is read from its own header, and
+   * the option is refused on the open path.
+   * @default 1
+   * @range 1–65535
+   */
+  inputChannels?: number;
 }
 
 /**
@@ -769,10 +923,17 @@ export interface AudioWriterOptions extends SaveOptions, WritableOptions {
   sampleRate: number;
 
   /**
-   * Number of channels. Audio is written mono; only `1` is accepted.
+   * Number of channels the incoming bytes are interleaved at, written into
+   * the file's header. The stream's total sample count must be a whole
+   * number of frames at this count. Bounded below at `1` (the default);
+   * above it, each container's own ceiling applies (a FLAC frame carries at
+   * most 8 channels; a WAV `fmt ` chunk's `nBlockAlign` is a 16-bit field,
+   * so 16-bit samples allow at most 32767), reported when the stream
+   * finishes as the container layer's own refusal. decibri enforces no
+   * ceiling of its own.
    * @default 1
    */
-  channels?: 1;
+  channels?: number;
 
   /**
    * Sample encoding of the incoming bytes.