> 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. # LiveKit [LiveKit](https://livekit.io/) is an open-source platform for low-latency, bi-directional audio streaming and real-time media orchestration. With [LiveKit Agents](https://docs.livekit.io/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. > **Info** > > Wanna get right to the code? See our complete [LiveKit example project](https://github.com/HumeAI/hume-api-examples/blob/main/tts/tts-python-livekit) 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](https://app.hume.ai/) and follow the [Getting your API key guide](/docs/introduction/api-key). ### Copy your LiveKit credentials Deploy a LiveKit server or use [LiveKit Cloud](https://docs.livekit.io/home/cloud/). In your project dashboard, copy the following: * `LIVEKIT_URL` – your server URL * `LIVEKIT_API_KEY` – your project’s API key * `LIVEKIT_API_SECRET` – your API secret ### 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. #### .env ``` 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](https://docs.livekit.io/agents/build/#agent-sessions) and [Standalone TTS](https://docs.livekit.io/agents/integrations/tts/#standalone-usage).
**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: * **Enable instant_mode**: Reduces latency significantly. Note that enabling `instant_mode` requires explicitly specifying a voice. * **Specify a voice**: Select from Hume’s extensive [Voice Library](https://app.hume.ai/voices) or a custom voice for voice consistency. * **Omit crafting parameters**: Parameters for crafting TTS output like `description`, `speed`, `trailing_silence`, and `context` are globally applied to all session responses. These parameters are best suited for standalone TTS. **Example implementation:** > **Info** > > For a complete AgentSession implementation, see our [LiveKit Agents example project](https://github.com/HumeAI/hume-api-examples/blob/main/tts/tts-python-livekit/src/agent_session/main.py). #### AgentSession ```python maxLines=0 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: * **One utterance per request**: LiveKit processes only a single [utterance](/docs/text-to-speech-tts/overview#glossary) per request. Split multi-part dialogue into separate requests to control delivery for each line. * **Supply acting instructions**: Use utterance options like `description`, `speed`, and `trailing_silence` to shape the delivery. See our [acting instructions guide](/docs/text-to-speech-tts/acting-instructions) for best practices. * **Provide context**: Use the context field to maintain continuity across requests. For more on how context influences output, see our [continuation guide](/docs/text-to-speech-tts/continuation). **Example implementation:** > **Info** > > For a working Standalone TTS implementation, see our [LiveKit Agents example project](https://github.com/HumeAI/hume-api-examples/blob/main/tts/tts-python-livekit/src/standalone_tts/main.py). #### Standalone TTS ```python maxLines=0 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 * **Audio format support**: The Hume TTS plugin supports **WAV**, **MP3**, and **PCM** audio formats. If no audio format is specified, it will default to MP3. * **Fixed sample rate**: The Hume TTS API outputs audio at a fixed sample rate of **48kHz**. Ensure compatibility with your audio processing pipeline. * **Output data limitations**: The plugin returns audio data with encoding details only. Additional Hume API response data (such as `generation_id`) is not included. * **Normalized TTS interface**: Due to the LiveKit Agents SDK’s normalized interface, each request must contain a single [utterance](/docs/text-to-speech-tts/overview#glossary). Split multi-utterance text into separate requests. * **Plugin options persist**: The configuration set when initializing the plugin is applied to each TTS request. To update these options during a session, use the plugin’s `update_options` method. See the [LiveKit documentation](https://docs.livekit.io/agents/integrations/tts/hume/#updating-utterance-options) for usage details. ## Resources #### [LiveKit Source Code](https://github.com/livekit/agents/tree/main/livekit-plugins/livekit-plugins-hume) Explore the source code or contribute to the Hume TTS plugin for LiveKit Agents on GitHub. #### [LiveKit Documentation](https://docs.livekit.io/agents/integrations/tts/hume/) Reference the official LiveKit docs for a full list of plugin options and additional configuration details. #### [LiveKit Example Project](https://github.com/HumeAI/hume-api-examples/tree/main/tts/tts-python-livekit) Use a working example to get started with Hume TTS and LiveKit Agents 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. ---