decibri 5.5.0 → 5.6.0

package/src/decibri.js

@@ -102,6 +102,7 @@ class Microphone extends Readable {
     this._vad = prepared.vadEnabled;
     this._vadThreshold = prepared.vadThreshold;
     this._vadHoldoff = prepared.vadHoldoff;
+    this._dtype = prepared.dtype;
     this._vadScore = 0;
     this._isSpeaking = false;
     this._silenceTimer = null;
@@ -145,16 +146,42 @@ class Microphone extends Readable {
       throw new RangeError('sample rate must be between 1000 and 384000');
     }
 
-    // Mono only: the capture path delivers a single channel. A value below 1
-    // is a plain range error; a value above 1 is rejected as multichannel
-    // (not silently downmixed) so a later move to true multichannel stays
-    // additive. The `channels` option is kept for that forward compatibility.
+    // The number of channels delivered, interleaved frame by frame. Bounded
+    // below here; bounded above by the resolved device alone, which answers
+    // when the stream starts. No fixed maximum exists on this path.
     const channels = options.channels ?? 1;
     if (channels < 1) {
       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)');
+
+    // ── Validate channel map ─────────────────────────────────────────────────
+
+    // An optional list of 0-based device channel indices, one per delivered
+    // channel: delivered channel j carries device channel channelMap[j].
+    // Absence delivers the documented average of every opened channel. The
+    // checks here are shape-only (an array of integers that fit the channel
+    // count's width, with one entry per channel); whether each entry exists on
+    // the device is the core's check, made against the resolved device's own
+    // report when the stream starts, because only the device can say how many
+    // channels it has. No fixed maximum exists on this path.
+    const channelMap = options.channelMap;
+    if (channelMap !== undefined) {
+      if (!Array.isArray(channelMap)) {
+        throw new TypeError(
+          `Invalid channelMap value: ${JSON.stringify(channelMap)}. Expected an array of 0-based device channel indices, such as [0].`
+        );
+      }
+      for (const entry of channelMap) {
+        if (typeof entry !== 'number' || !Number.isInteger(entry)) {
+          throw new TypeError('channelMap entries must be integers');
+        }
+        if (entry < 0 || entry > 65535) {
+          throw new RangeError('channelMap entries must be between 0 and 65535');
+        }
+      }
+      if (channelMap.length !== channels) {
+        throw new RangeError('channelMap must have exactly one entry per channel');
+      }
     }
 
     const framesPerBuffer = options.framesPerBuffer ?? 1600;
@@ -202,7 +229,7 @@ class Microphone extends Readable {
     // vad selects the detector and (optionally) its threshold/holdoff policy.
     // It accepts false (disabled, default), the 'silero'/'energy' shorthand
     // (which uses the mode's default threshold and holdoff), or a config object
-    // { model, threshold, holdoffMs } to tune the policy. The legacy two-flag
+    // { model, threshold, holdoffMs, source } to tune the policy. The legacy two-flag
     // form (vad: true plus vadMode) and the flat vadThreshold/vadHoldoff
     // options are rejected with a migration error. The threshold and holdoff
     // live JS-side (the state machine runs in this wrapper); only the mode is
@@ -218,6 +245,7 @@ class Microphone extends Readable {
     let vadMode;
     let vadThreshold;
     let vadHoldoff;
+    let vadSource;
     if (vad === false) {
       vadEnabled = false;
       vadMode = 'energy'; // inert placeholder; ignored while disabled
@@ -229,10 +257,13 @@ class Microphone extends Readable {
       vadEnabled = true;
       vadMode = vad;
     } else if (vad !== null && typeof vad === 'object' && !Array.isArray(vad)) {
-      // Config object form: { model, threshold?, holdoffMs? }. model is required
-      // and selects the detector; threshold and holdoffMs override the mode
-      // defaults when supplied.
-      const { model, threshold, holdoffMs } = vad;
+      // Config object form: { model, threshold?, holdoffMs?, source? }. model
+      // is required and selects the detector; threshold and holdoffMs override
+      // the mode defaults when supplied; source names the 0-based DELIVERED
+      // channel the detector reads (the position within the delivered
+      // interleaved frames, after any channelMap), absent feeding the frame
+      // average of every delivered channel.
+      const { model, threshold, holdoffMs, source } = vad;
       if (model !== 'silero' && model !== 'energy') {
         throw new TypeError(
           `Invalid vad model: ${JSON.stringify(model)}. Expected 'silero' or 'energy'.`
@@ -258,9 +289,26 @@ class Microphone extends Readable {
         }
         vadHoldoff = holdoffMs;
       }
+      if (source !== undefined) {
+        if (typeof source !== 'number' || !Number.isInteger(source)) {
+          throw new TypeError('vad source must be an integer');
+        }
+        if (source < 0 || source > 65535) {
+          throw new RangeError('vad source must be between 0 and 65535');
+        }
+        // The delivered count is the only ceiling, checked here where both
+        // sides are in scope; the message is the core's own for the same
+        // condition. No fixed maximum exists.
+        if (source >= channels) {
+          throw new RangeError(
+            `the detector source names delivered channel ${source}; the delivered channel count is ${channels}`
+          );
+        }
+        vadSource = source;
+      }
     } else {
       throw new TypeError(
-        `Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'silero', 'energy', or a config object { model, threshold, holdoffMs }.`
+        `Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'silero', 'energy', or a config object { model, threshold, holdoffMs, source }.`
       );
     }
 
@@ -433,6 +481,7 @@ class Microphone extends Readable {
       nativeOptions: {
         sampleRate,
         channels,
+        channelMap,
         framesPerBuffer,
         format: dtype,
         device: resolvedDevice,
@@ -441,6 +490,9 @@ class Microphone extends Readable {
         // native compute the energy score for a microphone that did not ask for
         // VAD. Absent means VAD off in native.
         vadMode: vadEnabled ? vadMode : undefined,
+        // The delivered channel the detector reads, from the vad config
+        // object's source key. Absent feeds the frame average.
+        detectorSource: vadSource,
         modelPath,
         dcRemoval,
         denoise,
@@ -614,24 +666,27 @@ 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`), 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.
+   * played out, pushed as it is played, in played order. Accepts a `Buffer`,
+   * `Uint8Array`, or `DataView` of PCM bytes in this microphone's `dtype`,
+   * or the typed array carrying that dtype (`Int16Array` for `'int16'`,
+   * `Float32Array` for `'float32'`), at the declared `referenceSampleRate`
+   * (the capture rate when unset), interleaved at the declared
+   * `referenceChannels` (mono when unset). A typed array carrying any other
+   * sample dtype throws a `TypeError`, whatever the capture state. 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
    * 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.
+   * playing. A push while capture is not running is discarded and counted by
+   * `referenceDropped`, read once capture runs; a push with the `aec` option
+   * unset is a no-op.
    *
    * @param {Buffer | NodeJS.ArrayBufferView} data PCM samples in the
    *   configured `dtype`.
@@ -641,8 +696,28 @@ class Microphone extends Readable {
     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.
+      // A typed array names its own sample dtype, so one carrying a dtype
+      // other than the configured one is refused rather than read as raw
+      // bytes. Buffer, Uint8Array, and DataView are format-agnostic byte
+      // carriers, exactly as bytes are on the Python surface; the accepted
+      // view is normalized to the same bytes, no copy, exactly as the stream
+      // machinery normalizes a typed-array write to a Speaker.
+      if (!(data instanceof Uint8Array) && !(data instanceof DataView)) {
+        const expected = this._dtype === 'int16' ? Int16Array : Float32Array;
+        if (!(data instanceof expected)) {
+          const mismatched = this._dtype === 'int16' ? Float32Array : Int16Array;
+          if (data instanceof mismatched) {
+            const other = this._dtype === 'int16' ? 'float32' : 'int16';
+            throw new TypeError(
+              `dtype '${this._dtype}' configured but ${mismatched.name} samples were pushed; ` +
+                `convert to ${expected.name} or construct Microphone with dtype: '${other}'`
+            );
+          }
+          throw new TypeError(
+            'pushAecReference requires a Buffer, TypedArray, or DataView of PCM samples in the configured dtype'
+          );
+        }
+      }
       buf = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
     } else {
       throw new TypeError(
@@ -663,6 +738,11 @@ class Microphone extends Readable {
    * `referenceDropped` means single pushes are exceeding the reference
    * queue's bound.
    *
+   * The top-level engine fields report the first delivered channel's
+   * canceller; `channels` carries every delivered channel's report in
+   * delivered order, one entry per channel, so the two agree on a
+   * single-channel stream.
+   *
    * @returns {import('./decibri').AecMetrics | null}
    */
   aecMetrics() {
@@ -677,6 +757,14 @@ class Microphone extends Readable {
       referenceReanchors: m.referenceReanchors,
       referenceDropped: m.referenceDropped,
       referenceSilence: m.referenceSilence,
+      channels: m.channels.map((c) => ({
+        delaySamples: c.delaySamples ?? null,
+        erleDb: c.erleDb,
+        doubleTalk: c.doubleTalk,
+        referenceStarved: c.referenceStarved,
+        acquisitionParked: c.acquisitionParked,
+        referenceReanchors: c.referenceReanchors,
+      })),
     };
   }
 
@@ -755,6 +843,15 @@ class File extends Readable {
   constructor(filePath, options = {}, _internal = undefined) {
     super({ highWaterMark: options.highWaterMark, objectMode: false });
 
+    // The open path reads the source's channel count from the file's own
+    // header, so a caller-stated interleave has nothing to describe here;
+    // it is refused rather than ignored.
+    if (!_internal && options.inputChannels !== undefined) {
+      throw new TypeError(
+        'inputChannels applies only to File.buffer; a file carries its channel count in its own header'
+      );
+    }
+
     const prepared = _internal ? _internal.prepared : File._prepareOptions(options);
 
     // ── Store config ───────────────────────────────────────────────────────
@@ -772,6 +869,9 @@ class File extends Readable {
     this._silenceStartPos = null;
     this._position = 0;
     this._sampleRate = prepared.nativeOptions.sampleRate;
+    // The delivered channel count: file time advances by frames, so the
+    // interleaved sample count divides by it before it divides by the rate.
+    this._channels = prepared.channels;
     this._bytesPerSample = prepared.dtype === 'int16' ? 2 : 4;
     this._ended = false;
     // Set the moment the consumer asks the stream for data, which is earlier
@@ -810,6 +910,42 @@ class File extends Readable {
       throw new RangeError('sample rate must be between 1000 and 384000');
     }
 
+    // The number of channels delivered, interleaved frame by frame. Bounded
+    // below here; bounded above by the source's own channel count alone,
+    // which the core reads from the header (or takes from inputChannels)
+    // when the source is opened. No fixed maximum exists on this path.
+    const channels = options.channels ?? 1;
+    if (channels < 1) {
+      throw new RangeError('channels must be at least 1');
+    }
+
+    // An optional list of 0-based source channel indices, one per delivered
+    // channel: delivered channel j carries source channel channelMap[j].
+    // Absence delivers the documented average of every source channel. The
+    // checks here are shape-only, exactly as the Microphone's: whether each
+    // entry exists on the source is the core's check, made against the
+    // source's own count, because only the opened source can say how many
+    // channels it has. No fixed maximum exists on this path.
+    const channelMap = options.channelMap;
+    if (channelMap !== undefined) {
+      if (!Array.isArray(channelMap)) {
+        throw new TypeError(
+          `Invalid channelMap value: ${JSON.stringify(channelMap)}. Expected an array of 0-based source channel indices, such as [0].`
+        );
+      }
+      for (const entry of channelMap) {
+        if (typeof entry !== 'number' || !Number.isInteger(entry)) {
+          throw new TypeError('channelMap entries must be integers');
+        }
+        if (entry < 0 || entry > 65535) {
+          throw new RangeError('channelMap entries must be between 0 and 65535');
+        }
+      }
+      if (channelMap.length !== channels) {
+        throw new RangeError('channelMap must have exactly one entry per channel');
+      }
+    }
+
     const dtype = options.dtype ?? 'int16';
     if (dtype !== 'int16' && dtype !== 'float32') {
       throw new TypeError("dtype must be 'int16' or 'float32'");
@@ -830,6 +966,7 @@ class File extends Readable {
     let vadMode;
     let vadThreshold;
     let vadHoldoff;
+    let vadSource;
     if (vad === false) {
       vadEnabled = false;
       vadMode = 'energy'; // inert placeholder; ignored while disabled
@@ -841,7 +978,7 @@ class File extends Readable {
       vadEnabled = true;
       vadMode = vad;
     } else if (vad !== null && typeof vad === 'object' && !Array.isArray(vad)) {
-      const { model, threshold, holdoffMs } = vad;
+      const { model, threshold, holdoffMs, source } = vad;
       if (model !== 'silero' && model !== 'energy') {
         throw new TypeError(
           `Invalid vad model: ${JSON.stringify(model)}. Expected 'silero' or 'energy'.`
@@ -867,9 +1004,25 @@ class File extends Readable {
         }
         vadHoldoff = holdoffMs;
       }
+      // source names the 0-based DELIVERED channel the detector reads,
+      // exactly as on Microphone; the checks and messages are the same.
+      if (source !== undefined) {
+        if (typeof source !== 'number' || !Number.isInteger(source)) {
+          throw new TypeError('vad source must be an integer');
+        }
+        if (source < 0 || source > 65535) {
+          throw new RangeError('vad source must be between 0 and 65535');
+        }
+        if (source >= channels) {
+          throw new RangeError(
+            `the detector source names delivered channel ${source}; the delivered channel count is ${channels}`
+          );
+        }
+        vadSource = source;
+      }
     } else {
       throw new TypeError(
-        `Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'silero', 'energy', or a config object { model, threshold, holdoffMs }.`
+        `Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'silero', 'energy', or a config object { model, threshold, holdoffMs, source }.`
       );
     }
 
@@ -923,16 +1076,22 @@ class File extends Readable {
 
     return {
       dtype,
+      channels,
       vadEnabled,
       vadMode,
       vadThreshold: vadThreshold ?? (vadMode === 'silero' ? 0.5 : 0.01),
       vadHoldoff: vadHoldoff ?? 300,
       nativeOptions: {
         sampleRate,
+        channels,
+        channelMap,
         format: dtype,
         // Pass the mode to native only when VAD is enabled, exactly as the
         // Microphone options do; absent means VAD off in native.
         vadMode: vadEnabled ? vadMode : undefined,
+        // The delivered channel the detector reads, from the vad config
+        // object's source key. Absent feeds the frame average.
+        detectorSource: vadSource,
         // The whole-file analysis applies threshold and holdoff in the core
         // (segment merging in file time), so both cross the boundary here,
         // unlike the live path where the policy is wrapper-only.
@@ -964,6 +1123,13 @@ class File extends Readable {
     if (typeof filePath !== 'string') {
       throw new TypeError('path must be a string');
     }
+    // The same refusal the synchronous constructor makes: a path's channel
+    // count comes from its own header.
+    if (options.inputChannels !== undefined) {
+      throw new TypeError(
+        'inputChannels applies only to File.buffer; a file carries its channel count in its own header'
+      );
+    }
     const prepared = File._prepareOptions(options);
     let native;
     try {
@@ -976,12 +1142,13 @@ class File extends Readable {
 
   /**
    * Wrap in-memory samples as an offline source. `samples` must be a
-   * `Float32Array` of mono samples in [-1.0, 1.0]; a raw `Buffer` of PCM
-   * bytes is rejected as ambiguous (encoded bytes, int16 PCM, and f32
-   * samples are indistinguishable, and decibri's own capture output is a
-   * `Buffer`). Raw samples carry no header, so `inputRate` (their native
-   * rate) is required; `sampleRate` stays the target output rate. No I/O,
-   * so construction is synchronous.
+   * `Float32Array` of samples in [-1.0, 1.0], frame-interleaved at
+   * `inputChannels` (1, mono, by default); a raw `Buffer` of PCM bytes is
+   * rejected as ambiguous (encoded bytes, int16 PCM, and f32 samples are
+   * indistinguishable, and decibri's own capture output is a `Buffer`). Raw
+   * samples carry no header, so `inputRate` (their native rate) is
+   * required; `sampleRate` stays the target output rate. No I/O, so
+   * construction is synchronous.
    *
    * @param {Float32Array} samples
    * @param {import('./decibri').FileBufferOptions} [options]
@@ -1003,10 +1170,23 @@ class File extends Readable {
     if (inputRate < 1000 || inputRate > 384000) {
       throw new RangeError('inputRate must be between 1000 and 384000');
     }
+    // The channel counterpart of inputRate: the interleave of the caller's
+    // own samples. Shape-checked here; whether the samples divide into
+    // whole frames at this count is the core's check.
+    const inputChannels = options.inputChannels ?? 1;
+    if (typeof inputChannels !== 'number' || !Number.isInteger(inputChannels)) {
+      throw new TypeError('inputChannels must be an integer');
+    }
+    if (inputChannels < 1 || inputChannels > 65535) {
+      throw new RangeError('inputChannels must be between 1 and 65535');
+    }
     const prepared = File._prepareOptions(options);
     let native;
     try {
-      native = FileHandle.buffer(samples, inputRate, prepared.nativeOptions);
+      native = FileHandle.buffer(samples, inputRate, {
+        ...prepared.nativeOptions,
+        inputChannels,
+      });
     } catch (err) {
       throw wrapNativeError(err);
     }
@@ -1094,7 +1274,9 @@ class File extends Readable {
       // before the opt-in conditioning step, exactly as the live pump does.
       this._processVadValue(this._native.vadProbability, chunk.length);
     } else {
-      this._position += chunk.length / this._bytesPerSample / this._sampleRate;
+      // Bytes to interleaved samples to frames to seconds of file time.
+      this._position +=
+        chunk.length / this._bytesPerSample / this._channels / this._sampleRate;
     }
     this.push(chunk);
   }
@@ -1108,7 +1290,9 @@ class File extends Readable {
    */
   _processVadValue(value, chunkBytes) {
     const chunkStart = this._position;
-    const chunkEnd = chunkStart + chunkBytes / this._bytesPerSample / this._sampleRate;
+    // Bytes to interleaved samples to frames to seconds of file time.
+    const chunkEnd =
+      chunkStart + chunkBytes / this._bytesPerSample / this._channels / this._sampleRate;
     this._position = chunkEnd;
     this._vadScore = value;
     if (value >= this._vadThreshold) {
@@ -1301,7 +1485,9 @@ class AudioWriter extends Writable {
    *
    * 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
+   * bytes), frame-interleaved at `channels` (1, mono, by default; the
+   * stream's total sample count must divide into whole frames, and each
+   * container's own channel ceiling applies at the write). `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
@@ -1324,9 +1510,12 @@ class AudioWriter extends Writable {
     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)');
+    // Bounded below here; above, each container's own ceiling answers at
+    // the write, with the container layer's own message. No decibri-side
+    // maximum exists on this path.
+    const channels = options.channels ?? 1;
+    if (channels < 1) {
+      throw new RangeError('channels must be at least 1');
     }
     const dtype = options.dtype ?? 'int16';
     if (dtype !== 'int16' && dtype !== 'float32') {
@@ -1337,6 +1526,7 @@ class AudioWriter extends Writable {
     this._saveOptions = File._prepareSaveOptions(options);
     this._filePath = filePath;
     this._sampleRate = sampleRate;
+    this._channels = channels;
     this._dtype = dtype;
     this._chunks = [];
     this._report = null;
@@ -1384,13 +1574,17 @@ class AudioWriter extends Writable {
         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.
+    // The write is File.save on a source at the writer's own rate and
+    // interleave: the same encode path, so the two spellings produce the
+    // same bytes. A stream that does not divide into whole frames is the
+    // core's refusal, surfaced here when the stream finishes.
     let file;
     try {
       file = File.buffer(samples, {
         inputRate: this._sampleRate,
+        inputChannels: this._channels,
         sampleRate: this._sampleRate,
+        channels: this._channels,
       });
     } catch (err) {
       callback(err);

package/src/errors.js

@@ -76,10 +76,12 @@ class OrtPathError extends OrtError {
 const RANGE_PREFIXES = [
   'sample rate 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',
+  'the detector source names',
+  'the channel map has',
+  'the requested block size',
   'flac compression level must be between',
   'aec tailMs must be between',
   'aec referenceSampleRate must be between',
@@ -127,6 +129,12 @@ const BASE_CODES = [
   ['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'],
+  ['the input device does not support', 'MICROPHONE_CHANNELS_UNSUPPORTED'],
+  ['a channel map is required', 'CHANNEL_SELECTION_AMBIGUOUS'],
+  ['the channel map names', 'CHANNEL_MAP_OUT_OF_RANGE'],
+  ['the file does not have', 'FILE_CHANNELS_UNSUPPORTED'],
+  ['delivering', 'FILE_CHANNEL_SELECTION_AMBIGUOUS'],
+  ['the file channel map names', 'FILE_CHANNEL_MAP_OUT_OF_RANGE'],
   ['Microphone permission denied.', 'PERMISSION_DENIED'],
   ['Microphone stream is closed', 'MICROPHONE_STREAM_CLOSED'],
   ['Speaker stream is closed', 'SPEAKER_STREAM_CLOSED'],