Node.js API

Complete reference for the decibri Node.js API. For installation and basic usage, see Getting started.

Constructor

new Microphone(options?)

Creates a Node.js Readable stream that captures raw PCM audio from the system microphone.

The five conditioning options (dcRemoval, denoise, highpass, agc, limiter) are off by default and run as a fixed chain before each chunk is delivered. They are documented in full on the Audio Capture Engine page. Above one delivered channel, DC removal, denoise and the high-pass run on each channel with its own state, while AGC and the limiter are linked: one detector measures across all the channels and one gain is applied to all of them, which keeps the balance between the channels.

Echo cancellation is a separate opt-in capture option, aec, documented in Acoustic Echo Cancellation (AEC) below. It is the one capture option that also needs a second audio stream from you at run time.

Standard Node.js ReadableOptions (e.g., highWaterMark) are also accepted. Voice activity detection (the vad and modelPath options) is documented in the Voice activity detection section below.

To construct without blocking the event loop on the open work (notably the Silero model load when vad: 'silero' is set), use the Microphone.open() async factory.

Channels

channels is a delivered count: the number of channels in every 'data' chunk, interleaved frame by frame, so a chunk holds framesPerBuffer * channels samples. It works the way sampleRate does. The device itself is always opened at its own native channel count, the maxInputChannels figure that Microphone.devices() reports, and Decibri derives the delivered channels from what the device gives it.

Without a channelMap, two counts can be derived:

• channels: 1, the default, delivers the average of every device channel.
• A count equal to the device's own delivers every device channel, in device order.

Any other count above 1 without a map is refused when capture starts, because the device's channel count is only read when the stream opens. A count above the device's own fails with the code MICROPHONE_CHANNELS_UNSUPPORTED, because Decibri cannot deliver a channel the device does not have. A count above 1 but below the device's own fails with CHANNEL_SELECTION_AMBIGUOUS, because it does not say which of the device's channels it means. Both arrive as a DecibriError on the 'error' event, not from the constructor. A channelMap lifts both refusals, because it names every delivered channel.

channelMap names device channels. It is an array of 0-based device channel indices with one entry per delivered channel, so its length must equal channels: delivered channel j carries device channel channelMap[j]. Entries may repeat and their order is significant, so a map can select, reorder and duplicate device channels, and it can deliver more channels than the device has. channelMap: [1] with channels: 1 delivers the device's second channel alone, and channelMap: [1, 0] with channels: 2 swaps a stereo pair. An entry the device does not have fails with CHANNEL_MAP_OUT_OF_RANGE on the 'error' event.

vad.source names a delivered channel. It is a position in the 'data' chunk, counted after channelMap has been applied, and never a device index. Omitted, the detector reads the frame average of every delivered channel; set, it reads that one delivered channel. It must be below channels, and it changes only what the detector reads, not the audio the stream emits.

const { Microphone } = require('decibri');

// Needs a device with at least three input channels.
// Deliver device channels 2 and 0, in that order. source: 0 names
// delivered channel 0, which carries device channel 2.
const mic = new Microphone({
  channels: 2,
  channelMap: [2, 0],
  vad: { model: 'silero', source: 0 },
});

mic.on('error', (err) => console.error(err.code, err.message));
mic.on('data', (chunk) => {
  // Int16 LE frames, interleaved: device channel 2, then device channel 0
});

The constructor checks everything that does not need the device, and Microphone.open() rejects with the same errors. The device checks run when the stream starts, which is when you begin consuming it, so attach an 'error' listener first.

The three device refusals are a DecibriError carrying a code, not a DeviceError. A 'data' handler that reads each chunk as a run of mono samples needs channels: 1; any higher count that the device accepts delivers interleaved frames.

Methods

Microphone.open(options?)

Static async factory. Returns Promise<Microphone>. Runs the open work (device resolution, and the Silero model load when vad: 'silero' is set) on the native thread pool instead of the event loop, then resolves to a ready instance. The synchronous constructor blocks for roughly 100 to 500 milliseconds on a cold Silero load; open() does not. Options are identical to the constructor. A failed open rejects with the matching error: RangeError or TypeError for invalid options, or DeviceError, OrtError, or OrtPathError for native failures.

const mic = await Microphone.open({ vad: 'silero' });
mic.on('data', (chunk) => { /* ... */ });

mic.stop()

