@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(): voiddestroy(): voidmute(): voidunmute(): voidtoggleMute(): booleanclearAudioQueue(): voidsendMessage(message: Record<string, unknown>): voidgetStats(): { sentChunks, receivedChunks, queueSize, readyState }
Client State
isMuted: booleanisConnected: booleanreadyState: 'disconnected' | 'connecting' | 'connected'
Events
connecteddisconnected(payload:{ code?, reason?, wasClean? })error(payload:VocalLabsError)userConnectedtranscript(payload includestranscript,is_final,speaker)muteChanged(payload:{ muted: boolean })audioQueueClearedmessage(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, andAudioContext - 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_CONFIGALREADY_CONNECTEDNOT_CONNECTEDCONNECTION_FAILEDCONNECTION_TIMEOUTAUDIO_INIT_FAILEDMICROPHONE_DENIEDAUDIO_PROCESSING_ERRORWEBSOCKET_ERRORMESSAGE_PARSE_ERROR
Development
Build
npm run build
Watch Build
npm run build:watch
License
MIT