API Reference

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.

Option	Type	Default	Description
sampleRate	number	16000	Samples per second (1,000 to 384,000 Hz)
channels	number	1	Number of input channels (1 to 32)
framesPerBuffer	number	1600	Frames per audio callback. Controls chunk size and latency (64 to 65,536)
device	number | string	system default	Device index from Decibri.devices() or case-insensitive name substring
format	'int16' | 'float32'	'int16'	Sample encoding format
vad	boolean	false	Enable built-in voice activity detection
vadThreshold	number	0.01	RMS energy threshold for speech detection (0 to 1)
vadHoldoff	number	300	Milliseconds of sub-threshold audio before 'silence' is emitted

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

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:

Property	Type	Description
index	number	PortAudio device index, used as options.device
name	string	Human-readable device name reported by the OS
maxInputChannels	number	Maximum number of input channels supported
defaultSampleRate	number	Device's native/preferred sample rate in Hz
isDefault	boolean	Whether this is the current system default input device

Decibri.version()

Returns version information for decibri and the bundled PortAudio library.

Decibri.version();
// { decibri: '1.0.0', portaudio: 'PortAudio V19.7.0-devel...' }

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