Stops microphone capture and ends the stream. Safe to call multiple times; subsequent calls are no-ops.

Microphone.devices()

Returns an array of available audio input devices on the system.

const devices = Microphone.devices();
console.log(devices);
// [
//   { index: 0, name: 'Built-in Microphone', id: '...', maxInputChannels: 1,
//     defaultSampleRate: 44100, isDefault: true },
//   ...
// ]

Each device object contains:

Microphone.version()

Returns version information for decibri and the audio backend. The audioBackend field reports the cpal version, and the binding field reports the npm package version.

Microphone.version();
// { decibri: '<version>', audioBackend: 'cpal <version>', binding: '<version>' }

Properties

mic.isOpen

boolean (read-only). Returns true while the microphone is actively capturing audio.

mic.vadScore

number (read-only). Most recent VAD score for the active mode: the Silero speech probability in 'silero' mode, the normalised RMS of the last chunk in 'energy' mode. Above one delivered channel both modes score the frame average of the delivered channels, or the one channel vad.source names. 0 when VAD is disabled or before the first chunk is processed. This is the raw per-chunk view; the debounced speaking state is surfaced through the 'speech' and 'silence' events. See Voice activity detection.

mic.overrunCount

number (read-only). Number of capture buffers dropped because the consumer could not keep pace. 0 while the consumer keeps up, before capture starts, and after stop(), which releases the stream the counter lives on, so read it before stopping to see a session's total. A rising value means audio is being dropped to bound memory.

Events

Stream events

Microphone extends Node.js Readable, so all standard stream events are available:

• 'data': emitted when audio data is available (callback receives Buffer)
• 'end': emitted when the stream ends (after stop())
• 'error': emitted on microphone errors, including device disconnection (for example unplugging the microphone). When a device fails, isOpen becomes false and the 'error' event fires, rather than capture freezing silently.
• 'close': emitted when the stream is closed

When vad is enabled, the stream additionally emits 'speech' and 'silence'. Those are documented in the Voice activity detection section.

'backpressure'

Emitted when the stream's internal buffer is full and the consumer is reading too slowly. Because a microphone cannot be paused, audio chunks continue to arrive. Drain the stream or drop data to avoid unbounded memory growth.

mic.on('backpressure', () => {
  console.warn('Consumer is too slow, audio may be lost');
});

Voice activity detection

Decibri ships two VAD modes plus a disabled default, selected with the vad option on the Microphone constructor. When VAD is enabled, the microphone emits 'speech' and 'silence' events and updates the vadScore property. Both the energy detector and the Silero model run locally; there is no cloud call.

Both detectors read one mono signal. Above one delivered channel that signal is the frame average of every delivered channel, unless vad.source names one delivered channel for the detector to read instead. vadScore and the 'speech' and 'silence' events describe that signal; the audio the stream emits is not changed by it.

Tuning with a VadOptions object

To tune the threshold or holdoff, or to choose the delivered channel the detector reads, pass a VadOptions object as the vad option instead of a bare mode string. The vad: 'silero' and vad: 'energy' shorthands are equivalent to the object with its default tuning.

const mic = new Microphone({ vad: { model: 'silero', threshold: 0.6, holdoffMs: 200 } });

Speaking state: the 'speech' and 'silence' events

Node surfaces speaking state through events rather than a polled boolean. 'speech' fires when the VAD score crosses the configured threshold. 'silence' fires when the score then stays below the threshold for holdoffMs milliseconds after a speech period. Both require vad to be enabled. Because Microphone is a Readable stream, attach a 'data' listener (or otherwise consume the stream) so audio keeps flowing and the detector runs.

const mic = new Microphone({ sampleRate: 16000, vad: 'energy' });

mic.on('speech', () => console.log('Speech detected'));
mic.on('silence', () => console.log('Silence detected'));
mic.on('data', () => {}); // keep the stream flowing so VAD runs

For the raw per-chunk signal, read the mic.vadScore property documented above. vadScore is the underlying score; the 'speech' and 'silence' events are the debounced state derived from it via the threshold and holdoff.

Bundled Silero model

The Silero VAD ONNX model and ONNX Runtime ship inside the npm package. No separate download, no API key, and no system onnxruntime dependency are required for vad: 'silero'. To use a different Silero ONNX variant, pass an absolute path on the modelPath option; it is consulted only when vad is 'silero'.

