decibri 5.5.0 → 5.6.0

package/CHANGELOG.md

@@ -9,6 +9,45 @@ For other decibri packages, see:
 - Rust core: [crates/decibri/CHANGELOG.md](../../crates/decibri/CHANGELOG.md)
 - Python package: [bindings/python/CHANGELOG.md](../../bindings/python/CHANGELOG.md)
 
+## [5.6.0] - 2026-08-16
+
+### Breaking changes
+
+- **`Microphone` opens the device at its native channel count, and decibri performs the collapse to the delivered mono.** The device was opened at the configured count of 1, so on a multichannel device the operating system collapsed the channels before decibri saw them, and it did so differently on each platform: the Windows audio engine applies an unpublished mixing matrix, macOS's default channel map selects device channel zero rather than mixing, and on Linux the result depends on which PCM the device name resolved to (a `plug` device routes under a named policy, a raw `hw` device refuses the open). The capture stream now receives every device channel and decibri averages them into the delivered audio, the same documented average `File` applies to a multichannel container. The delivered audio changes for any device whose native count is above one: on macOS it changes from device channel zero to the average of every channel; on Windows the engine's stereo mix is replaced by the average, which is close to it but not guaranteed identical; above two channels every platform's mix differs from a plain average. A device already delivering one channel is unaffected, byte for byte. The `channels` option now names the DELIVERED count, exactly as `sampleRate` names the delivered rate.
+- **The browser `Microphone` receives every channel the browser grants, and decibri performs the collapse to the delivered mono.** The capture requested a single channel from `getUserMedia` and read the first channel of the granted track, so on a track granted with more than one channel the delivered audio was the first channel alone. The capture now requests the 32-channel count the Web Audio specification requires an implementation to support, with ideal semantics, reads the granted track's own channel count, and averages every granted channel into the single delivered channel, the same documented average the Node entry delivers. The delivered audio changes for any track granted with more than one channel: the first granted channel is replaced by the average of every granted channel. A track granted with a single channel is unchanged, byte for byte.
+- **`Microphone` accepts a `channels` count above 1, and a request for one is honoured rather than refused.** The constructor threw `RangeError: multichannel capture is not supported; channels must be 1 (mono)` for every count above 1, so the request failed before the device was touched. It now constructs, opens, and emits chunks carrying that many interleaved channels. Code that used the throw as a guard, catching it to fall back to a single-channel request, no longer has one: it receives interleaved multichannel audio where it received an error, and a consumer that reads a `'data'` chunk as a run of mono samples reads interleaved frames instead. Pass `channels: 1` to keep the previous delivery, which is unchanged byte for byte.
+- **The browser `Microphone` accepts a `channels` count above 1, and delivers that many channels.** It threw `RangeError: multichannel capture is not supported; channels must be 1 (mono)` for every count above 1. It now delivers the requested channels interleaved, from the granted track, exactly as the Node entry does, so the two entries accept and refuse the same inputs with the same classes and messages. Code that relied on the throw loses the same guard the Node entry's callers lose. `channels: 1` is unchanged, byte for byte, and so is every other browser `Microphone` option.
+- **The `Invalid vad value:` `TypeError` names `source` among the config object's keys.** The message reads `Invalid vad value: <value>. Expected false, 'silero', 'energy', or a config object { model, threshold, holdoffMs, source }.`, and the browser entry's copy names the same key list with its own accepted set of `false`, `'energy'`, and the config object. Code matching the full message text exactly stops matching and has to be updated to the new text; code matching the `Invalid vad value:` prefix is unaffected. The class, the inputs that throw it, the accepted `vad` values, and every other message are unchanged.
+- **`pushAecReference` refuses a typed array whose sample dtype is not the microphone's own.** Any `ArrayBufferView` was read as raw bytes in the configured `dtype`, so a `Float32Array` pushed on an `'int16'` capture fed the canceller a byte reinterpretation of its samples, with nothing said. A `Float32Array` on an `'int16'` capture and an `Int16Array` on a `'float32'` capture now throw a `TypeError` naming both dtypes and both remedies (`dtype 'int16' configured but Float32Array samples were pushed; convert to Int16Array or construct Microphone with dtype: 'float32'`, and the mirror for the other direction), and every other sample-dtype view (`Float64Array`, `Int32Array`, and the rest) throws the existing `pushAecReference requires a Buffer, TypedArray, or DataView of PCM samples in the configured dtype` message, whatever the capture state, the refusal the Python surface raises for the same condition. A call site that relied on byte reinterpretation passes its bytes as a `Buffer`, `Uint8Array`, or `DataView` instead, which remain format-agnostic byte carriers, read exactly as before. `Int16Array` on `'int16'` and `Float32Array` on `'float32'` remain accepted unchanged.
+- **`aecMetrics().referenceDropped` counts reference samples pushed while capture is not running.** A push made between construction (or `await Microphone.open()`) and the first consumer engaging the stream, or after `stop()`, was discarded with no counter moved, so the reference for audio played at startup vanished with nothing to show for it. Those samples now add to `referenceDropped`, readable once capture runs. A `referenceDropped` of zero no longer certifies only that every push fit the queue's bound; it also certifies that none arrived while capture was down, so code alerting on a nonzero figure now fires for pre-start pushes as well. The push itself still never blocks and never throws on any capture state, a push with `aec` unset is still an uncounted no-op, `aecMetrics()` still reads `null` while capture is not running, and the Python surface's counters are unchanged.
+- **`AudioWriter` accepts a `channels` count above 1, and writes that many interleaved channels.** The constructor threw `RangeError: multichannel write is not supported; channels must be 1 (mono)` for every count above 1; that message is no longer thrown, and code that relied on the throw as a guard no longer has one. The incoming bytes are read as interleaved frames at the declared count and the file's header carries it; the stream's total sample count must divide into whole frames, refused when the stream finishes otherwise. Each container's own channel ceiling applies at the write, reported as a `DecibriError` with code `AUDIO_FORMAT_UNSUPPORTED` carrying the container layer's own text: a FLAC frame carries at most 8 channels, and a WAV format chunk's `nBlockAlign` field holds at most 32767 channels at 16-bit samples. decibri enforces no ceiling of its own. `channels: 1` (still the default) writes the identical file it wrote before, byte for byte, and `channels: 0` throws `RangeError: channels must be at least 1`. `sampleRate`, `dtype`, `format`, `compression` and the `report` are unchanged.
+
+### Added
+
+- `channelMap` on the `Microphone` options: an optional array of 0-based device channel indices selecting which device channels feed the delivered channels, so `channelMap: [1]` delivers the device's second channel alone. The length must equal `channels`, and 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; a length that does not match, or a malformed array, throws a `RangeError` or `TypeError` from the constructor. Absent delivers the average of every opened channel, the previous behaviour. The same shape as CoreAudio AUHAL's channel map (an array of device channel indices, one entry per client channel), not miniaudio's `channelMap`, which names a spatial layout. Entries are checked against the resolved device's own report when the stream starts; the device's report is the only ceiling, and no fixed maximum exists.
+- Error code `CHANNEL_MAP_OUT_OF_RANGE` on `DecibriError`, emitted on the `'error'` event when the channel map names a device channel the device does not have. The message names the offending entry and the count the device reports, the figure `MicrophoneInfo.maxInputChannels` carries.
+- `channelMap` on the browser `Microphone` options, mirroring the Node entry: an optional array of 0-based device channel indices selecting which granted channels feed the delivered channels, so `channelMap: [1]` delivers the granted track's second channel alone. The length must equal `channels`, and entries may repeat and may appear in any order, so a map both selects and permutes; a length that does not match, or a malformed array, throws the same `RangeError` or `TypeError` as the Node entry, with the same message, from the constructor. Absent delivers the average of every granted channel. 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, the same message the Node entry carries for the same condition; where it does not, the same `Error` is emitted on the `'error'` event and the capture stops as soon as the audio graph reports its true channel count. The granted report is the only ceiling, and no fixed maximum exists.
+- Multichannel capture on the `Microphone`: `channels` names how many interleaved channels each `'data'` chunk carries, bounded below by the constructor and above by the resolved device alone, with no fixed maximum. With a `channelMap`, delivered channel `j` carries the device channel the map names. Without one, two derivations are accepted: 1 delivers the average of every device channel, and the device's own count delivers every device channel in device order. A chunk's samples are interleaved frames of the delivered width, so a chunk holds `framesPerBuffer * channels` samples.
+- Multichannel capture on the browser `Microphone`, the same rules read against the granted track instead of a device: a `channelMap` names granted channels, an unmapped count of 1 averages every granted channel, and an unmapped count equal to the grant delivers every granted channel in granted order. Above one delivered channel `vadScore` is the RMS of the per-frame average of the delivered channels rather than of the samples as they lie, which is what the Node entry's detector reads for the same capture; at one delivered channel it is unchanged.
+- Error code `MICROPHONE_CHANNELS_UNSUPPORTED` on `DecibriError`, emitted on the `'error'` event when the delivered count exceeds the device's own. The message names both figures, the second being the one `MicrophoneInfo.maxInputChannels` carries. The browser entry rejects `start()` with the same message.
+- Error code `CHANNEL_SELECTION_AMBIGUOUS` on `DecibriError`, emitted on the `'error'` event when the delivered count is above 1 and below the device's own with no `channelMap` set. The message names both figures. Set a `channelMap` naming which channels to deliver. The browser entry rejects `start()` with the same message.
+- Echo cancellation on every delivered channel: with `aec` set and `channels` above 1, one canceller engine runs per delivered channel, each fed the same pushed reference and each finding its own channel's echo delay. `pushAecReference` is unchanged: one push serves every channel. The processing and memory cost scale with the delivered count, and a capture that outruns the machine shows up as `overrunCount` climbing; no capacity ceiling exists. A single-channel capture with the canceller is unchanged byte for byte.
+- `channels` on the object `aecMetrics()` returns: every delivered channel's canceller report in delivered order, one entry per channel, each carrying `delaySamples`, `erleDb`, `doubleTalk`, `referenceStarved`, `acquisitionParked` and `referenceReanchors`. The top-level fields keep their names and report the first delivered channel's engine (the queue counters `referenceDropped` and `referenceSilence` describe the shared queue), so a single-channel stream reads as before with a one-entry array alongside. `delaySamples` is each engine's alignment offset from the reference frontier, not a room measurement, and `erleDb` is not a quality ranking across channels: it rises with echo distance, so a far microphone reports a higher figure while removing less echo in absolute terms.
+- `channels` and `channelMap` on the `File` options, the `Microphone`'s channel vocabulary on the offline source, with the source's own channel count (the file's header, or `File.buffer`'s `inputChannels`) standing where the device's report stands. `channels: 1` (the default) delivers the documented average of every source channel, the previous behaviour, byte for byte; a count equal to the source's own delivers every source channel in source order, interleaved frame by frame in the emitted chunks. `channelMap` is an array of 0-based source channel indices, one entry per delivered channel; 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. Checked at construction, where the source's count is known; the source's count is the only ceiling, and no fixed maximum exists.
+- Error codes `FILE_CHANNELS_UNSUPPORTED`, `FILE_CHANNEL_SELECTION_AMBIGUOUS` and `FILE_CHANNEL_MAP_OUT_OF_RANGE` on `DecibriError`, thrown from the `File` constructors: an unmapped delivered count above the source's own, an unmapped count above 1 and below the source's own (set a `channelMap` naming which source channels to deliver), and a map entry the source does not have. Each message names the figures in question. A map length that differs from `channels` keeps the shared `RangeError`.
+- `inputChannels` on the `File.buffer` options, the channel counterpart of `inputRate`: the interleave of the caller's own samples, 1 (mono) by default, up to 65535. A sample count that is not a whole number of frames at the declared count throws the same `RangeError` the live block-size refusal carries. The option applies to `File.buffer` alone and throws a `TypeError` on the open path, where the file's own header answers.
+- `File.save` writes the delivered channel count: the saved file carries the same interleaved layout the stream emits, in every container, with each container's own ceiling reported exactly as the `AudioWriter` entry above describes.
+- `source` on the `vad` config object, on the `Microphone` and `File` options alike: the 0-based DELIVERED channel the detector reads, the position within the delivered interleaved frames after any `channelMap` is applied (a `channelMap` names device or source channels; `source` names the delivered position, so a channel a map delivers at two positions is named by position). Absent feeds the detector the frame average of every delivered channel, the previous behaviour. The value must be an integer (`TypeError: vad source must be an integer` otherwise), in 0 to 65535 (`RangeError: vad source must be between 0 and 65535` otherwise), and below the delivered channel count, refused from the constructor with a `RangeError` whose message is `the detector source names delivered channel <i>; the delivered channel count is <n>`; the delivered count is the only ceiling, and no fixed maximum exists. Selecting a source changes which samples the detector reads and nothing else: the emitted audio, `threshold`, `holdoffMs`, and the `'speech'` / `'silence'` mechanics are untouched.
+- `source` on the browser `Microphone`'s `vad` config object, mirroring the Node entry: `vadScore` becomes the RMS of the named delivered channel's samples rather than of the per-frame average, and the same values are refused with the same classes and messages from the constructor.
+
+### Changed
+
+- The capture queue's fixed 64-buffer bound now holds buffers at the device's native channel width, so its memory scales with the device's channel count: roughly 123 KB per channel at a 48 kHz native rate with a typical 10 millisecond driver period.
+
+### Removed
+
+- The internal classification row for the message `multichannel capture is not supported; channels must be 1 (mono)`, which nothing produces. The message classified to a built-in `RangeError` with no `code`, so no thrown class, code, message or option changes.
+
 ## [5.5.0] - 2026-08-10
 
 ### Breaking changes
