LiveKit | Hume API

LiveKit TTS Plugin

LiveKit is an open-source platform for low-latency, bi-directional audio streaming and real-time media orchestration. With LiveKit Agents, developers can compose voice pipelines using modular components like speech-to-text (STT), large language models (LLMs), and text-to-speech (TTS).

Hume’s expressive TTS can be integrated into your LiveKit Agents pipelines using the Hume LiveKit Agents TTS plugin. This guide covers setup instructions, integration modes, and configuration best practices.

Wanna get right to the code? See our complete LiveKit example project on GitHub.

Authentication

To use the Hume TTS plugin with LiveKit Agents, you’ll need both Hume and LiveKit 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.

Copy your LiveKit credentials

Deploy a LiveKit server or use LiveKit Cloud. In your project dashboard, copy the following:

Configure environment variables

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

HUME_API_KEY=...
LIVEKIT_URL=...
LIVEKIT_API_KEY=...
LIVEKIT_API_SECRET=...

Usage

The Hume TTS plugin for LiveKit Agents can be used for two use cases: Agent Sessions and Standalone TTS.

Mode Use case Voice Control
AgentSession Real-time conversational agents using STT → LLM → TTS pipelines. Set once at session start; consistent throughout the session.
Standalone TTS Direct text-to-speech without STT or LLM components. Set per request; customize voice and expressiveness as needed.

AgentSession

When using the Hume TTS plugin within an AgentSession, follow these guidelines to ensure responsive performance and consistent voice behavior throughout the session:

Example implementation:

For a complete AgentSession implementation, see our LiveKit Agents example project.

from livekit.agents import (
  Agent,
  AgentSession,
  JobContext,
  WorkerOptions,
  cli,
)
from livekit.plugins.hume import TTS, VoiceByName, VoiceProvider

class VoiceAssistant(Agent):
    def __init__(self):
        super().__init__(instructions="Your system prompt...")

async def entrypoint(ctx: JobContext) -> None:
    await ctx.connect()

# 1. Configure the Hume TTS plugin
    tts = TTS(
        voice=VoiceByName(
            name="Male English Actor",
            provider=VoiceProvider.hume,
        ),
        instant_mode=True,
    )

# 2. Create your AgentSession with STT/LLM as needed
    session = AgentSession(
        stt=..., # specify your STT config
        llm=..., # specify your LLM config
        tts=tts,
    )

# 3. Start the session with a greeting
    await session.start(agent=VoiceAssistant(), room=ctx.room)
    await session.generate_reply(instructions=GREETING_INSTRUCTIONS)

if __name__ == "__main__":
    cli.run_app(
        WorkerOptions(entrypoint_fnc=entrypoint)
    )

Standalone TTS

The Hume TTS plugin can be used independently for direct text-to-speech synthesis, outside of an AgentSession. This is useful when you don’t need STT or LLM components and want full control over voice selection, expressiveness, and timing on a per-request basis.

When using the plugin this way, keep the following in mind:

Example implementation:

For a working Standalone TTS implementation, see our LiveKit Agents example project.

import asyncio
from aiohttp import ClientSession
from livekit.plugins.hume import TTS
from simpleaudio import play_buffer

async def standalone_tts(text: str):
    async with ClientSession() as session:
        # 1. Configure the Hume TTS plugin
        tts = TTS(
            voice=VoiceByName(
                name="Male English Actor",
                provider=VoiceProvider.hume,
            ),
            description="calm, pedagogical",
            speed=0.65,
            trailing_silence=4,
            instant_mode=True,
            http_session=session,
        ),

# 2. Collect PCM data
        pcm_buffer = bytearray()
        async for chunk in tts.synthesize(text):
            pcm_buffer.extend(chunk.frame.data)

# 3. Play back the audio
    play_buffer(
        pcm,
        num_channels=1,     # mono
        bytes_per_sample=2, # 16-bit
        sample_rate=48000,  # 48000 Hz
    ).wait_done()

if __name__ == "__main__":
    asyncio.run(
        standalone_tts("Let us begin by taking a deep breath...")
    )

Constraints

Resources