Pipecat | Hume API

Pipecat

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.

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.

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.

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.

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:

Example implementation:

For a complete Pipecat implementation, see our Pipecat example project.

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:

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:

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:

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

Resources