@@ -62,7 +101,7 @@ For other decibri packages, see:
 ### Added
 
 - `aec` option on `Microphone`: acoustic echo cancellation on the capture path. The short form names the model (`aec: 'tau'`); the object form takes `{ model, tailMs, suppression, referenceSampleRate }`. It runs before the detector tap, so `vadScore` and the `speech` / `silence` events read the echo-removed signal, and it requires `sampleRate` in 8000 to 48000. Native capture only: the browser entry keeps the platform's own `echoCancellation` constraint.
-- `Microphone.pushAecReference(data)`, which queues the far-end audio the canceller cancels against: the same input shapes `Speaker.write` accepts, mono, in played order, at the declared `referenceSampleRate`. It never blocks and never throws on a full queue. When it is pushed does not have to match when it plays: the queue is read at the rate the capture consumes it, so a greeting pushed before the first `data` event, or a whole utterance handed over in one call, is read out over the capture it echoes into and every sample of it is cancelled against. The queue holds two seconds, which bounds how far ahead of its own capture a caller may run.
+- `Microphone.pushAecReference(data)`, which queues the far-end audio the canceller cancels against: the same input shapes `Speaker.write` accepts, mono, in played order, at the declared `referenceSampleRate`. It never blocks and never throws on a full queue. Push the reference as it plays rather than ahead of it: the canceller acquires its delay from the reference already standing in front of the consumer's first read, so a push that runs far enough ahead of the capture it echoes into leaves the delay unacquired for the rest of the session, and the capture is then delivered uncancelled with no error reported and `aecMetrics().delaySamples` staying `null`. It does not recover on its own, and how large a lead is too large depends on the rest of the capture chain. The queue holds two seconds at the declared rate, and a push beyond that is dropped and counted in `aecMetrics().referenceDropped`.
 - `Microphone.aecMetrics()`, the canceller's transport and cancellation metrics merged with the reference queue's counters, or `null` while echo cancellation is off or capture is not running.
 
 Echo cancellation joins automatic gain control as a stage that can drive captured samples above full scale when the limiter is off, because it subtracts its estimate of the echo from the capture and exceeds the capture wherever that estimate is wrong in phase. The limiter runs after it and bounds the output to its ceiling; the `int16` sample format clamps, so an over-scale sample arrives as full scale rather than wrapping, and a `float32` consumer without the limiter should clamp its own output.

