VoiceBlender

https://www.voiceblender.org
Admin
VoiceBlender is an open source Go service that bridges SIP and WebRTC voice calls with multi-party...
Tokens:4,108
Snippets:38
Trust Score:2.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run VoiceBlender Performance Benchmark

Source: https://www.voiceblender.org/

Execute the integration tests to measure VoiceBlender's performance under various load conditions, such as concurrent rooms and audio latency.

```bash
# Run the benchmark (default scales: 5, 10, 25, 50, 100 rooms)
go test -tags integration -v -timeout 300s \
  -run TestConcurrentRoomsScale ./tests/integration/

# Example output at 100 rooms:
# Phase 1 — Setup: 100 rooms in 3.7s (26.9 rooms/sec)
#   call+room setup latency: avg=570ms p50=615ms p95=728ms p99=751ms
#   Goroutines: 1914  |  Heap alloc: 19.0 MB
# Phase 2 — Sustaining 100 rooms for 3s... All 200 calls connected
# Phase 3 — Audio latency: avg=20ms p50=10ms p95=62ms p99=64ms
# Phase 4 — Teardown: 100 rooms in 5.6ms (17782 rooms/sec)
```

--------------------------------

### Run VoiceBlender Service

Source: https://www.voiceblender.org/

Build and run the VoiceBlender service using Go commands or Docker. The service exposes a REST API on port 8080 and SIP on port 5060.

```bash
go build -o voiceblender ./cmd/voiceblender
./voiceblender
```

```bash
go run ./cmd/voiceblender
```

--------------------------------

### Typical Workflow

Source: https://www.voiceblender.org/

A common sequence of API calls to handle an inbound call, add it to a room, attach an AI agent, and manage the call lifecycle.

```APIDOC
## Typical Workflow

This section outlines a typical workflow for handling inbound calls, integrating AI agents, and managing call lifecycles using the VoiceBlender API.

1. **Register a webhook** to receive inbound call events.
   `POST /v1/webhooks`

2. **Receive inbound call notification** via webhook.
   `--> webhook: leg.ringing {leg_id, from, to}`

3. **Answer the incoming leg**.
   `POST /v1/legs/{id}/answer`

4. **Create a multi-party room**.
   `POST /v1/rooms`

5. **Add the leg to the room**.
   `POST /v1/rooms/{id}/legs`

6. **Attach an AI agent** to the leg (e.g., ElevenLabs).
   `POST /v1/legs/{id}/agent/elevenlabs`

7. **Start recording** the leg if needed.
   `POST /v1/legs/{id}/record`

8. **Hang up** the leg when done.
   `DELETE /v1/legs/{id}`
```

--------------------------------

### Configure VoiceBlender Environment Variables

Source: https://www.voiceblender.org/

Set these environment variables to configure the VoiceBlender application, including network addresses, ports, API keys, and storage options.

```bash
export HTTP_ADDR=:8080              # REST API listen address
export SIP_BIND_IP=127.0.0.1       # IP for SDP/Contact/Via headers
export SIP_PORT=5060                # SIP listen port
export ICE_SERVERS=stun:stun.l.google.com:19302
export RECORDING_DIR=/tmp/recordings
export LOG_LEVEL=info               # debug, info, warn, error
export WEBHOOK_URL=https://example.com/hooks
export ELEVENLABS_API_KEY=sk-...    # TTS, STT, Agent
export VAPI_API_KEY=...             # Vapi Agent provider
export DEEPGRAM_API_KEY=...         # STT, TTS, Agent
export S3_BUCKET=my-recordings      # Optional S3 upload
```

--------------------------------

### VoiceBlender Typical Workflow

Source: https://www.voiceblender.org/

This sequence outlines a common workflow for handling inbound calls, adding participants to rooms, attaching AI agents, and managing call recordings via the VoiceBlender REST API.

```text
1. Register a webhook        POST /v1/webhooks
2. Receive inbound call      --> webhook: leg.ringing {leg_id, from, to}
3. Answer                    POST /v1/legs/{id}/answer
4. Create a room             POST /v1/rooms
5. Add legs to room          POST /v1/rooms/{id}/legs
6. Attach AI agent           POST /v1/legs/{id}/agent/elevenlabs
7. Start recording           POST /v1/legs/{id}/record
8. Hang up                   DELETE /v1/legs/{id}
```

--------------------------------

### VoiceBlender Rooms API Endpoints

Source: https://www.voiceblender.org/

Reference for managing multi-party rooms, including creation, listing, deletion, adding participants, and integrating TTS, STT, and AI agents for room-wide interactions.

```text
POST   /v1/rooms                         # Create room
GET    /v1/rooms                         # List rooms
DELETE /v1/rooms/{id}                    # Delete room (hangs up all legs)
POST   /v1/rooms/{id}/legs               # Add leg to room
GET    /v1/rooms/{id}/ws                 # Join room via WebSocket
POST   /v1/rooms/{id}/play               # Play audio or tone to room
POST   /v1/rooms/{id}/tts                # TTS to room
POST   /v1/rooms/{id}/record             # Record room mix
POST   /v1/rooms/{id}/agent/elevenlabs   # ElevenLabs agent
POST   /v1/rooms/{id}/agent/vapi         # Vapi agent
POST   /v1/rooms/{id}/agent/pipecat      # Pipecat agent
POST   /v1/rooms/{id}/agent/deepgram     # Deepgram agent
POST   /v1/rooms/{id}/agent/message      # Send message to agent
```

--------------------------------

### WebRTC Endpoints

