decibri 5.4.0 → 5.6.0

package/CHANGELOG.md

@@ -9,6 +9,71 @@ 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
+
+- **The `RangeError` thrown for a `channels` count below 1 carries the message `channels must be at least 1`.** It carried `channels must be between 1 and 32`, naming an upper bound that neither `Microphone` nor `Speaker` enforces. Code that matches the message text exactly stops matching and has to be updated to the new text. Nothing else about the error moves: it is still a `RangeError`, thrown for the same input, `channels: 0` on either constructor or `open()`.
+- **`Speaker` accepts a `channels` count above 32.** It threw `RangeError: channels must be between 1 and 32` from the constructor. It now accepts any count above zero, offers the count to the device when playback starts, and a device that cannot serve it emits a `DecibriError` with code `SPEAKER_CHANNELS_UNSUPPORTED` on the `'error'` event, or rejects `writeAsync()` with it. Code that relied on the constructor throwing to reject an unsupported output channel count has to handle the failure asynchronously instead, on `'error'` or the rejection. `new Speaker({ channels: 0 })` still throws a `RangeError` from the constructor, and a count above 16383 still carries `STREAM_OPEN_FAILED` naming that limit. How many channels a device serves depends on the `sampleRate` asked for as well as the count.
+- **An output channel count above the device's reported figure carries `SPEAKER_CHANNELS_UNSUPPORTED`.** It carried `STREAM_OPEN_FAILED`. Code branching on `STREAM_OPEN_FAILED` to detect an unsupported output channel count has to match `SPEAKER_CHANNELS_UNSUPPORTED` as well, and cannot drop `STREAM_OPEN_FAILED`, because a device that reports no figure at all keeps `STREAM_OPEN_FAILED` for the same condition. `STREAM_OPEN_FAILED` is otherwise unchanged and remains the code for an output open that failed for any other reason.
+- **The browser `Microphone` rejects a `channels` count above 1.** It accepted 1 to 32 and delivered the first channel only, with nothing to indicate the rest were dropped. A count above 1 now throws `RangeError: multichannel capture is not supported; channels must be 1 (mono)`, and a count below 1 throws `RangeError: channels must be at least 1` where it threw a `TypeError`. Code passing a count above 1 to the browser entry has to pass 1 and mix down its own sources, or read the single channel it was already receiving. `channels: 1` is unchanged, as is every other browser `Microphone` option. Both class and message now match the Node entry's for the same values, so the two entries reject the same input the same way.
+- The browser `Speaker` is unchanged. It still accepts 1 to 32 channels, the range the Web Audio specification requires an implementation to support, and keeps its own `channels must be between 1 and 32, got <n>` message, which that range does enforce.
+
+### Added
+
+- Error code `SPEAKER_CHANNELS_UNSUPPORTED` on `DecibriError`, for an output device that cannot serve the requested `channels`. The message names the count asked for, the count the device reports (the figure `SpeakerInfo.maxOutputChannels` carries) and the platform's own message.
+- `referenceChannels` on the `aec` option object: the channel count of the far-end reference pushed through `pushAecReference`. Default 1 (mono). With a count above 1 the pushed samples are read as interleaved frames and each frame is averaged to one mono sample before the canceller sees it. The collapse is opt-in: a caller pushing a multichannel reference must declare the count, and an undeclared multichannel push keeps its current behaviour, cancelling nothing and reporting no error. The declared count must match the pushed buffer: a mismatch is not detected and raises no error, and shows up only as `aecMetrics().delaySamples` staying `null` with no fault reported. A count below 1 throws a `RangeError`; the only ceiling is the option's own 16-bit carrier. A mono reference against playback through more than one loudspeaker has a cancellation ceiling: the canceller models one room response applied to the channel average, so a placement where the per-loudspeaker echo paths differ leaves a residual that adaptation does not remove.
+- Each of the four platform packages (`@decibri/decibri-win32-x64-msvc`, `@decibri/decibri-darwin-arm64`, `@decibri/decibri-linux-x64-gnu`, `@decibri/decibri-linux-arm64-gnu`) now includes `THIRD-PARTY-NOTICES.md`, the third-party license notices for the ONNX Runtime dynamic libraries the package carries and for the third-party material incorporated into them, with a source-availability statement for the MPL-2.0-licensed Eigen code they contain.
+- `models/THIRD-PARTY-NOTICES.md`, carrying the origin, version and license text for the two bundled ONNX models together with the training-data attribution the denoise checkpoint requires. It ships beside the weights it covers. `models/README.md` alongside it documents each model's tensor interface and points at the notice.
+
+### Changed
+
+- ONNX Runtime telemetry is disabled on the environment decibri commits when it initializes the runtime, where it was left at ONNX Runtime's own default of enabled. This covers every path that reaches the runtime: `vad: 'silero'` and the ACE `denoise` stage. Set `DECIBRI_ORT_TELEMETRY=1` in the environment before first use to leave it enabled; every other value, an empty value, and an absent variable leave it disabled. Two limits apply on Windows and decibri can close neither. ONNX Runtime logs one process-information event while the environment is being created, before the setting is applied, and logs it once per process, so that event is emitted whichever way the setting is left. The runtime also assigns its telemetry state from the Windows tracing session through an ETW callback, so the platform can re-enable telemetry after decibri has disabled it. On other platforms ONNX Runtime's telemetry provider does nothing. The browser build has no ONNX Runtime and is unaffected. No option, event, method or error text changes.
+
+### Fixed
+
+- The bundled Silero VAD model is documented as v6.2, the version that ships. The `model` field on `VadOptions`, the `vad` option on `MicrophoneOptions`, the README and the notice beside the model named v5. Which model file ships is unchanged.
+- The Silero VAD tensor specification in `models/README.md` names the tensors the model exposes: `input`, `state` and `sr` in, `output` and `stateN` out. It described a four-input form carrying separate `h` and `c` LSTM tensors.
+
 ## [5.4.0] - 2026-08-04
 
 ### Added
