Node.js API

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

Constructor

new Decibri(options?)

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

Standard Node.js ReadableOptions (e.g., highWaterMark) are also accepted.

When vadMode is 'silero', the default vadThreshold changes from 0.01 to 0.5 (probability scale 0.0–1.0). If you explicitly set vadThreshold, your value is used regardless of mode.

Methods

mic.stop()

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

Decibri.devices()

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

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

Each device object contains:

Decibri.version()

Returns version information for decibri and the audio backend. The portaudio key is kept for backward compatibility but the value is the cpal version.

Decibri.version();
// { decibri: '3.0.0', portaudio: 'cpal 0.17' }

Properties

mic.isOpen

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

Events

Stream events

Decibri 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
• 'close': emitted when the stream is closed

'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');
});

'speech'

Requires vad: true. Emitted when the RMS energy of an audio chunk crosses the vadThreshold.

'silence'

Requires vad: true. Emitted when audio stays below vadThreshold for vadHoldoff milliseconds after a speech period.

const mic = new Decibri({ sampleRate: 16000, channels: 1, vad: true });

mic.on('speech', () => console.log('Speech detected'));
mic.on('silence', () => console.log('Silence detected'));

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 Decibri({ sampleRate: 16000, channels: 1, format: 'float32' });

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

DecibriOutput

new DecibriOutput(options?)

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

const Decibri = require('decibri');
const { DecibriOutput } = Decibri;

const speaker = new DecibriOutput(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.end([chunk])

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

speaker.stop()

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

Static methods

DecibriOutput.devices()

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

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

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

Each device object contains:

DecibriOutput.version()

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

Properties

speaker.isPlaying

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

Events