> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-source-analytics-user-turn-strategies.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Typecast

> Text-to-speech service implementation using Typecast's neural voices

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="neosapience" maintainerUrl="https://github.com/neosapience" repo="https://github.com/neosapience/pipecat-typecast" />

## Overview

`TypecastTTSService` converts text into expressive, lifelike speech using
[Typecast](https://typecast.ai/)'s neural voices. It supports emotion control
and audio customization, and integrates Typecast's streaming text-to-speech into
a Pipecat pipeline.

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

  <Card title="PyPI Package" icon="cube" href="https://pypi.org/project/pipecat-ai-typecast/">
    The `pipecat-ai-typecast` package on PyPI
  </Card>

  <Card title="Typecast Website" icon="book" href="https://typecast.ai/">
    Learn more about Typecast's text-to-speech voices
  </Card>

  <Card title="API Keys" icon="key" href="https://typecast.ai/developers/api/api-key">
    Create and manage your Typecast API keys
  </Card>
</CardGroup>

## Installation

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

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

## Prerequisites

### Typecast Account Setup

Before using the Typecast TTS service, you need:

1. **Typecast Account**: Sign up at [Typecast](https://typecast.ai/)
2. **API Key**: Create a key from the [Typecast API key page](https://typecast.ai/developers/api/api-key)

### 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

<ParamField path="aiohttp_session" type="aiohttp.ClientSession" required>
  Active aiohttp client session used for Typecast API requests.
</ParamField>

<ParamField path="api_key" type="str" default="None">
  Typecast API key. Falls back to the `TYPECAST_API_KEY` environment variable if
  not provided.
</ParamField>

<ParamField path="voice_id" type="str" default="None">
  Voice ID to use. Falls back to the `TYPECAST_VOICE_ID` environment variable,
  or the service's built-in default voice.
</ParamField>

<ParamField path="model" type="str" default="ssfm-v30">
  Typecast model version. Use `ssfm-v30` (default) or the legacy `ssfm-v21`.
</ParamField>

<ParamField path="base_url" type="str" default="https://api.typecast.ai/v1/text-to-speech">
  Typecast API endpoint URL.
</ParamField>

<ParamField path="sample_rate" type="int" default="44100">
  Audio sample rate in Hz.
</ParamField>

<ParamField path="params" type="TypecastInputParams" default="None">
  Advanced configuration parameters for language, seed, emotion, and audio
  output. See [Input Parameters](#input-parameters) below.
</ParamField>

### 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`. |

<Note>
  Available parameters and defaults are defined by the integration and the
  selected Typecast model. See the [source
  repository](https://github.com/neosapience/pipecat-typecast) for the
  authoritative, up-to-date list.
</Note>

## Usage

```python theme={null}
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`](https://github.com/neosapience/pipecat-typecast/blob/main/example.py)
in the source repository for a complete working bot.

## Compatibility

Tested with Pipecat v0.0.94+. Check the [source
repository](https://github.com/neosapience/pipecat-typecast) for the latest
tested version and changelog.