Browser API

Decibri includes browser support via conditional exports. When imported in a browser bundle (webpack, vite, etc.), it uses getUserMedia and AudioWorklet to capture raw PCM audio chunks in real-time. Same API as the Node.js version, same npm package.

Quickstart

Install

Quick start

Capture microphone audio and log the chunk size:

import { Decibri } from 'decibri';

const mic = new Decibri({ sampleRate: 16000 });

mic.on('data', (chunk) => {
  console.log(`Received ${chunk.length} samples`);
});

await mic.start();

start() must be called from a user gesture (click/tap) in Safari. Each chunk contains 100 ms of audio by default (1,600 frames at 16 kHz).

Permission handling

Microphone access requires HTTPS (or localhost). The browser will show a permission prompt when start() is called.

• If the user denies permission, start() rejects with Error('Microphone permission denied')
• The 'error' event also fires with the same error
• Device labels from Decibri.devices() may be empty before permission is granted

Stopping and cleanup

mic.stop();

stop() releases all resources: MediaStream tracks are stopped, AudioContext is closed, all nodes are disconnected, references are nulled. Safe for React/Vue component unmount cycles. Safe to call multiple times or before start().

To restart after stopping:

await mic.start(); // creates a fresh audio pipeline

Device selection

// Start first to trigger permission, then enumerate with labels
await mic.start();
const devices = await Decibri.devices();
console.log(devices);
// [{ deviceId: 'abc123', label: 'Built-in Microphone', groupId: 'g1' }, ...]

// Use a specific device
const usbMic = new Decibri({ device: devices[1].deviceId });
await usbMic.start();

Output formats

// Int16 PCM (default) - ready for most STT engines
const mic = new Decibri({ format: 'int16' });
mic.on('data', (chunk) => {
  // chunk is an Int16Array
});

// Float32 - native browser format, no conversion
const mic2 = new Decibri({ format: 'float32' });
mic2.on('data', (chunk) => {
  // chunk is a Float32Array
});

Voice activity detection

Enable the built-in VAD to receive 'speech' and 'silence' events based on RMS energy thresholding:

const mic = new Decibri({
  sampleRate: 16000,
  vad: true,
  vadThreshold: 0.01,
  vadHoldoff: 300,
});

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

await mic.start();

WebSocket streaming

const ws = new WebSocket('wss://your-server.com/audio');
const mic = new Decibri({ sampleRate: 16000, format: 'int16' });

mic.on('data', (chunk) => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(chunk.buffer);
  }
});

document.getElementById('start').onclick = () => mic.start();
document.getElementById('stop').onclick = () => mic.stop();

Browser support

Requires HTTPS (or localhost) for microphone access.

CSP-restricted environments

By default, decibri loads its AudioWorklet processor via an inline Blob URL. If your Content Security Policy blocks blob: URLs:

const mic = new Decibri({
  workletUrl: '/static/decibri-worklet.js',
});

Copy the worklet file from node_modules/decibri/dist/worklet.js to your static assets directory and pass the URL.

API reference

Constructor

new Decibri(options?)

Creates a new capture instance. Does not start capture. Call start() to begin.

import { Decibri } from 'decibri';
const mic = new Decibri(options?);

Methods

mic.start()

Returns Promise<void>. Requests microphone permission and begins capture. Must be called from a user gesture in Safari. No-op if already started. Rejects with a clear error on permission denial.

mic.stop()

Stops capture and releases all resources (tracks, context, nodes). Safe to call anytime, including before start() or multiple times. Emits 'end' then 'close'.

Properties

mic.isOpen

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

Static methods

Decibri.devices()

Returns Promise<DeviceInfo[]>. Lists available audio input devices. Labels may be empty before microphone permission is granted.

const devices = await Decibri.devices();
console.log(devices);
// [
//   { deviceId: 'abc123', label: 'Built-in Microphone', groupId: 'g1' },
//   ...
// ]

Decibri.version()

Returns version information for decibri.

Decibri.version();
// { decibri: '3.0.0' }

Events

Types

// DeviceInfo
{
  deviceId: string,
  label: string,
  groupId: string,
}

// VersionInfo
{
  decibri: string,
}

Differences from Decibri (Node.js)