vocal-call-sdk/README.md

A JavaScript SDK that provides a complete voice calling interface with WebSocket communication, audio recording/playback, and automatic UI management.

# VocalCallSDK

A JavaScript SDK for real-time voice calls with automatic recording and upload capabilities.

## Installation

```javascript
import { VocalCallSDK } from './vocal-call-sdk.js';
```

## Basic Usage

```javascript
let sdk = new VocalCallSDK({
            agentId: 'uuid agentId',           // necessary get it from vocallabs.ai
            callId: 'a084564e-86ac-4802-b37e-01295f7f6f00',     // get from arc.vocallabs.ai. query on VocallabsGetWebsocketUrl
            inactiveText: "Start Call",                  // optional
            activeText: "End Call",                     //optional
            size: 'large',                            //optional
            container: '#your-front-end-button-class', 
            config: {
                endpoints: {
                    websocket: websocketUrl.replace(/\/ws.*$/, '/ws/'),          // optional
                    upload: "upload-url"  // mandatory if you want to upload recordings
                },
                audio: {
                    userInputSampleRate: 32000,      // recommended sample rates
                    agentOutputSampleRate: 24000    // recommended: 24k. Available : 48k,24k,16k 
                },
            }
        });

// Render the call button
sdk.renderButton();
```

## Required Parameters

- **`agentId`**: Agent identifier from vocallabs.ai
- **`callId`**: Unique identifier for each call session
- **`config.endpoints.upload`**: Endpoint URL for recording upload (required)

## Optional Parameters

- **`inactiveText`**: Button text when idle (default: "Talk to Assistant")
- **`activeText`**: Button text when recording (default: "Listening...")
- **`size`**: Button size - "small", "medium", "large" (default: "medium")
- **`container`**: DOM container for button rendering

## Event Handling

```javascript
sdk.on('onCallStart', () => console.log('Call started'))
  .on('onCallEnd', (reason) => console.log('Call ended:', reason))
  .on('onUploadSuccess', (data) => console.log('Recording uploaded:', data.downloadUrl))
  .on('onError', (error) => console.error('Error:', error));
```

## Methods

- **`startCall()`**: Programmatically start a call
- **`endCall()`**: Programmatically end a call
- **`getStatus()`**: Get current SDK status
- **`destroy()`**: Clean up resources

## How It Works

The SDK automatically handles microphone access, WebSocket connections, audio processing, call recording, and upload to your specified endpoint.

### Key Features

**Dual-Stream Recording**: The SDK captures both user microphone input and agent audio output separately, then combines them into a single high-quality WAV file. This ensures clear recordings of the entire conversation.

**Real-Time Audio Processing**: 
- User audio is captured at 32kHz sample rate by default
- Agent audio is received at 24kHz sample rate by default  
- Automatic resampling and normalization for optimal quality
- Echo cancellation and noise suppression for clear communication

**Automatic Upload**: When a call ends, the combined recording is automatically uploaded to your specified endpoint using a presigned URL workflow:
1. SDK requests presigned URL from your upload endpoint
2. Recording is uploaded directly to cloud storage (R2/S3)
3. Download URL is returned for access

**Browser Compatibility**: Uses modern AudioWorkletNode when available, with automatic fallback to ScriptProcessorNode for older browsers.

### Audio Configuration
Various configurations for agent output sample rate avaliable like 48k,24k,16k 
```javascript
config: {
  audio: {
    userInputSampleRate: 32000,    // Microphone sample rate
    agentOutputSampleRate: 24000,  // Agent audio sample rate
    echoCancellation: true,
    noiseSuppression: true
  }
}
```