Source: https://www.voiceblender.org/

Endpoints for managing WebRTC connections, including SDP offer/answer exchange and ICE candidate management.

```APIDOC
## POST /v1/webrtc/offer

### Description
Initiates the SDP offer/answer exchange for WebRTC connections.

### Method
POST

### Endpoint
/v1/webrtc/offer

### Request Body
(Not specified in source)

### Response
(Not specified in source)
```

```APIDOC
## POST /v1/legs/{id}/ice-candidates

### Description
Adds a trickle ICE candidate for a specific leg of a call.

### Method
POST

### Endpoint
/v1/legs/{id}/ice-candidates

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the leg.

### Request Body
(Not specified in source)

### Response
(Not specified in source)
```

```APIDOC
## GET /v1/legs/{id}/ice-candidates

### Description
Retrieves the gathered ICE candidates for a specific leg of a call.

### Method
GET

### Endpoint
/v1/legs/{id}/ice-candidates

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the leg.

### Response
(Not specified in source)
```

--------------------------------

### Rooms API

Source: https://www.voiceblender.org/

Endpoints for managing multi-party call rooms, including creation, adding participants, and controlling room-wide actions.

```APIDOC
## Rooms API

This API manages multi-party call rooms.

- **Create a room**
  `POST /v1/rooms`

- **List rooms**
  `GET /v1/rooms`

- **Delete a room** (hangs up all legs in the room)
  `DELETE /v1/rooms/{id}`

- **Add a leg to a room**
  `POST /v1/rooms/{id}/legs`

- **Join a room via WebSocket**
  `GET /v1/rooms/{id}/ws`

- **Play audio or tone to the room**
  `POST /v1/rooms/{id}/play`

- **Text-to-speech to the room**
  `POST /v1/rooms/{id}/tts`

- **Record the room mix**
  `POST /v1/rooms/{id}/record`

- **Attach ElevenLabs agent to the room**
  `POST /v1/rooms/{id}/agent/elevenlabs`

- **Attach Vapi agent to the room**
  `POST /v1/rooms/{id}/agent/vapi`

- **Attach Pipecat agent to the room**
  `POST /v1/rooms/{id}/agent/pipecat`

- **Attach Deepgram agent to the room**
  `POST /v1/rooms/{id}/agent/deepgram`

- **Send message to an agent in the room**
  `POST /v1/rooms/{id}/agent/message`
```

--------------------------------

### VoiceBlender Legs API Endpoints

Source: https://www.voiceblender.org/

Reference for managing individual call legs, including originating calls, answering, hanging up, playing audio, and integrating TTS, STT, and AI agents.

```text
POST   /v1/legs                          # Originate outbound SIP call
GET    /v1/legs                          # List all legs
POST   /v1/legs/{id}/answer              # Answer ringing inbound leg
POST   /v1/legs/{id}/early-media         # Enable early media (183)
DELETE /v1/legs/{id}                     # Hang up
POST   /v1/legs/{id}/dtmf               # Send DTMF digits
POST   /v1/legs/{id}/play               # Play audio or tone
POST   /v1/legs/{id}/tts                # Text-to-speech
POST   /v1/legs/{id}/record             # Start recording
POST   /v1/legs/{id}/stt                # Start speech-to-text
POST   /v1/legs/{id}/agent/elevenlabs   # ElevenLabs agent
POST   /v1/legs/{id}/agent/vapi         # Vapi agent
POST   /v1/legs/{id}/agent/pipecat      # Pipecat agent
POST   /v1/legs/{id}/agent/deepgram     # Deepgram agent
POST   /v1/legs/{id}/agent/message      # Send message to agent
```

--------------------------------

### VoiceBlender WebRTC API Endpoints

Source: https://www.voiceblender.org/

These are the REST API endpoints for managing WebRTC connections, including initiating SDP offers and handling ICE candidates.

```text
POST   /v1/webrtc/offer                 # SDP offer/answer exchange
POST   /v1/legs/{id}/ice-candidates     # Add trickle ICE candidate
GET    /v1/legs/{id}/ice-candidates     # Get gathered ICE candidates
```

--------------------------------

### Legs API

Source: https://www.voiceblender.org/

Endpoints for managing individual call legs, including originating calls, answering, controlling media, and attaching AI agents.

```APIDOC
## Legs API

This API manages individual call legs.

- **Originate outbound SIP call**
  `POST /v1/legs`

- **List all legs**
  `GET /v1/legs`

- **Answer ringing inbound leg**
  `POST /v1/legs/{id}/answer`

- **Enable early media (183)**
  `POST /v1/legs/{id}/early-media`

- **Hang up a leg**
  `DELETE /v1/legs/{id}`

- **Send DTMF digits**
  `POST /v1/legs/{id}/dtmf`

- **Play audio or tone**
  `POST /v1/legs/{id}/play`

- **Text-to-speech**
  `POST /v1/legs/{id}/tts`

- **Start recording**
  `POST /v1/legs/{id}/record`

- **Start speech-to-text**
  `POST /v1/legs/{id}/stt`

- **Attach ElevenLabs agent**
  `POST /v1/legs/{id}/agent/elevenlabs`

- **Attach Vapi agent**
  `POST /v1/legs/{id}/agent/vapi`

- **Attach Pipecat agent**
  `POST /v1/legs/{id}/agent/pipecat`

- **Attach Deepgram agent**
  `POST /v1/legs/{id}/agent/deepgram`

- **Send message to agent**
  `POST /v1/legs/{id}/agent/message`
```
Tokens:
Raw