@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';

const client = Vocallabs({
  sampleRate: 8000,
  connectionTimeout: 5000,
  audioFormat: 'audio/x-l16',
});

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

// later
client.disconnect();

API

Factory

• Vocallabs(options?) => VocalLabsClient

Options

• sampleRate: 8000 | 16000 (default: 8000)
• 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')

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