package/MIGRATION.md

@@ -42,10 +42,10 @@ is `'energy'` (the only browser detector): `vad: { model: 'energy', threshold: 0
 ## Breaking in 5.0.0: mono-only capture
 
 decibri 4.x delivered interleaved multichannel audio when a microphone was
-opened with `channels` greater than `1`. decibri 5.0.0 narrows capture to mono:
-the `channels` option accepts only `1` (the default), and a value greater than
-`1` throws a `RangeError` instead of being captured. If your code opened a
-microphone with more than one channel, pass `channels: 1` (or omit it).
+opened with `channels` greater than `1`. decibri 5.0.0 narrowed capture to
+mono: the `channels` option accepted only `1` (the default), and a value
+greater than `1` threw a `RangeError` instead of being captured. To run 4.x
+code on the 5.0.0 through 5.5.0 releases, pass `channels: 1` (or omit it).
 
 Before:
 
@@ -60,20 +60,16 @@ new Microphone({ channels: 1 }); // 5.0: mono (or omit channels entirely)
 new Microphone();                // unchanged; mono is the default
 ```
 
-A value greater than `1` now throws:
+On those releases a value greater than `1` threw:
 
 ```js
 new Microphone({ channels: 2 });
 // RangeError: multichannel capture is not supported; channels must be 1 (mono)
 ```
 