@@ -36,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
 
@@ -152,7 +155,7 @@ Creates a Writable stream for speaker playback.
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `sampleRate` | number | 16000 | Playback sample rate (1000 to 384000) |
-| `channels` | number | 1 | Output channels (1 to 32) |
+| `channels` | number | 1 | Output channels (1 or more, up to what the device supports) |
 | `dtype` | `'int16'` \| `'float32'` | `'int16'` | Sample encoding of incoming data |
 | `device` | number, string, or `{ id: string }` | system default | Output device index, case-insensitive name substring, or stable per-host ID |
 
@@ -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
 
@@ -293,7 +296,7 @@ mic.on('silence', () => console.log('silent'));
 
 ### Silero mode
 
-ML-based detection using the Silero VAD v5 model. More accurate than energy mode, especially in noisy environments.
+ML-based detection using the Silero VAD v6.2 model. More accurate than energy mode, especially in noisy environments.
 
 ```javascript
 const mic = new Microphone({ vad: { model: 'silero', threshold: 0.5 } });
@@ -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:
 
@@ -337,17 +340,25 @@ setTimeout(() => mic.stop(), 5000);
 
 VAD reads the signal before the chain, so `vadScore` and the `'speech'` / `'silence'` events are unaffected by which conditioning stages you enable. The conditioning chain runs in the native Node.js capture path; the browser build does not include it.
 
+## ONNX Runtime telemetry
+
+Silero mode (`vad: 'silero'`) and the ACE `denoise` stage run on ONNX Runtime, which carries its own telemetry, separate from anything decibri does. Decibri disables it on the environment it commits when it initializes the runtime. Set `DECIBRI_ORT_TELEMETRY=1` in the environment before first use to leave it enabled; every other value, an empty value, and an absent variable leave it disabled.
+
+Two limits apply on Windows and decibri can close neither, so decibri does not claim that no telemetry is emitted. ONNX Runtime logs one process-information event while the environment is being created, before the setting is applied, and logs it once per process, so that event is emitted whichever way the setting is left. The runtime also assigns its telemetry state from the Windows tracing session through an ETW callback, so the platform can re-enable telemetry after decibri has disabled it. On other platforms ONNX Runtime's telemetry provider does nothing.
+
+Neither ONNX Runtime nor this setting applies to the browser build, which has no ONNX Runtime.
+
 ## API: File (offline source)
 
 Everything a `Microphone` does to live audio, `File` does to audio you already have: the same conditioning options, the same Readable stream of conditioned chunks (finite: it ends at EOF), and the same opt-in `vad`. Because a `File` is a complete recording, it can also analyze the whole recording for speech.
 
 - `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.4.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";
@@ -132,7 +145,16 @@ var decibri = (function() {
 				this._noiseSuppression = options.noiseSuppression ?? true;
 				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 || this._channels > 32) throw new TypeError(`channels must be between 1 and 32, got ${this._channels}`);
+				if (this._channels < 1) throw new RangeError("channels must be at least 1");
+				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'");
 			}
@@ -188,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() {
@@ -213,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
 				};
@@ -227,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 {
@@ -247,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);
 				};
@@ -293,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;