> ## 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.

# Speechmatics Text-to-Speech

> SpeechmaticsTTSService provides production-grade low-latency TTS, streaming 16kHz mono audio tuned for telephony voice agents.

## Overview

`SpeechmaticsTTSService` provides production-grade, low-latency synthesis optimized for telephony and voice agents. By streaming 16kHz mono audio, it ensures bandwidth efficiency and prioritizes pronunciation accuracy for natural, uninterrupted conversations at scale.

> [card] [Speechmatics TTS API Reference](https://reference-server.pipecat.ai/en/latest/api/pipecat.services.speechmatics.tts.html)
>
> Pipecat's API methods for Speechmatics TTS integration

> [card] [Example Implementation](https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-speechmatics.py)
>
> Complete example with Speechmatics TTS

> [card] [Speechmatics Documentation](https://docs.speechmatics.com/text-to-speech/quickstart)
>
> Official Speechmatics TTS API documentation

> [card] [Speechmatics Portal](https://portal.speechmatics.com)
>
> Browse and test available voices

## Installation

To use Speechmatics services, install the required dependencies:

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

## Prerequisites

### Speechmatics Account Setup

Before using Speechmatics TTS services, you need:

1. **Speechmatics Account**: Sign up at [Speechmatics Portal](https://portal.speechmatics.com)
2. **API Key**: Generate an API key from your dashboard
3. **Voice Selection**: Choose from available [voices](https://docs.speechmatics.com/text-to-speech/quickstart#voices)

### Required Environment Variables

* `SPEECHMATICS_API_KEY`: Your Speechmatics API key for authentication

## Configuration

### SpeechmaticsTTSService

**api\_key** `str` *required*

Speechmatics API key for authentication. Raises `ValueError` when empty.

**base\_url** `str` (default: [https://preview.tts.speechmatics.com](https://preview.tts.speechmatics.com))

Base URL for Speechmatics TTS API.

**voice\_id** `str` *deprecated* (default: None)

*Deprecated since 0.0.105, removed in 2.0.0.* Use
`settings=SpeechmaticsTTSService.Settings(...)` instead.

**aiohttp\_session** `aiohttp.ClientSession` *required*

An aiohttp session for HTTP requests.

**sample\_rate** `int` (default: 16000)

Audio sample rate in Hz. Speechmatics TTS only supports 16kHz.

**params** `InputParams` *deprecated* (default: None)

*Deprecated since 0.0.105, removed in 2.0.0.* Use
`settings=SpeechmaticsTTSService.Settings(...)` instead.

**settings** `SpeechmaticsTTSService.Settings` (default: None)

Runtime-configurable settings. See [Settings](#settings) below.

### Settings

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

| Parameter | Type | Default | Description |
| - | - | - | - |
| `model` | `str` | `None` | Not sent by this service; reported only as the model name in metrics and traces. *(Inherited.)* |
| `voice` | `str` | `"sarah"` | Voice identifier. *(Inherited.)* |
| `language` | `Language \| str` | `None` | Language used to split text into sentences; not sent to Speechmatics. *(Inherited.)* |
| `max_retries` | `int` | `5` | Maximum number of attempts, including the first, when Speechmatics returns 503. |

## Usage

### Basic Setup

```python theme={null}
import os

import aiohttp
from pipecat.services.speechmatics.tts import SpeechmaticsTTSService

async with aiohttp.ClientSession() as session:
    tts = SpeechmaticsTTSService(
        api_key=os.getenv("SPEECHMATICS_API_KEY"),
        settings=SpeechmaticsTTSService.Settings(
            voice="sarah",
        ),
        aiohttp_session=session,
    )
```

### With Custom Settings

```python theme={null}
import aiohttp
from pipecat.services.speechmatics.tts import SpeechmaticsTTSService

async with aiohttp.ClientSession() as session:
    tts = SpeechmaticsTTSService(
        api_key=os.getenv("SPEECHMATICS_API_KEY"),
        aiohttp_session=session,
        settings=SpeechmaticsTTSService.Settings(
            max_retries=3,
            voice="sarah",
        ),
    )
```

## Notes

* **Fixed sample rate**: Speechmatics TTS only supports 16kHz output. Using a different sample rate may cause issues.
* **Automatic retry with backoff**: The service automatically retries on 503 (service unavailable) responses using exponential backoff, up to `max_retries` attempts. Each failed attempt pushes an `ErrorFrame`.
* **HTTP-based service**: Speechmatics TTS uses HTTP streaming, so it does not have WebSocket connection events.
* **Requires aiohttp session**: You must create and manage an `aiohttp.ClientSession` yourself and pass it to the constructor.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.