-The `channels` option and the channel-general `'data'` chunk shape are kept, so
-multichannel may return later as an additive change (a future release accepting
-a value greater than `1` by delivering true interleaved multichannel) rather
-than a further break. The intended longer-term multichannel direction is array
-ingest (consuming several channels internally for processing such as
-beamforming or array noise reduction while still delivering one conditioned
-stream), which is distinct from raw multichannel delivery.
+That restriction has since been removed: `channels` above `1` is accepted again
+and delivers interleaved multichannel audio. See
+[CHANGELOG.md](./CHANGELOG.md) for the current `channels` semantics.
 
 ## New in 4.2.0 (additive, nothing to migrate)
 

package/README.md

@@ -1,6 +1,6 @@
 # decibri
 
-Cross-platform audio capture, playback, and voice activity detection for Node.js and browsers.
+Cross-platform audio capture, conditioning, and playback for Node.js and browsers, with voice activity detection on live and recorded audio.
 
 ## Installation
 
@@ -98,11 +98,12 @@ Creates a Readable stream that captures from the microphone.
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `sampleRate` | number | 16000 | Samples per second (1000 to 384000) |
-| `channels` | number | 1 | Mono only: the only accepted value is `1`; a value greater than `1` throws a `RangeError` |
+| `channels` | number | 1 | Delivered channels per frame, interleaved. `1` (the default) delivers the average of every device channel; the device's own count delivers every device channel in device order; a `channelMap` names any other selection. The device's own report is the only ceiling; no fixed maximum exists |
+| `channelMap` | number[] | none | 0-based device channel indices choosing 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 selects, permutes, and duplicates |
 | `framesPerBuffer` | number | 1600 | Frames per chunk (64 to 65536). At 16kHz mono, 1600 = 100ms = 3200 bytes |
 | `device` | number, string, or `{ id: string }` | system default | Device index, case-insensitive name substring, or stable per-host ID |
 | `dtype` | `'int16'` \| `'float32'` | `'int16'` | Sample encoding |
-| `vad` | `false` \| `'silero'` \| `'energy'` \| `VadOptions` | `false` | Voice activity detection: disabled, the Silero ML model, an RMS energy threshold, or a config object `{ model, threshold, holdoffMs }` to tune the policy |
+| `vad` | `false` \| `'silero'` \| `'energy'` \| `VadOptions` | `false` | Voice activity detection: disabled, the Silero ML model, an RMS energy threshold, or a config object `{ model, threshold, holdoffMs, source }` to tune the policy and the detector source |
 | `modelPath` | string | bundled model | Path to the Silero model. Only used when `vad` is `'silero'` |
 | `dcRemoval` | boolean | off | Remove a constant (DC) offset with a one-pole DC-blocking high-pass. Runs first in the chain; same-length, no added latency |
 | `denoise` | `'fastenhancer-t'` | off | Single-channel speech-enhancement (denoise) model. The model ships in the package; no path or download needed |
