> ## 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 service using Speechmatics TTS API

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

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

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

  <Card title="Speechmatics Documentation" icon="book" href="https://docs.speechmatics.com/text-to-speech/quickstart">
    Official Speechmatics TTS API documentation
  </Card>

  <Card title="Speechmatics Portal" icon="microphone" href="https://portal.speechmatics.com">
    Browse and test available voices
  </Card>
</CardGroup>

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

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

<ParamField path="base_url" type="str" default="https://preview.tts.speechmatics.com">
  Base URL for Speechmatics TTS API.
</ParamField>

<ParamField path="voice_id" type="str" default="sarah" deprecated>
  Voice model to use for synthesis.

  *Deprecated in v0.0.105. Use `settings=SpeechmaticsTTSService.Settings(...)` instead.*
</ParamField>

<ParamField path="aiohttp_session" type="aiohttp.ClientSession" required>
  An aiohttp session for HTTP requests.
</ParamField>

<ParamField path="sample_rate" type="int" default="16000">
  Audio sample rate in Hz. Speechmatics TTS only supports 16kHz.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  Runtime-configurable service settings. See [InputParams](#inputparams) below.

  *Deprecated in v0.0.105. Use `settings=SpeechmaticsTTSService.Settings(...)` instead.*
</ParamField>

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

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `SpeechmaticsTTSService.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.)*   |
| `max_retries` | `int`             | `NOT_GIVEN` | Maximum number of retries for synthesis. |

## Usage

### Basic Setup

```python theme={null}
import aiohttp
from pipecat.services.speechmatics 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 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",
        ),
    )
```

<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

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