decibri 5.4.0 → 5.6.0

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-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

@@ -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;
@@ -42,7 +44,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';
@@ -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;
 }
 
 /**
@@ -105,12 +118,84 @@ 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;
+}
+
+/**
+ * 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 {
   /**
@@ -149,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;
   /**
@@ -161,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`. */
@@ -173,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
@@ -211,10 +338,10 @@ 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
+   * - 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
@@ -362,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;
 
@@ -371,13 +500,23 @@ 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
    * 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;
 
@@ -432,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)
@@ -495,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
@@ -504,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;
 }
 
 /**
@@ -737,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.
@@ -810,9 +1003,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;