ONNX Runtime telemetry

The Silero detector and the denoise conditioning stage run on ONNX Runtime, which carries its own telemetry, separate from anything Decibri does. Decibri disables it when it initialises the runtime. Set DECIBRI_ORT_TELEMETRY=1 in the environment before the first load to leave it enabled; any other value, an empty value, and an absent variable leave it disabled.

Two limits apply on Windows, and Decibri can close neither, so it does not claim that no telemetry is emitted. ONNX Runtime logs one process-information event while its environment is being created, before the setting is applied, once per process, so that event is emitted whichever way the setting is left. The runtime also takes 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.

Acoustic Echo Cancellation (AEC)

Echo cancellation removes the sound of your own loudspeaker from the microphone capture. It is opt-in through the aec option on the Microphone constructor. Unlike every other capture option, it also needs a second audio stream at run time: the audio you are playing, pushed block by block for as long as you are playing it.

The plumbing, the diagnostics procedure, and the limits of the technique are on the Acoustic Echo Cancellation (AEC) feature page. This section is the Node.js surface.

The aec option

The declared signature is aec?: 'tau' | AecOptions.

const { Microphone } = require('decibri');

// Short form: the model with its defaults.
const a = new Microphone({ sampleRate: 16000, aec: 'tau' });

// Object form: the same model, every option set to its default.
const b = new Microphone({
  sampleRate: 16000,
  aec: {
    model: 'tau',
    tailMs: 200,
    suppression: 'conservative',
    referenceSampleRate: 16000,
    referenceChannels: 1,
  },
});

Echo cancellation requires sampleRate between 8000 and 48000, narrower than the range sampleRate otherwise accepts. It runs on every delivered channel: one canceller per delivered channel, each fed the same pushed reference and each finding its own channel's echo delay, so its processing cost grows with channels. It is available on native capture only and is not a File option. The browser build does not carry it; browser capture has the browser's own echoCancellation constraint instead, which is on by default. See the Browser API.

AecOptions

interface AecOptions {
  model: 'tau';                                // required in the object form
  tailMs?: number;                             // 16 to 500, default 200
  suppression?: 'conservative' | 'off';        // default 'conservative'
  referenceSampleRate?: number;                // 1000 to 384000, default: the capture rate
  referenceChannels?: number;                  // at least 1, default 1
}

The declared referenceChannels must match what you push. A mismatch is not detected and throws nothing: the frames are misread, nothing is cancelled, and aecMetrics().delaySamples stays null. The canceller reads one mono reference, so with playback through more than one loudspeaker whose echo paths differ, some echo remains that adaptation does not remove.

Methods

mic.pushAecReference(data)

Signature pushAecReference(data: Buffer | NodeJS.ArrayBufferView): void. Push the audio you played, as you played it, in the order it was played, in the same dtype the microphone was constructed with, interleaved at referenceChannels (mono by default). Pass a Buffer, Uint8Array or DataView of PCM bytes, or the typed array that carries the configured dtype: Int16Array for 'int16', Float32Array for 'float32'. One push serves every delivered channel.

The push method never blocks and never throws on a full queue. Samples that do not fit are discarded and counted in referenceDropped. A push made while capture is not running, before it starts or after stop(), is discarded too and added to referenceDropped, which you can read once capture runs. With the option unset, a push does nothing and is not counted. A bad input type, including a typed array of the other dtype, throws TypeError regardless of capture state. Because a Microphone stream starts when you begin consuming it, push from inside your 'data' handler or your playback loop, not immediately after the constructor returns.

mic.aecMetrics()

Signature aecMetrics(): AecMetrics | null. Returns null when the aec option is unset or capture is not running, and an AecMetrics otherwise. Read it while capture is still running; after stop() it returns null.

AecMetrics

interface AecMetrics {
  delaySamples: number | null;
  erleDb: number;
  doubleTalk: boolean;
  referenceStarved: number;
  acquisitionParked: number;
  referenceReanchors: number;
  referenceDropped: number;
  referenceSilence: number;
  channels: AecChannelMetrics[];
}

The first six fields report the canceller on the first delivered channel. referenceDropped and referenceSilence describe the one reference queue that every channel's canceller shares. On a one-channel capture, channels holds a single entry that agrees with the top-level fields.

