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.

Speechmatics TTS API Reference

Pipecat’s API methods for Speechmatics TTS integration

Example Implementation

Complete example with Speechmatics TTS

Speechmatics Documentation

Official Speechmatics TTS API documentation

Speechmatics Portal

Browse and test available voices

Installation

To use Speechmatics services, install the required dependencies:

pip install "pipecat-ai[speechmatics]"

Prerequisites

Speechmatics Account Setup

Before using Speechmatics TTS services, you need:

1. Speechmatics Account: Sign up at Speechmatics Portal
2. API Key: Generate an API key from your dashboard
3. Voice Selection: Choose from available voices

Required Environment Variables

• SPEECHMATICS_API_KEY: Your Speechmatics API key for authentication

Configuration

SpeechmaticsTTSService

api_key · str · required

Speechmatics API key for authentication.

base_url · str · default: "https://preview.tts.speechmatics.com"

Base URL for Speechmatics TTS API.

voice_id · str · default: "sarah" · deprecated

Voice model to use for synthesis.

Deprecated in v0.0.105. 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 · default: "None" · deprecated

Runtime-configurable service settings. See InputParams below.

Deprecated in v0.0.105. Use settings=SpeechmaticsTTSService.Settings(...) instead.

settings · SpeechmaticsTTSService.Settings · default: "None"

Runtime-configurable settings. See 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 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

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

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",
        ),
    )

The InputParams / params= pattern is deprecated as of v0.0.105. Use Settings / settings= instead. See the Service Settings guide for migration details.

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.