> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Resemble AI

> Text-to-speech service using Resemble AI's WebSocket streaming API with word-level timing

## Overview

`ResembleAITTSService` provides high-quality text-to-speech synthesis using Resemble AI's streaming WebSocket API with word-level timestamps and audio context management for handling multiple simultaneous synthesis requests with proper interruption support.

<CardGroup cols={2}>
  <Card title="Resemble AI TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.resembleai.tts.html">
    Pipecat's API methods for Resemble AI TTS integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-resemble.py">
    Complete example with interruption handling
  </Card>

  <Card title="Resemble AI Documentation" icon="book" href="https://docs.resemble.ai/">
    Official Resemble AI API documentation
  </Card>

  <Card title="Sign up" icon="user" href="https://app.resemble.ai/">
    Sign up for a Resemble AI account
  </Card>
</CardGroup>

## Installation

To use Resemble AI services, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[resemble]"
```

## Prerequisites

### Resemble AI Account Setup

Before using Resemble AI TTS services, you need:

1. **Resemble AI Account**: Sign up at [Resemble AI](https://app.resemble.ai)
2. **API Key**: Generate an API key from your [account settings](https://app.resemble.ai/account/api)
3. **Voice Selection**: Choose or create voice UUIDs from your [voice library](https://app.resemble.ai/hub/voices)

### Required Environment Variables

* `RESEMBLE_API_KEY`: Your Resemble AI API key for authentication

## Configuration

### ResembleAITTSService

<ParamField path="api_key" type="str" required>
  Resemble AI API key for authentication.
</ParamField>

<ParamField path="voice_id" type="str" required deprecated>
  Voice UUID to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=ResembleAITTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="settings" type="ResembleAITTSService.Settings" default="None">
  Runtime-configurable settings. See [Settings](#settings) below.
</ParamField>

<ParamField path="url" type="str" default="wss://websocket.cluster.resemble.ai/stream">
  WebSocket URL for Resemble AI TTS API.
</ParamField>

<ParamField path="precision" type="str" default="PCM_16">
  PCM bit depth. Options: `PCM_32`, `PCM_24`, `PCM_16`, or `MULAW`.
</ParamField>

<ParamField path="output_format" type="str" default="wav">
  Audio output format (`wav` or `mp3`).
</ParamField>

<ParamField path="sample_rate" type="int" default="22050">
  Audio sample rate in Hz. Options: 8000, 16000, 22050, 32000, or 44100.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `ResembleAITTSService.Settings(...)`. These can be updated mid-conversation with `TTSUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter  | Type              | Default | Description                            |
| ---------- | ----------------- | ------- | -------------------------------------- |
| `model`    | `str`             | `None`  | Model identifier. *(Inherited.)*       |
| `voice`    | `str`             | `None`  | Voice identifier. *(Inherited.)*       |
| `language` | `Language \| str` | `None`  | Language for synthesis. *(Inherited.)* |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.resembleai import ResembleAITTSService

tts = ResembleAITTSService(
    api_key=os.getenv("RESEMBLE_API_KEY"),
    settings=ResembleAITTSService.Settings(
        voice="your-voice-uuid",
    ),
)
```

### With Custom Settings

```python theme={null}
from pipecat.services.resembleai import ResembleAITTSService

tts = ResembleAITTSService(
    api_key=os.getenv("RESEMBLE_API_KEY"),
    settings=ResembleAITTSService.Settings(
        voice="your-voice-uuid",
    ),
    sample_rate=16000,
    precision="PCM_16",
    output_format="wav",
)
```

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Notes

* **Word-level timestamps**: Resemble AI provides word-level timing information, enabling synchronized text highlighting and precise interruption handling.
* **Jitter buffering**: The service buffers approximately 1 second of audio before starting playback to absorb network latency gaps (Resemble AI sends audio in bursts with 300-450ms gaps).
* **Audio context management**: Supports multiple simultaneous synthesis requests with proper context tracking and interruption handling.
* **Default sample rate**: Defaults to 22050 Hz. Supported rates are 8000, 16000, 22050, 32000, and 44100 Hz.

## Event Handlers

Resemble AI TTS supports the standard [service connection events](/api-reference/server/events/service-events):

| Event                 | Description                             |
| --------------------- | --------------------------------------- |
| `on_connected`        | Connected to Resemble AI WebSocket      |
| `on_disconnected`     | Disconnected from Resemble AI WebSocket |
| `on_connection_error` | WebSocket connection error occurred     |

```python theme={null}
@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Resemble AI")
```