The diagnostics section of the feature page reads these fields as a procedure rather than a field list. This is that procedure as code:

function diagnose(mic) {
  const m = mic.aecMetrics();

  if (m === null) {
    return 'echo cancellation is off, or capture is not running';
  }
  if (m.delaySamples !== null) {
    return `aligned at ${m.delaySamples} samples, double talk ${m.doubleTalk}`;
  }
  if (m.referenceSilence >= m.acquisitionParked) {
    return 'no reference is reaching the canceller';
  }
  if (m.referenceDropped > 0) {
    return 'pushes are being discarded: push smaller blocks, in step with playback, while capture runs';
  }
  return 'reference is arriving but nothing has aligned: check the rate';
}

AecChannelMetrics

One entry of AecMetrics.channels: the report of the canceller on one delivered channel. It carries the six canceller fields and not the two queue counters, which stay on AecMetrics. Declared as a TypeScript type.

interface AecChannelMetrics {
  delaySamples: number | null;
  erleDb: number;
  doubleTalk: boolean;
  referenceStarved: number;
  acquisitionParked: number;
  referenceReanchors: number;
}

Each channel's canceller finds its own echo delay, so the entries differ where the channels' acoustic paths differ. erleDb is not a ranking across channels: it rises with echo distance, because a weaker echo is easier to reduce in ratio terms, so a far microphone can report a higher figure than a near one while removing less echo in absolute terms. Compare a channel with its own history, not with its neighbours.

AEC errors

Node follows its own convention: built-in TypeError and RangeError for argument validation, and a decibri class carrying a code for everything else. The two bindings raise different classes on purpose; catch them in the idiom of the language you are in, not in a shape shared across both.

Every one of these is raised by the Microphone constructor, except the two pushAecReference rows, which the push itself throws. DecibriError is exported from the package and satisfies instanceof; the RangeError and TypeError cases are built-ins and do not.

Audio format

Int16 (default)

Each 2 bytes represents one 16-bit signed integer sample, little-endian. Range: -32,768 to 32,767.

mic.on('data', (chunk) => {
  const samples = new Int16Array(chunk.buffer, chunk.byteOffset, chunk.length / 2);
});

Float32

Each 4 bytes represents one 32-bit IEEE 754 float sample, little-endian. Range: approximately -1.0 to 1.0.

const mic = new Microphone({ sampleRate: 16000, channels: 1, dtype: 'float32' });

mic.on('data', (chunk) => {
  const samples = new Float32Array(chunk.buffer, chunk.byteOffset, chunk.length / 4);
});

Speaker

new Speaker(options?)

Creates a Node.js Writable stream for speaker playback. Extends Writable from the stream module.

const { Speaker } = require('decibri');

const speaker = new Speaker(options?);

Standard Node.js WritableOptions are also accepted.

Methods

speaker.write(chunk)

Writes PCM data for playback. Returns boolean. If false, the buffer is full; wait for the 'drain' event before writing more.

speaker.writeAsync(chunk)

Returns Promise<void>. Writes PCM audio without blocking the event loop, performing the backpressure wait (when the native playback queue is full) on the native thread pool, and resolves when the samples are queued. This is an opt-in alternative to write(); do not interleave it with write() or pipe() on the same instance, and await calls sequentially to preserve sample order.

speaker.end([chunk])

Graceful stop. Plays all remaining buffered audio, then emits 'finish'. Optionally accepts a final chunk to write before ending.

speaker.drainAsync()

Returns Promise<void>. Waits for all queued audio to finish playing without blocking the event loop, resolving when the buffer has drained (immediately if nothing was written). Pair with writeAsync() for a fully non-blocking playback path.

speaker.stop()

Immediate stop. Discards remaining buffered audio and releases resources. Does not emit 'finish'. Safe to call multiple times.

Static methods

Speaker.open(options?)

Static async factory, symmetric with Microphone.open(). Returns Promise<Speaker>. The speaker loads no model, so the only open work is device resolution; the factory is provided so async callers can use one construction pattern across both classes. A failed open (for example an unknown device) rejects with the matching error.

Speaker.devices()

Returns an array of available audio output devices on the system.

const { Speaker } = require('decibri');

const devices = Speaker.devices();
console.log(devices);
// [
//   { index: 0, name: 'Speakers', id: '...', maxOutputChannels: 2,
//     defaultSampleRate: 48000, isDefault: true },
//   ...
// ]

