> This page is for Voice APIs.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.hume.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server.

# Pipecat

[Pipecat](https://pipecat.ai/) is an open-source Python framework for building real-time voice and multimodal conversational agents. With Pipecat, developers can orchestrate audio and video, AI services, different transports, and conversation pipelines using a modular, frame-based architecture.

Hume's expressive TTS can be integrated into your Pipecat pipelines using the `HumeTTSService`. This guide covers setup instructions, integration patterns, and configuration best practices.

> **Info**
>
> Wanna get right to the code? See our complete [Pipecat example project](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/07ae-interruptible-hume.py) on GitHub.

## Authentication

To use the Hume TTS service with Pipecat, you'll need your Hume API credentials. Follow these steps to obtain your credentials and set up environment variables.

### Get your Hume API key

To get your Hume API key, sign in to the [Hume Platform](https://app.hume.ai/) and follow the [Getting your API key guide](/docs/introduction/api-key).

### Get your Hume voice ID

Browse the [Hume Voice Library](https://app.hume.ai/voices) to select a voice for your agent. Copy the voice ID for use in your configuration.

### Configure environment variables

Create a `.env` file in your project and define the required environment variables. The service reads your Hume API
key from the `HUME_API_KEY` variable.

#### .env

```
HUME_API_KEY=...
HUME_VOICE_ID=...
```

## Usage

The `HumeTTSService` in Pipecat can be used for conversational agents with STT → LLM → TTS pipelines. It supports word-level timestamps for precise audio-text synchronization and dynamic updates of voice and synthesis parameters at runtime.

### Basic Pipeline Integration

When using `HumeTTSService` within a Pipecat pipeline, follow these guidelines to ensure responsive performance and proper voice configuration:

* **Specify a voice**: Select from Hume's extensive [Voice Library](https://app.hume.ai/voices) or use a custom voice ID for voice consistency.

* **Configure audio sample rate**: Hume TTS streams at 48kHz. Ensure your pipeline's `audio_out_sample_rate` matches this for optimal performance.

* **Enable word timestamps**: The service supports word-level timestamps by default, which are useful for synchronizing audio with text display.

**Example implementation:**

> **Info**
>
> For a complete Pipecat implementation, see our [Pipecat example project](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/07ae-interruptible-hume.py).

#### Basic Pipeline

```python maxLines=0
import os
from dotenv import load_dotenv
from pipecat.services.hume.tts import HUME_SAMPLE_RATE, HumeTTSService
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask

load_dotenv(override=True)

async def run_bot(transport, runner_args):
    # 1. Configure the Hume TTS service
    tts = HumeTTSService(
        api_key=os.getenv("HUME_API_KEY"),
        voice_id=os.getenv("HUME_VOICE_ID"),
    )

    # 2. Configure STT and LLM services
    stt = # your STT service provider here
    llm = # your LLM service provider here

    # 3. Create your pipeline
    pipeline = Pipeline([
        transport.input(),
        stt,
        context_aggregator.user(),
        llm,
        tts,  # Hume TTS with word timestamps
        transport.output(),
        context_aggregator.assistant(),
    ])

    # 4. Configure task with matching sample rate
    task = PipelineTask(
        pipeline,
        params=PipelineParams(
            enable_metrics=True,
            enable_usage_metrics=True,
            audio_out_sample_rate=HUME_SAMPLE_RATE,  # 48000 Hz
        ),
    )

    # 5. Run the pipeline
    runner = PipelineRunner()
    await runner.run(task)
```

### Advanced Configuration

The `HumeTTSService` supports advanced configuration options including acting instructions (currently only supported in Octave 1, so this will switch your model from Octave 2 to Octave 1), speed control, and trailing silence:

#### Advanced Configuration

```python maxLines=0
from pipecat.services.hume.tts import HumeTTSService, HumeTTSService.InputParams

tts = HumeTTSService(
    api_key=os.getenv("HUME_API_KEY"),
    voice_id=os.getenv("HUME_VOICE_ID"),
    params=HumeTTSService.InputParams(
        description="calm, pedagogical",  # Acting instructions
        speed=0.8,  # Speaking-rate multiplier (0.5-2.0)
        trailing_silence=2.0,  # Seconds of silence to append (0-5)
    ),
)
```

### Runtime Configuration Updates

You can update voice and synthesis parameters at runtime using `TTSUpdateSettingsFrame`:

#### Runtime Updates

```python maxLines=0
from pipecat.frames.frames import TTSUpdateSettingsFrame

# Update voice
await task.queue_frames([
    TTSUpdateSettingsFrame(settings={"voice_id": "new-voice-id"})
])

# Update synthesis parameters
await task.queue_frames([
    TTSUpdateSettingsFrame(settings={
        "description": "excited, enthusiastic",
        "speed": 1.2,
    })
])
```

### Word Timestamps

The `HumeTTSService` supports word-level timestamps for precise audio-text synchronization. Use observers like `DebugLogObserver` to log timestamps or `RTVIObserver` to display them in your UI:

#### Word Timestamps

```python maxLines=0
from pipecat.observers.loggers.debug_log_observer import (
    DebugLogObserver,
    FrameEndpoint,
)
from pipecat.transports.base_output import BaseOutputTransport
from pipecat.frames.frames import TTSTextFrame

task = PipelineTask(
    pipeline,
    params=PipelineParams(
        enable_metrics=True,
        enable_usage_metrics=True,
        audio_out_sample_rate=HUME_SAMPLE_RATE,
    ),
    observers=[
        DebugLogObserver(
            frame_types={
                TTSTextFrame: (BaseOutputTransport, FrameEndpoint.SOURCE),
            }
        ),
    ],
)
```

## Constraints

* **Audio format support**: The `HumeTTSService` streams **PCM** audio at 48kHz. Downstream processors can resample if needed.

* **Frame-based architecture**: Pipecat uses a frame-based pipeline system. The service emits `TTSAudioRawFrame` frames suitable for Pipecat transports.

* **Word timestamps**: Word-level timestamps are enabled by default and provide precise timing information for each word in the generated speech.

* **Instant mode**: The service always uses instant mode for low-latency streaming. This is not user-configurable.

## Resources

#### [Pipecat Source Code](https://github.com/pipecat-ai/pipecat)

Explore the source code or contribute to Pipecat on GitHub.

#### [Pipecat Documentation](https://docs.pipecat.ai/)

Reference the official Pipecat docs for framework architecture and additional configuration details.

#### [Pipecat Example Project](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/07ae-interruptible-hume.py)

Use a working example to get started with Hume TTS and Pipecat in Python.

#### [Hume TTS Documentation](/docs/text-to-speech-tts/overview)

Learn more about Hume's speech-language model, and features of Hume's TTS API.

---