@vocallabs/web-sdk

@vocallabs/web-sdk

Real-time voice communication SDK for browser applications.

Features

• WebSocket-based bi-directional audio streaming
• Microphone capture and browser audio playback
• Transcript event handling
• Built-in mute controls
• Lightweight event API (on, off, once)
• TypeScript declarations included

Installation

npm install @vocallabs/web-sdk

Quick Start

import { Vocallabs } from '@vocallabs/web-sdk';

// No audio options needed — the `_web_<rate>` token in the URL configures
// rates and codec. `_web_32000` is the recommended transport.
const client = Vocallabs({ connectionTimeout: 5000 });

client.on('connected', () => {
  console.log('Connected');
});

client.on('transcript', (payload) => {
  console.log('Transcript:', payload.transcript, 'final:', payload.is_final);
});

client.on('error', (err) => {
  console.error('SDK error:', err.code, err.message);
});

await client.connect('wss://your-server.example/ws?callId=abc123_web_32000');

// later
client.disconnect();

API

Factory

• Vocallabs(options?) => VocalLabsClient

Options

• sampleRate: 8000 | 16000 | 24000 | 32000 | 44100 | 48000 (default: 8000). Shorthand for both directions.
• inputSampleRate: mic → server rate (default: sampleRate)
• outputSampleRate: server → speakers rate (default: sampleRate)
• autoTransport: read the rate from the connect URL (default: true)
• connectionTimeout: number in ms (default: 5000)
• maxQueueSize: number (default: 15)
• noiseGateThreshold: number in dB (default: -50)
• speakingThreshold: number (default: 0.01)
• audioFormat: 'audio/x-l16' | 'audio/x-mulaw' (default: 'audio/x-l16')

Sample rates and the _web_<rate> token

Prefer _web_32000. It is the transport we recommend and the one most thoroughly exercised — capture at 32 kHz, playback at 24 kHz, linear PCM both ways. The others work but each has a caveat, listed below.

The two directions are independent, each with its own AudioContext — a context has one immutable sample rate, so differing rates need two.

If the connect URL contains a _web_<rate> token, the SDK configures itself from it and you can pass no audio options at all:

const client = Vocallabs();
await client.connect('wss://host/ws?callId=abc_web_32000'); // send l16@32000, recv l16@24000

token	sends	receives	notes
_web_32000	l16 @ 32000	l16 @ 24000	recommended
_web_16000	l16 @ 16000	l16 @ 16000	fine; lower fidelity
_web_48000	l16 @ 48000	l16 @ 44100	~6x the bandwidth of 8 kHz; 44.1 kHz playback is resampled on most hardware
_web_8000	l16 @ 8000	mulaw @ 8000	narrowband telephony; use when bridging to the phone network

Note that the rate you send is not the rate you receive — _web_32000 returns 24 kHz and _web_48000 returns 44.1 kHz. The SDK handles that for you; it matters only if you configure rates by hand.

Anything you set by name (inputSampleRate, outputSampleRate, audioFormat) wins over the token. Set autoTransport: false to ignore the token entirely.

Client Methods

• connect(wsUrl: string): Promise<void>
• disconnect(): void
• destroy(): void
• mute(): void
• unmute(): void
• toggleMute(): boolean
• clearAudioQueue(): void
• sendMessage(message: Record<string, unknown>): void
• getStats(): { sentChunks, receivedChunks, queueSize, readyState }

Client State

• isMuted: boolean
• isConnected: boolean
• readyState: 'disconnected' | 'connecting' | 'connected'

Events

• connected
• disconnected (payload: { code?, reason?, wasClean? })
• error (payload: VocalLabsError)
• userConnected
• transcript (payload includes transcript, is_final, speaker)
• muteChanged (payload: { muted: boolean })
• audioQueueCleared
• message (unknown server event payload)

Use:

client.on('connected', handler);
client.off('connected', handler);
client.once('connected', handler);

Browser Requirements

• Modern browser with WebSocket, MediaDevices.getUserMedia, and AudioContext
• Microphone permission must be granted by the user
• Works best in secure contexts (https://)

Error Handling

The SDK throws or emits VocalLabsError with code values such as:

• INVALID_CONFIG
• ALREADY_CONNECTED
• NOT_CONNECTED
• CONNECTION_FAILED
• CONNECTION_TIMEOUT
• AUDIO_INIT_FAILED
• MICROPHONE_DENIED
• AUDIO_PROCESSING_ERROR
• WEBSOCKET_ERROR
• MESSAGE_PARSE_ERROR

Development

Build

npm run build

Watch Build

npm run build:watch

License

MIT