Each device object contains:

Speaker.version()

Returns version information. Same as Microphone.version().

Properties

speaker.isPlaying

boolean (read-only). Returns true while audio is being output to the speaker.

speaker.underrunCount

number (read-only). Number of samples played as silence because the playback queue ran dry. 0 while the producer keeps the queue fed, or before playback starts. A rising value means the output is filling gaps with silence.

Events

File

Offline audio source. A File runs a recording, or samples you already hold, through the same conditioning chain as Microphone and delivers it as a finite Readable stream that ends at EOF. Because a recording has an end, it can also score the whole thing for speech in one pass with analyze(). The feature page is Audio File Processor (AFP).

new File(path, options?)

Opens an audio file synchronously: the read, the decode, and the chain construction all happen inline, so this blocks the event loop on disk I/O and throws from the constructor on a bad path. Fine for a script; prefer File.open() in servers. path must be a string; anything else throws TypeError: path must be a string. WAV, AIFF, AIFF-C and FLAC are read, identified from the file's own bytes rather than its extension; see the format table for the encodings each container carries.

Omit an option, or pass undefined, to leave that stage off. The live-capture-only options (device, framesPerBuffer, aec) do not apply to an offline source. channels, channelMap and vad.source do, following the Microphone rules in Channels with the source's own channel count standing where the device's stands: the file's header for a path, or inputChannels for File.buffer. That count is known as soon as the source is opened, so every channel refusal throws from the constructor, or rejects File.open(). Standard Node.js ReadableOptions such as highWaterMark are accepted, because FileOptions extends them. The package's own TypeScript declarations ship with it, so FileOptions and FileBufferOptions type-check in an editor without a separate @types package.

File.open(path, options?)

Static async factory. Returns Promise<File>. Runs the disk read, the decode, and the chain construction on the native thread pool instead of the event loop, then resolves to a ready instance. Options are identical to the constructor. This is the recommended form, mirroring Microphone.open().

const { File } = require('decibri');

const file = await File.open('clip.wav', { denoise: 'fastenhancer-t', agc: -18 });

for await (const chunk of file) {
  handle(chunk); // Buffer of conditioned Int16 LE PCM
}
file.close();

File.buffer(samples, options)

Wraps in-memory samples instead of reading a file. samples must be a Float32Array of samples in -1.0 to 1.0, frame-interleaved at options.inputChannels; a raw Buffer of PCM bytes is rejected as ambiguous, with its own message. Raw samples carry no header, so options.inputRate (their native rate, 1,000 to 384,000) is required, and options.inputChannels (1 to 65,535, default 1) is its channel counterpart. The sample count must be a whole number of frames at inputChannels. channels and channelMap then choose what is delivered from those input channels. inputChannels belongs to File.buffer alone; the path constructors refuse it, because a file carries its own count. No I/O is involved, so unlike File.open() this one is synchronous and returns a File directly, not a promise.

const { File } = require('decibri');

// samples: a Float32Array of mono samples in -1.0 to 1.0, at their own rate
const file = File.buffer(samples, { inputRate: 48000, sampleRate: 16000 });

file.on('data', (chunk) => handle(chunk));

// pairs: stereo samples interleaved L, R, L, R, ... Deliver both channels.
const stereo = File.buffer(pairs, { inputRate: 48000, inputChannels: 2, channels: 2 });

This is also the route for any audio the reader rejects, an MP3 or an Opus file for example: decode it yourself, convert to floats in -1.0 to 1.0, interleaved frame by frame, and pass the source rate as inputRate and its channel count as inputChannels. WAV, AIFF, AIFF-C and FLAC do not need it; the path constructors open those directly.

Single-pass lifecycle

Streaming, analysis and saving are three alternatives, and each reads the source from beginning to end. Use one File per operation.

• Asking the stream for data engages it, and analyze() is refused from that point on with a DecibriError carrying the code FILE_ENGAGED. resume(), read(), and attaching a 'data' or 'readable' listener all engage it, synchronously with your own call, whether or not any chunk has arrived yet. pause() on its own and prependListener() do not.
• save() follows the same rule and checks it in the same order: on an engaged stream it rejects with FILE_ENGAGED before any option is interpreted, so a bad format on an engaged File reports the engagement rather than the option.
• A second pass reports FILE_CONSUMED. That covers calling analyze() twice, saving twice, and streaming a File that has already been analysed or saved.
• Streaming a File that has been drained or closed yields nothing rather than erroring. Only a second pass reports the consumed state.
• An analyze() or save() rejected before it touched the source leaves the File streamable: the no-VAD and energy-mode refusals, and a rejected save option, all return before the pass begins, and no 'error' event is emitted.
• close() is idempotent, and the three properties keep returning their pre-close values afterwards.

