Installation

Requires Python 3.11 or later, Pipecat 1.12.0 or later, and Typecast Python SDK 0.5.1 or later.

pip install pipecat-ai-typecast

Prerequisites

Quick Start

TypecastTTSService integrates Typecast's streaming text-to-speech into a Pipecat pipeline. It converts LLM text output into expressive speech while leveraging Pipecat's transport, STT, and turn-taking stack.

import os, aiohttp
from pipecat.pipeline.pipeline import Pipeline
from pipecat_typecast.tts import TypecastTTSService

async with aiohttp.ClientSession() as session:
    llm = ...
    stt = ...
    tts = TypecastTTSService(
        aiohttp_session=session,
        api_key=os.getenv("TYPECAST_API_KEY"),
        voice_id=os.getenv("TYPECAST_VOICE_ID", "tc_672c5f5ce59fac2a48faeaee"),
    )

    pipeline = Pipeline([
        transport.input(),               # audio/user input
        stt,                             # speech to text
        context_aggregator.user(),       # add user text to context
        llm,                             # LLM generates response
        tts,                             # Typecast TTS synthesis
        transport.output(),              # stream audio back to user
        context_aggregator.assistant(),  # store assistant response
    ])

See example.py for a complete working example including event handlers and transport setup.

Configuration

TypecastTTSService exposes structured parameter models for emotion and audio control.

ssfm-v30 (Default) - Preset Emotion Control

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

params = TypecastInputParams(
    streaming=False,                  # Required when using volume.
    prompt_options=PresetPromptOptions(
        emotion_preset="happy",      # normal | happy | sad | angry | whisper | toneup | tonedown
        emotion_intensity=1.3,       # 0.0 - 2.0
    ),
    output_options=OutputOptions(
        volume=110,                  # 0 - 200 (percent). Defaults to None
                                     # so the server-side default of 100
                                     # kicks in when neither this nor
                                     # `target_lufs` is set.
        audio_pitch=2,               # -12 to 12 (semitones)
        audio_tempo=1.05,            # 0.5 - 2.0 (playback speed)
        audio_format="wav",          # Only 'wav' supported
        # target_lufs=-16.0,         # Absolute loudness target in LUFS
                                     # (-70.0 to 0.0). Mutually exclusive
                                     # with `volume` — leave `volume` unset
                                     # when using `target_lufs`.
    ),
)

tts = TypecastTTSService(
    aiohttp_session=session,
    api_key=os.getenv("TYPECAST_API_KEY"),
    voice_id="tc_672c5f5ce59fac2a48faeaee",
    model="ssfm-v30",
    params=params,
)

ssfm-v30 - Smart Emotion Control

For context-aware emotional delivery, use SmartPromptOptions which infers emotion from surrounding text:

from pipecat_typecast.tts import (
    TypecastTTSService,
    TypecastInputParams,
    SmartPromptOptions,
)

params = TypecastInputParams(
    prompt_options=SmartPromptOptions(
        previous_text="I just got the best news ever!",   # max 2000 chars
        next_text="I can't wait to share this with everyone!",
    ),
)

tts = TypecastTTSService(
    aiohttp_session=session,
    api_key=os.getenv("TYPECAST_API_KEY"),
    params=params,
)

Legacy Model (ssfm-v21)

from pipecat_typecast.tts import (
    TypecastTTSService,
    TypecastInputParams,
    PromptOptions,
)

params = TypecastInputParams(
    prompt_options=PromptOptions(
        emotion_preset="happy",      # normal | happy | sad | angry
        emotion_intensity=1.3,
    ),
)

tts = TypecastTTSService(
    aiohttp_session=session,
    api_key=os.getenv("TYPECAST_API_KEY"),
    model="ssfm-v21",
    params=params,
)

Parameter Reference

Running the Example

# 1. Install dependencies
uv sync

# 2. Configure environment
cp env.example .env

# 3. Run
uv run python example.py

The bot will create a call (e.g. Daily room) and speak responses using Typecast voices.

Compatibility

Support

• API Documentation: typecast.ai
• Pipecat Discord: discord.gg/pipecat (#community-integrations)