Integrations

Pipecat

Guide to integrating Hume TTS via the Pipecat framework.

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

1

Get your Hume API key

To get your Hume API key, sign in to the Hume Platform and follow the Getting your API key guide.

2

Get your Hume voice ID

Browse the Hume Voice Library to select a voice for your agent. Copy the voice ID for use in your configuration.

3

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

Basic Pipeline
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
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
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
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

Explore the source code or contribute to Pipecat on GitHub.

Pipecat Documentation

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

Pipecat Example Project

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

Hume TTS Documentation

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