Methods

file.analyze() and file.analyse()

Score the whole recording for voice activity in one pass, off the event loop. Returns Promise<VadReport>, a plain object with exactly the keys scores and segments, all times in seconds of file time. Requires vad: 'silero'. Above one delivered channel it scores the frame average of the delivered channels, or the one channel vad.source names. analyse() is the same analysis under the other spelling.

const file = await File.open('clip.wav', { vad: 'silero' });
const report = await file.analyze();

report.scores;   // [{ start, end, vadScore, isSpeech }, ...]
report.segments; // [{ start, end }, ...]

scores holds one entry per analysis window. Windows tile the recording from zero, contiguous and non-overlapping, 0.032 seconds each; a trailing remainder shorter than one window is left unscored. segments holds the merged speech regions: consecutive speech windows whose silence gaps fall within the holdoff collapse into one, and a segment ends at its last speech window rather than at the holdoff expiry.

file.save(path, options?)

Run the recording once through the conditioning chain, whole, and write it to path, off the event loop. Returns Promise<SaveReport>. The pass consumes the source exactly as analyze() does. Output is 16-bit PCM at sampleRate, in every one of the three containers, at the delivered channel count and interleaved: the same layout the stream emits, so one channel unless channels asks for more. Each container's own channel ceiling applies, and a save above it rejects with AUDIO_FORMAT_UNSUPPORTED, carrying the container layer's own text: FLAC carries at most 8 channels, and a 16-bit WAV at most 32767. Decibri adds no ceiling of its own.

The container comes from the extension: .wav, .aiff, .aif, .aifc or .flac, matched ASCII case-insensitively. .aifc writes a plain AIFF. An unrecognised extension, or a path with no extension, rejects with AUDIO_FORMAT_UNSUPPORTED rather than defaulting. Decibri reads a file by its content and writes one by its name.

SaveOptions:

SaveReport is a plain object with exactly two keys. clippedSamples counts finite samples that fell outside full scale and were clamped to -1.0 to 1.0: AGC without a limiter can push conditioned audio past full scale, and 16-bit PCM cannot hold it, so Decibri clamps and counts rather than clipping silently. nonFiniteSamples counts non-finite samples the save itself repaired on the way out, a NaN written as silence and an infinity as full scale. That repair and its count cover only the direct path, a one-channel source already at the target rate with no channel map and no conditioning. In every other case the conditioning chain runs and has already replaced each non-finite sample with silence at its entry, so the file carries silence there and the count does not include it.

const file = await File.open('noisy.wav', {
  denoise: 'fastenhancer-t',
  agc: -18,
  limiter: -1.0,
});
const report = await file.save('clean.flac', { compression: 8 });

report.clippedSamples;    // number
report.nonFiniteSamples;  // number

file.close()

Releases the source. Idempotent; a closed File reads as ended.

Properties

file.sampleRate

number (read-only). The target output rate every delivered chunk carries.

file.inputRate

number (read-only). The source's own rate, read from the file's header or taken from the inputRate passed to File.buffer. Differs from sampleRate whenever the recording is resampled.

file.vadScore

number (read-only). Most recent per-chunk VAD score for the active mode, computed on the signal before conditioning. 0 when VAD is disabled or before the first chunk.

Events

File extends Readable, so the standard stream events apply: 'data' (payload Buffer), 'end' at EOF, 'error', and 'close'. When vad is enabled it additionally emits 'speech' and 'silence', the same pair the Microphone emits, with the holdoff measured in file time rather than wall-clock time.

const file = await File.open('clip.wav', { vad: 'silero' });

file.on('speech', () => console.log('speech starts'));
file.on('silence', () => console.log('speech ends'));
file.on('error', (err) => console.error(err.code, err.message));

file.on('data', (chunk) => {
  // file.vadScore holds the score for the chunk just delivered
});

A freshly constructed File has no listeners of its own, so nothing is subscribed for you.