@@ -112,7 +113,9 @@ Creates a Readable stream that captures from the microphone.
 
 Standard `ReadableOptions` (e.g. `highWaterMark`) are also accepted.
 
-`vad: true` is not accepted; pass the mode explicitly as `vad: 'silero'` or `vad: 'energy'`. The string shorthand uses the default threshold (0.5 for `'silero'`, 0.01 for `'energy'`) and a 300 ms holdoff; to tune them pass a config object: `vad: { model: 'silero', threshold: 0.6, holdoffMs: 200 }`. The `threshold` (`0`–`1`) and `holdoffMs` fields are optional and fall back to those defaults.
+`vad: true` is not accepted; pass the mode explicitly as `vad: 'silero'` or `vad: 'energy'`. The string shorthand uses the default threshold (0.5 for `'silero'`, 0.01 for `'energy'`) and a 300 ms holdoff; to tune them pass a config object: `vad: { model: 'silero', threshold: 0.6, holdoffMs: 200 }`. The `threshold` (`0`–`1`) and `holdoffMs` fields are optional and fall back to those defaults. The optional `source` field names 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 a delivered position). Absent, the detector reads the frame average of every delivered channel. Selecting a source changes which samples the detector reads and nothing else; the delivered audio is untouched.
+
+Multichannel capture delivers interleaved frames: each chunk holds `framesPerBuffer * channels` samples, and each frame carries the delivered channels in order. Without a `channelMap`, a `channels` count above `1` must equal the device's own: a count above the device's report fails with a `DecibriError` carrying the code `'MICROPHONE_CHANNELS_UNSUPPORTED'`, and a count above `1` and below the device's report fails with `'CHANNEL_SELECTION_AMBIGUOUS'`, because which channels it means has no single answer; a `channelMap` names them. A map entry the device does not have fails with `'CHANNEL_MAP_OUT_OF_RANGE'`, naming the entry and the count the device reports.
 
 ### Methods
 
@@ -235,7 +238,7 @@ Same options as Node.js, plus:
 | `noiseSuppression` | boolean | true | Browser noise suppression |
 | `workletUrl` | string | inline blob | Custom worklet URL for strict CSP |
 
-The browser runs energy-mode VAD only, so its `vad` option accepts `false` or `'energy'`. The browser `version()` returns `{ decibri }` only: the browser build has no native core, so `decibri` reports the installed package version. In Node, `version().decibri` reports the native core version.
+The browser runs energy-mode VAD only, so its `vad` option accepts `false`, `'energy'`, or a config object `{ model: 'energy', threshold, holdoffMs, source }`. The browser `version()` returns `{ decibri }` only: the browser build has no native core, so `decibri` reports the installed package version. In Node, `version().decibri` reports the native core version.
 
 ### Key differences from Node.js
 
@@ -303,9 +306,9 @@ mic.on('silence', () => console.log('silent'));
 
 The Silero model (~2MB) ships inside the npm package. No downloads or API keys required. Silero mode is Node.js only.
 
-## decibri ACE (audio conditioning)
+## Decibri ACE (audio conditioning)
 
-decibri ACE (Audio Capture Engine) is decibri's opt-in audio front-end for speech. It is a conditioning chain that runs on the captured audio before it reaches your `'data'` handler. Every stage is off by default, runs on-device, and needs no API key. With nothing enabled the capture path is byte-identical to plain capture.
+Decibri ACE (Audio Conditioning Engine) is decibri's opt-in audio front-end for speech. It is a conditioning chain that runs on the captured audio before it reaches your `'data'` handler. Every stage is off by default, runs on-device, and needs no API key. With nothing enabled the capture path is byte-identical to plain capture.
 
 The stages run in a fixed order. Enable any subset:
 
@@ -351,11 +354,11 @@ Everything a `Microphone` does to live audio, `File` does to audio you already h
 
 - `await File.open(path, options?)`: read a file off the event loop (recommended, like `Microphone.open`). Reads WAV, AIFF, AIFF-C and FLAC, identified from the file's own bytes rather than its extension.
 - `new File(path, options?)`: the same result, synchronous (blocks on disk I/O; fine for scripts).
-- `File.buffer(samples, options)`: wrap a `Float32Array` of samples you already hold. `options.inputRate` is required (raw samples carry no header); a raw `Buffer` of bytes is rejected as ambiguous.
+- `File.buffer(samples, options)`: wrap a `Float32Array` of samples you already hold. `options.inputRate` is required (raw samples carry no header); a raw `Buffer` of bytes is rejected as ambiguous. `options.inputChannels` states the interleave of the samples, `1` by default, the channel counterpart of `inputRate`.
 - `await file.analyze()` (also spelled `analyse()`): consume the source and resolve to a `VadReport` of per-window `scores` (`{ start, end, vadScore, isSpeech }`) and merged speech `segments` (`{ start, end }`), in seconds of file time. Requires `vad: 'silero'`; a `File` opened without `vad` rejects with `analysis requires VAD`.
 - `file.vadScore`, `'speech'` / `'silence'` events: per-chunk VAD alongside the stream, with the holdoff measured in FILE time (sample positions), never wall-clock time, so processing speed does not change the reported events.
 
