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

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](https://dev.hume.ai/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.

```plaintext
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:**

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

```python
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:

```python
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`:

```python
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:

```python
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](https://dev.hume.ai/docs/text-to-speech-tts/overview)  
Learn more about Hume’s speech-language model, and features of Hume’s TTS API.

---