File errors

The same split the rest of the Node API uses. Failures that crossed the native boundary are a DecibriError with a stable code, apart from the argument checks the native layer shares with the wrapper, which arrive as the same built-in the wrapper throws; failures the JavaScript wrapper caught first are built-in RangeError or TypeError with code undefined.

With a code:

Without a code, raised by the wrapper before the native layer is reached, apart from the last row, which the native layer checks:

AudioWriter

A file sink for PCM audio: the Writable to pair with decibri's Readable sources, and with any other stream of PCM bytes such as a TTS engine or a decoded network stream. It collects the whole stream, then writes it as one audio file when the stream finishes. What it writes is what File.save() writes: the same containers from the same extension rule, the same 16-bit PCM encoding, the same clamp and non-finite handling, the same bytes. Nothing reaches disk before then, so the whole stream is held in memory: an hour of 16 kHz mono 'int16' arrives as roughly 115 MB of bytes, and the write converts them to 32-bit floats before encoding, so the peak is a multiple of that. File.save() holds its recording the same way; neither route streams to disk.

new AudioWriter(path, options)

path must be a string, and its extension names the container unless format overrides it. options is required, because sampleRate is. Every option is validated in the constructor, so a bad one throws there rather than surfacing as a deferred 'error' event after the audio has already been streamed. AudioWriterOptions extends SaveOptions, so format and compression are accepted here with the same meanings they have on file.save(), and it extends Node's WritableOptions, so highWaterMark is accepted too.

writer.report

SaveReport | null (read-only). The clippedSamples and nonFiniteSamples counts of the completed write, exactly as file.save() resolves them. For a writer, the direct path that nonFiniteSamples covers is a one-channel stream; above one channel the non-finite samples are written as silence and not counted. null until 'finish' has fired, because the file is written when the stream finishes. A failure destroys the stream with the error rather than populating the report.

const { pipeline } = require('node:stream/promises');
const { File, AudioWriter } = require('decibri');

const file = await File.open('noisy.wav', { denoise: 'fastenhancer-t' });
const writer = new AudioWriter('clean.flac', { sampleRate: 16000 });

await pipeline(
  file,
  writer,
);

writer.report; // { clippedSamples, nonFiniteSamples }, populated after 'finish'

Module-level helpers

Convenience functions exported directly from the decibri package.

inputDevices()

Shortcut for Microphone.devices(). Returns a MicrophoneInfo[].

outputDevices()

Shortcut for Speaker.devices(). Returns a SpeakerInfo[].

version()

Returns the same VersionInfo ({ decibri, audioBackend, binding }) as Microphone.version().

const { inputDevices, outputDevices, version } = require('decibri');

const inputs = inputDevices();
const outputs = outputDevices();
console.log(version());

Errors

Decibri surfaces failures in three ways in Node, depending on when they occur.

Constructor argument validation

Invalid options throw a built-in RangeError or TypeError synchronously from the constructor (and reject the Microphone.open() or Speaker.open() promise), before any device is opened.

Native failures

Failures from the native layer throw DecibriError or one of its subclasses, each carrying a stable string code. These are thrown from the synchronous constructor and rejected from Microphone.open() or Speaker.open().

Catch DecibriError to handle any native failure generically, or a subclass for finer control. Argument validation (above) throws built-in RangeError or TypeError, not a DecibriError. If the Silero model file (the bundled one, or the one modelPath names) or the bundled denoise model file cannot be found at construction, an OrtError is thrown, with the code VAD_MODEL_LOAD_FAILED for the Silero model and MODEL_LOAD_FAILED for the denoise model.

Runtime stream errors

Errors after capture has started, such as a mid-stream device disconnect (unplugging the microphone), are surfaced through the 'error' event rather than thrown. When a device fails, isOpen becomes false and the 'error' event fires, rather than capture freezing silently.

The checks that need the opened device arrive the same way. A Microphone reports MICROPHONE_CHANNELS_UNSUPPORTED, CHANNEL_SELECTION_AMBIGUOUS and CHANNEL_MAP_OUT_OF_RANGE on 'error' when you begin consuming it (see Channels). A Speaker opens its stream at the first write and reports SPEAKER_CHANNELS_UNSUPPORTED there, on 'error', or as the rejection of writeAsync(). Each is a DecibriError carrying that code.