-Options mirror `Microphone` (`sampleRate`, `dtype`, `vad`, `dcRemoval`, `denoise`, `highpass`, `agc`, `limiter`); the live-capture options (`device`, `channels`, `framesPerBuffer`) do not apply. Iteration and analysis are separate single passes: construct one `File` per operation. Note: Node also has a global `File` (the web File API); import decibri's explicitly to avoid shadowing surprises.
+Options mirror `Microphone` (`sampleRate`, `channels`, `channelMap`, `dtype`, `vad`, `dcRemoval`, `denoise`, `highpass`, `agc`, `limiter`), with `channels` and `channelMap` read against the source's own channel count (the file's header, or `inputChannels` for `File.buffer`) where the live path reads the device's report, and the vad `source` naming a delivered channel exactly as on `Microphone`; the live-capture options (`device`, `framesPerBuffer`) do not apply. Iteration and analysis are separate single passes: construct one `File` per operation. Note: Node also has a global `File` (the web File API); import decibri's explicitly to avoid shadowing surprises.
 
 ## Device Selection
 

package/examples/decibri.browser.js

@@ -63,19 +63,21 @@ var decibri = (function() {
 	//#endregion
 	//#region npm/decibri/src/browser/worklet-inline.js
 	var require_worklet_inline = /* @__PURE__ */ __commonJSMin(((exports, module) => {
-		module.exports = { 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" };
+		module.exports = { 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);" };
 	}));
 	//#endregion
 	//#region npm/decibri/src/browser/decibri-browser.js
 	var require_decibri_browser = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		const { Emitter } = require_emitter();
 		const { WORKLET_SOURCE } = require_worklet_inline();
-		const VERSION = "5.5.0";
+		const VERSION = "5.6.0";
 		/**
 		* Browser microphone capture.
 		*
 		* Uses getUserMedia + AudioWorklet for real-time audio capture in browsers.
-		* Emits 'data' events with Int16Array or Float32Array chunks.
+		* Emits 'data' events with Int16Array or Float32Array chunks holding
+		* framesPerBuffer frames of the delivered channel count, interleaved frame
+		* by frame.
 		*
 		* Ported from decibri-web decibri.ts. Logic identical, types removed.
 		*
@@ -101,6 +103,7 @@ var decibri = (function() {
 				const vad = options.vad ?? false;
 				let vadThreshold = .01;
 				let vadHoldoff = 300;
+				let vadSource;
 				if (vad === false) this._vad = false;
 				else if (vad === true) throw new TypeError("vad: true is no longer supported. Specify the mode explicitly: vad: 'energy'.");
 				else if (vad === "energy") this._vad = true;
@@ -117,14 +120,24 @@ var decibri = (function() {
 						if (vad.holdoffMs < 0) throw new RangeError("vad holdoffMs must be non-negative");
 						vadHoldoff = vad.holdoffMs;
 					}
-				} else throw new TypeError(`Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'energy', or a config object { model, threshold, holdoffMs }.`);
+					if (vad.source !== void 0) {
+						const source = vad.source;
+						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");
+						const deliveredChannels = options.channels ?? 1;
+						if (deliveredChannels >= 1 && source >= deliveredChannels) throw new RangeError(`the detector source names delivered channel ${source}; the delivered channel count is ${deliveredChannels}`);
+						vadSource = source;
+					}
+				} else throw new TypeError(`Invalid vad value: ${JSON.stringify(vad)}. Expected false, 'energy', or a config object { model, threshold, holdoffMs, source }.`);
 				this._vadThreshold = vadThreshold;
 				this._vadHoldoff = vadHoldoff;
+				this._vadSource = vadSource;
 				this._vadScore = 0;
 				this._isSpeaking = false;
 				this._silenceTimer = null;
 				this._sampleRate = options.sampleRate ?? 16e3;
 				this._channels = options.channels ?? 1;
+				this._channelMap = options.channelMap;
 				this._framesPerBuffer = options.framesPerBuffer ?? 1600;
 				this._device = options.device;
 				this._dtype = options.dtype ?? "int16";
@@ -133,8 +146,15 @@ var decibri = (function() {
 				this._workletUrl = options.workletUrl;
 				if (this._sampleRate < 1e3 || this._sampleRate > 384e3) throw new RangeError("sample rate must be between 1000 and 384000");
 				if (this._channels < 1) throw new RangeError("channels must be at least 1");
-				if (this._channels > 1) throw new RangeError("multichannel capture is not supported; channels must be 1 (mono)");
-				if (this._channels < 1 || this._channels > 32) throw new TypeError(`channels must be between 1 and 32, got ${this._channels}`);
+				const channelMap = this._channelMap;
+				if (channelMap !== void 0) {
+					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 !== this._channels) throw new RangeError("channelMap must have exactly one entry per channel");
+				}
 				if (this._framesPerBuffer < 64 || this._framesPerBuffer > 65536) throw new TypeError(`frames per buffer must be between 64 and 65536, got ${this._framesPerBuffer}`);
 				if (this._dtype !== "int16" && this._dtype !== "float32") throw new TypeError("dtype must be 'int16' or 'float32'");
 			}
@@ -190,6 +210,9 @@ var decibri = (function() {
 			/**
 			* 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, or to the one delivered channel a `vad: { source }` names,
+			* before the RMS, so the score reflects one channel's level.
 			* @returns {number}
 			*/
 			get vadScore() {
@@ -215,7 +238,7 @@ var decibri = (function() {
 				const nativeSampleRate = this._audioContext.sampleRate;
 				await this._audioContext.resume();
 				const audioConstraints = {
-					channelCount: this._channels,
+					channelCount: { ideal: 32 },
 					echoCancellation: this._echoCancellation,
 					noiseSuppression: this._noiseSuppression
 				};
@@ -229,6 +252,29 @@ var decibri = (function() {
 					this.emit("error", error);
 					throw error;
 				}
+				if (this._channelMap !== void 0 || this._channels > 1) {
+					const track = this._stream.getAudioTracks()[0];
+					const granted = (track && typeof track.getSettings === "function" ? track.getSettings() : {}).channelCount;
+					if (typeof granted === "number") {
+						let message = null;
+						if (this._channelMap !== void 0) {
+							for (const entry of this._channelMap) if (entry >= granted) {
+								message = `the channel map names device channel ${entry}; the device reports ${granted} input channels`;
+								break;
+							}
+						} else if (this._channels > granted) message = `the input device does not support ${this._channels} delivered channels; it reports ${granted}`;
+						else if (this._channels < granted) message = `a channel map is required to deliver ${this._channels} of the device's ${granted} input channels`;
+						if (message !== null) {
+							this._stream.getTracks().forEach((t) => t.stop());
+							this._stream = null;
+							await this._audioContext.close();
+							this._audioContext = null;
+							const error = new Error(message);
+							this.emit("error", error);
+							throw error;
+						}
+					}
+				}
 				let blobUrl = null;
 				const workletUrl = this._workletUrl ?? (blobUrl = this._createBlobUrl());
 				try {
@@ -249,11 +295,21 @@ var decibri = (function() {
 					framesPerBuffer: this._framesPerBuffer,
 					format: this._dtype,
 					nativeSampleRate,
-					targetSampleRate: this._sampleRate
+					targetSampleRate: this._sampleRate,
+					channels: this._channels,
+					channelMap: this._channelMap ?? null
 				} });
 				this._workletNode.port.onmessage = (event) => {
-					const buffer = event.data;
-					const chunk = this._dtype === "int16" ? new Int16Array(buffer) : new Float32Array(buffer);
+					const data = event.data;
+					if (!(data instanceof ArrayBuffer)) {
+						if (data && data.type === "error") {
+							const error = new Error(data.message);
+							this.emit("error", error);
+							this.stop();
+						}
+						return;
+					}
+					const chunk = this._dtype === "int16" ? new Int16Array(data) : new Float32Array(data);
 					this.emit("data", chunk);
 					if (this._vad) this._processVad(chunk);
 				};
@@ -295,10 +351,35 @@ var decibri = (function() {
 				}, this._vadHoldoff);
 			}
 			_computeRms(chunk) {
-				let sum = 0;
 				const n = chunk.length;
 				if (n === 0) return 0;
-				if (chunk instanceof Float32Array) for (let i = 0; i < n; i++) sum += chunk[i] * chunk[i];
+				const channels = this._channels;
+				const isFloat = chunk instanceof Float32Array;
+				if (channels > 1) {
+					const frames = Math.floor(n / channels);
+					if (frames === 0) return 0;
+					const source = this._vadSource;
+					let sum = 0;
+					if (source !== void 0) {
+						for (let f = 0; f < frames; f++) {
+							const s = isFloat ? chunk[f * channels + source] : chunk[f * channels + source] / 32768;
+							sum += s * s;
+						}
+						return Math.sqrt(sum / frames);
+					}
+					for (let f = 0; f < frames; f++) {
+						let acc = 0;
+						for (let c = 0; c < channels; c++) {
+							const s = isFloat ? chunk[f * channels + c] : chunk[f * channels + c] / 32768;
+							acc = Math.fround(acc + s);
+						}
+						const mono = Math.fround(acc / channels);
+						sum += mono * mono;
+					}
+					return Math.sqrt(sum / frames);
+				}
+				let sum = 0;
+				if (isFloat) for (let i = 0; i < n; i++) sum += chunk[i] * chunk[i];
 				else for (let i = 0; i < n; i++) {
 					const s = chunk[i] / 32768;
 					sum += s * s;

package/index.d.ts

@@ -33,8 +33,10 @@ export declare class DecibriBridge {
    * Queue far-end reference audio for the echo canceller. `buffer` is mono
    * PCM bytes in the bridge's configured format, at the declared reference
    * rate, in played order. Never blocks and never fails: a full queue
-   * discards and counts rather than erroring, and a push with no active
-   * stream (not started, stopped, or echo cancellation off) is a no-op.
+   * discards and counts rather than erroring. A push with no active stream
+   * (not started, or stopped) is discarded and counted into the
+   * `referenceDropped` metric when a canceller is configured; with echo
+   * cancellation off it is a no-op.
    */
   pushAecReference(buffer: Buffer): void
   /**
@@ -42,6 +44,11 @@ export declare class DecibriBridge {
    * reference queue's own counters, or `null` when no stream is active or
    * echo cancellation is off. Counters are returned as f64 (exact JS numbers
    * for any realistic count), matching the `overrunCount` getter.
+   *
+   * The top-level engine fields report the first delivered channel's
+   * canceller; `channels` carries every delivered channel's engine report in
+   * delivered order, one entry per channel, so the two agree on a
+   * single-channel stream.
    */
   aecMetrics(): AecMetricsJs | null
   /** List all available audio input devices. */
@@ -126,8 +133,9 @@ export declare class FileHandle {
    */
   static openAsync(path: string, options?: FileOptions | undefined | null): Promise<unknown>
   /**
-   * Wrap in-memory samples as an offline source. `samples` are mono f32 in
-   * [-1.0, 1.0]; `inputRate` is their native rate (raw samples carry no
+   * Wrap in-memory samples as an offline source. `samples` are f32 in
+   * [-1.0, 1.0], frame-interleaved at the options' `inputChannels` (1
+   * when unset); `inputRate` is their native rate (raw samples carry no
    * header). No I/O, so construction is synchronous.
    */
   static buffer(samples: Float32Array, inputRate: number, options?: FileOptions | undefined | null): FileHandle
@@ -173,6 +181,49 @@ export declare class FileHandle {
   get inputRate(): number
 }
 
+/**
+ * One delivered channel's canceller report inside `AecMetricsJs.channels`.
+ * Engine-level fields only: the reference queue's counters (`referenceDropped`,
+ * `referenceSilence`) describe the shared queue and stay on the top level.
+ */
+export interface AecChannelMetricsJs {
+  /**
+   * 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
+  /**
+   * 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
+}
+
 /**
  * Echo-cancellation metrics returned to JS by `aecMetrics()`. One object
  * carries the canceller's own report and the reference queue's counters, so a
@@ -215,10 +266,11 @@ export interface AecMetricsJs {
    */
   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
   /**
@@ -227,6 +279,15 @@ export interface AecMetricsJs {
    * fault: 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: Array<AecChannelMetricsJs>
 }
 
 /**
@@ -257,6 +318,15 @@ export interface AecMetricsJs {
 export interface DecibriOptions {
   sampleRate?: number
   channels?: number
+  /**
+   * Capture channel map: 0-based device channel indices, one per delivered
+   * channel (the shape of CoreAudio AUHAL's channel map, an index list, not
+   * miniaudio's spatial `channelMap`). Absent delivers the documented
+   * average of every opened channel. Entries are validated against the
+   * resolved device's own report when the stream starts; no fixed maximum
+   * exists.
+   */
+  channelMap?: Array<number>
   framesPerBuffer?: number
   format?: string
   device?: any
@@ -351,8 +421,10 @@ export interface DeviceInfoJs {
   name: string
   /**
    * Stable per-host device ID suitable for `device: { id: ... }` selection.
-   * WASAPI endpoint ID on Windows, CoreAudio UID on macOS, ALSA pcm_id on
-   * Linux. Empty string if cpal cannot produce a stable ID for this device.
+   * The lowercase host name, a colon, then the platform device identifier:
+   * `wasapi:` then the endpoint ID on Windows, `coreaudio:` then the device
+   * UID on macOS, `alsa:` then the PCM identifier on Linux. Empty string if
+   * cpal cannot produce a stable ID for this device.
    */
   id: string
   maxInputChannels: number
@@ -362,14 +434,21 @@ export interface DeviceInfoJs {
 
 /**
  * Options passed from the JS `File` wrapper. The conditioning fields mirror
- * `DecibriOptions` exactly; the live-capture-only fields (device, channels,
- * framesPerBuffer) do not apply to an offline source. `vadThreshold` and
- * `vadHoldoffMs` are internal plumbing (the user passes them on the `vad`
- * config object; the wrapper resolves them), hidden from the generated
- * TypeScript like `ortLibraryPath`.
+ * `DecibriOptions` exactly, as do `channels` and `channelMap`, with the
+ * source's own channel count standing where the device's report stands; the
+ * live-capture-only fields (device, framesPerBuffer) do not apply to an
+ * offline source. `inputChannels` is the interleave of the caller's own
+ * samples and is honoured by `FileHandle::buffer` alone (a path's count
+ * comes from its header; the JS wrapper refuses the option on the open
+ * path). `vadThreshold` and `vadHoldoffMs` are internal plumbing (the user
+ * passes them on the `vad` config object; the wrapper resolves them),
+ * hidden from the generated TypeScript like `ortLibraryPath`.
  */
 export interface FileOptions {
   sampleRate?: number
+  channels?: number
+  channelMap?: Array<number>
+  inputChannels?: number
   format?: string
   vadMode?: string
   modelPath?: string