Typecast

Text-to-speech service implementation using Typecast’s neural voices

Overview

TypecastTTSService converts text into expressive, lifelike speech using Typecast’s neural voices. It supports emotion control and audio customization, and integrates Typecast’s streaming text-to-speech into a Pipecat pipeline.

Source Repository

Source code, examples, and issues for the Typecast integration

PyPI Package

The pipecat-ai-typecast package on PyPI

Typecast Website

Learn more about Typecast’s text-to-speech voices

API Keys

Create and manage your Typecast API keys

Installation

This is a community-maintained package distributed separately from pipecat-ai:

pip install pipecat-ai-typecast

Prerequisites

Typecast Account Setup

Before using the Typecast TTS service, you need:

1. Typecast Account: Sign up at Typecast
2. API Key: Create a key from the Typecast API key page

Required Environment Variables

• TYPECAST_API_KEY: Your Typecast API key for authentication (required)
• TYPECAST_VOICE_ID: Voice ID override (optional; defaults to the service’s built-in voice)

Configuration

aiohttp_session · aiohttp.ClientSession · required

Active aiohttp client session used for Typecast API requests.

api_key · str · default: "None"

Typecast API key. Falls back to the TYPECAST_API_KEY environment variable if not provided.

voice_id · str · default: "None"

Voice ID to use. Falls back to the TYPECAST_VOICE_ID environment variable, or the service’s built-in default voice.

model · str · default: "ssfm-v30"

Typecast model version. Use ssfm-v30 (default) or the legacy ssfm-v21.

base_url · str · default: "https://api.typecast.ai/v1/text-to-speech"

Typecast API endpoint URL.

sample_rate · int · default: "44100"

Audio sample rate in Hz.

params · TypecastInputParams · default: "None"

Advanced configuration parameters for language, seed, emotion, and audio output. See Input Parameters below.

Input Parameters

Advanced settings passed via the params constructor argument using TypecastInputParams(...).

Parameter	Type	Default	Description
language	Language	Language.EN	Target language, mapped to a Typecast ISO-639-3 code.
seed	int	None	Seed for deterministic synthesis of identical text.
prompt_options	TypecastPromptOptions	PresetPromptOptions()	Emotion control. See prompt option models below.
output_options	OutputOptions	OutputOptions()	Audio output configuration. See output options below.

prompt_options accepts one of:

• PresetPromptOptions (ssfm-v30): emotion_preset (e.g. normal, happy, sad, angry, whisper, toneup, tonedown) and emotion_intensity (0.0–2.0).
• SmartPromptOptions (ssfm-v30): previous_text and next_text (max 2000 chars each) for context-aware emotion inference.
• PromptOptions (legacy ssfm-v21): emotion_preset and emotion_intensity.

OutputOptions fields:

Parameter	Type	Default	Description
volume	int	None	Volume percent (0–200). Mutually exclusive with target_lufs.
audio_pitch	int	0	Pitch adjustment in semitones (-12 to 12).
audio_tempo	float	1.0	Playback speed (0.5–2.0).
audio_format	str	"wav"	Output format. Only wav is supported.
target_lufs	float	None	Absolute loudness target in LUFS (-70.0–0.0). Excludes volume.

Available parameters and defaults are defined by the integration and the selected Typecast model. See the source repository for the authoritative, up-to-date list.

Usage

import os
import aiohttp
from pipecat_typecast.tts import (
    TypecastTTSService,
    TypecastInputParams,
    PresetPromptOptions,
    OutputOptions,
)

async with aiohttp.ClientSession() as session:
    tts = TypecastTTSService(
        aiohttp_session=session,
        api_key=os.getenv("TYPECAST_API_KEY"),
        voice_id=os.getenv("TYPECAST_VOICE_ID"),
        model="ssfm-v30",
        params=TypecastInputParams(
            prompt_options=PresetPromptOptions(
                emotion_preset="happy",
                emotion_intensity=1.3,
            ),
            output_options=OutputOptions(
                audio_pitch=2,
                audio_tempo=1.05,
            ),
        ),
    )

    # Add tts to your pipeline (after the LLM, before transport.output()).

See example.py in the source repository for a complete working bot.

Compatibility

Tested with Pipecat v0.0.94+. Check the source repository for the latest tested version and changelog.