Skip to main content

​
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(...).
ParameterTypeDefaultDescription
languageLanguageLanguage.ENTarget language, mapped to a Typecast ISO-639-3 code.
seedintNoneSeed for deterministic synthesis of identical text.
prompt_optionsTypecastPromptOptionsPresetPromptOptions()Emotion control. See prompt option models below.
output_optionsOutputOptionsOutputOptions()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:
ParameterTypeDefaultDescription
volumeintNoneVolume percent (0–200). Mutually exclusive with target_lufs.
audio_pitchint0Pitch adjustment in semitones (-12 to 12).
audio_tempofloat1.0Playback speed (0.5–2.0).
audio_formatstr"wav"Output format. Only wav is supported.
target_lufsfloatNoneAbsolute 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.