> ## Documentation Index
> Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipecat

> Add expressive Typecast voices to your Pipecat AI voice pipelines.

<Info>
  [Pipecat](https://github.com/pipecat-ai/pipecat) is an open-source framework for building real-time, multimodal AI voice agents. With the Typecast TTS integration, you can add high-quality neural voices with emotion control to your voice AI pipelines.
</Info>

## What is Pipecat?

Pipecat is a Python framework that simplifies building voice AI applications. It connects various services (speech-to-text, LLMs, text-to-speech) into a unified pipeline, handling the complexity of real-time audio streaming, turn-taking, and transport protocols.

A typical Pipecat pipeline looks like this:

```
User Audio → STT → LLM → TTS → Bot Audio
```

The Typecast TTS service (`pipecat-ai-typecast`) integrates seamlessly into this pipeline, converting LLM responses into expressive speech.

***

## What You Can Do

With the Typecast Pipecat integration, you can:

* **Build voice AI agents** with natural, expressive voices
* **Choose from 500+ voices** with different genders, ages, and styles
* **Apply emotions** (happy, sad, angry, whisper, and more)
* **Use Smart Emotion** for context-aware voice synthesis
* **Deploy anywhere** — Daily, Twilio, or native WebRTC

***

## Prerequisites

Before you start, make sure you have:

| Requirement      | Version                                               |
| ---------------- | ----------------------------------------------------- |
| Python           | 3.10+                                                 |
| Pipecat          | v0.0.94+                                              |
| Typecast API Key | [Get yours here](https://typecast.ai/developers/api/) |

***

## Installation

Install the Typecast TTS service for Pipecat:

```bash theme={null}
pip install pipecat-ai-typecast
```

<Tip>
  Using uv? Run `uv add pipecat-ai-typecast` instead.
</Tip>

***

## Quick Start

Here's a minimal example of integrating Typecast TTS into a Pipecat pipeline:

```python theme={null}
import os
import aiohttp
from pipecat.pipeline.pipeline import Pipeline
from pipecat_typecast import TypecastTTSService

async with aiohttp.ClientSession() as session:
    # Initialize Typecast TTS
    tts = TypecastTTSService(
        aiohttp_session=session,
        api_key=os.getenv("TYPECAST_API_KEY"),
        voice_id=os.getenv("TYPECAST_VOICE_ID", "tc_672c5f5ce59fac2a48faeaee"),
    )

    # Build your pipeline
    pipeline = Pipeline([
        transport.input(),               # User audio 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 to user
        context_aggregator.assistant(),  # Store assistant response
    ])
```

<Note>
  Set your environment variables:

  * `TYPECAST_API_KEY` — Your Typecast API key (required)
  * `TYPECAST_VOICE_ID` — Voice to use (optional, defaults to a preset voice)
</Note>

***

## Configuration

The `TypecastTTSService` supports both preset-based and context-aware emotion control.

### Basic Configuration

```python theme={null}
from pipecat_typecast import TypecastTTSService

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

### Preset Emotion Control

Choose from predefined emotions for consistent voice styling:

```python theme={null}
from pipecat_typecast import (
    TypecastTTSService,
    TypecastInputParams,
    PresetPromptOptions,
    OutputOptions,
)

params = TypecastInputParams(
    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)
        audio_pitch=2,               # -12 to 12 (semitones)
        audio_tempo=1.05,            # 0.5 - 2.0 (playback speed)
    ),
)

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

### Smart Emotion (Context-Aware)

Let the AI automatically infer emotion from surrounding text:

```python theme={null}
from pipecat_typecast 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,
)
```

<CardGroup cols={2}>
  <Card title="Preset Emotion" icon="sliders">
    Manually choose from 7 emotions: Normal, Happy, Sad, Angry, Whisper, Tone Up, Tone Down.

    Best for consistent voice styling.
  </Card>

  <Card title="Smart Emotion" icon="wand-magic-sparkles">
    AI automatically detects the best emotion from text context.

    Best for natural conversations.
  </Card>
</CardGroup>

### Parameter Reference

| Parameter           | Range           | Description                                                                  |
| ------------------- | --------------- | ---------------------------------------------------------------------------- |
| `emotion_preset`    | varies by voice | ssfm-v30: `normal`, `happy`, `sad`, `angry`, `whisper`, `toneup`, `tonedown` |
| `emotion_intensity` | 0.0 - 2.0       | Values > 1.0 increase expressiveness                                         |
| `audio_pitch`       | -12 to 12       | Semitone adjustment                                                          |
| `audio_tempo`       | 0.5 - 2.0       | Recommended: 0.85 - 1.15                                                     |
| `volume`            | 0 - 200         | Audio volume as percentage                                                   |
| `seed`              | uint32          | Unsigned integer seed for deterministic synthesis (≥ 0)                      |

***

## Supported Transports

Pipecat supports multiple transport protocols. Typecast works with all of them:

<Tabs>
  <Tab title="Daily">
    [Daily](https://www.daily.co/) provides WebRTC-based video and audio infrastructure.

    ```python theme={null}
    from pipecat.transports.daily.transport import DailyParams

    transport_params = DailyParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        vad_analyzer=SileroVADAnalyzer(),
    )
    ```
  </Tab>

  <Tab title="Twilio">
    [Twilio](https://www.twilio.com/) enables voice calls over phone networks.

    ```python theme={null}
    from pipecat.transports.websocket.fastapi import FastAPIWebsocketParams

    transport_params = FastAPIWebsocketParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        vad_analyzer=SileroVADAnalyzer(),
    )
    ```
  </Tab>

  <Tab title="WebRTC">
    Native WebRTC for browser-based applications.

    ```python theme={null}
    from pipecat.transports.base_transport import TransportParams

    transport_params = TransportParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        vad_analyzer=SileroVADAnalyzer(),
    )
    ```
  </Tab>
</Tabs>

***

## Complete Example

Here's a full working example that creates a voice AI agent:

```python theme={null}
import os
import aiohttp
from dotenv import load_dotenv

from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.transports.daily.transport import DailyParams, DailyTransport

from pipecat_typecast import TypecastTTSService

load_dotenv()

async def main():
    async with aiohttp.ClientSession() as session:
        # Initialize services
        stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))
        llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"))
        tts = TypecastTTSService(
            aiohttp_session=session,
            api_key=os.getenv("TYPECAST_API_KEY"),
        )

        # Set up conversation context
        messages = [
            {
                "role": "system",
                "content": "You are a helpful AI assistant. Keep responses concise.",
            },
        ]
        context = LLMContext(messages)
        context_aggregator = LLMContextAggregatorPair(context)

        # Configure transport
        transport = DailyTransport(
            room_url=os.getenv("DAILY_ROOM_URL"),
            token=os.getenv("DAILY_TOKEN"),
            params=DailyParams(
                audio_in_enabled=True,
                audio_out_enabled=True,
                vad_analyzer=SileroVADAnalyzer(),
            ),
        )

        # Build and run pipeline
        pipeline = Pipeline([
            transport.input(),
            stt,
            context_aggregator.user(),
            llm,
            tts,
            transport.output(),
            context_aggregator.assistant(),
        ])

        task = PipelineTask(pipeline, params=PipelineParams())
        runner = PipelineRunner()
        await runner.run(task)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())
```

***

## Legacy Model (ssfm-v21)

<Accordion title="Using ssfm-v21 for backward compatibility">
  If you need to use the legacy ssfm-v21 model:

  ```python theme={null}
  from pipecat_typecast 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,
  )
  ```

  Note: ssfm-v21 supports fewer emotion presets (no `whisper`, `toneup`, `tonedown`).
</Accordion>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="API key not found error">
    * Ensure `TYPECAST_API_KEY` environment variable is set
    * Verify your key at [Typecast API Console](https://typecast.ai/developers/api/)
    * Check for extra spaces in the key
  </Accordion>

  <Accordion title="No audio output">
    * Confirm your transport is configured with `audio_out_enabled=True`
    * Check that the TTS service is included in your pipeline
    * Verify your API key has sufficient credits
  </Accordion>

  <Accordion title="Audio quality issues">
    * Adjust `audio_tempo` within the recommended range (0.85 - 1.15)
    * Try different `emotion_intensity` values
    * Ensure sample rate matches your transport configuration
  </Accordion>

  <Accordion title="Import errors">
    * Make sure you installed `pipecat-ai-typecast`, not just `pipecat-typecast`
    * Verify Python version is 3.10 or higher
    * Check that Pipecat version is v0.0.94 or later
  </Accordion>
</AccordionGroup>

***

## Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/neosapience/pipecat-typecast">
    Source code and examples
  </Card>

  <Card title="PyPI Package" icon="python" href="https://pypi.org/project/pipecat-ai-typecast/">
    Install via pip
  </Card>

  <Card title="Pipecat Documentation" icon="book" href="https://docs.pipecat.ai/">
    Learn more about Pipecat
  </Card>

  <Card title="Voice Library" icon="microphone" href="https://typecast.ai/developers/api/voices">
    Browse available voices
  </Card>
</CardGroup>