> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hume

> Text-to-speech service using Hume AI's expressive Octave models with word timestamps

## Overview

Hume provides expressive text-to-speech synthesis using their Octave models, which adapt pronunciation, pitch, speed, and emotional style based on context. `HumeTTSService` offers real-time streaming with word-level timestamps, custom voice support, and advanced synthesis controls including acting instructions, speed adjustment, and trailing silence configuration.

<CardGroup cols={2}>
  <Card title="Hume TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.hume.tts.html">
    Pipecat's API methods for Hume TTS integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-hume.py">
    Complete example with word timestamps and interruption handling
  </Card>

  <Card title="Hume Documentation" icon="book" href="https://dev.hume.ai/docs/text-to-speech-tts/overview">
    Official Hume TTS API documentation and features
  </Card>

  <Card title="Voice Library" icon="microphone" href="https://dev.hume.ai/docs/text-to-speech-tts/voices">
    Browse and manage available voices
  </Card>
</CardGroup>

## Installation

To use Hume services, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[hume]"
```

## Prerequisites

### Hume Account Setup

Before using Hume TTS services, you need:

1. **Hume Account**: Sign up at [Hume AI](https://www.hume.ai/)
2. **API Key**: Generate an API key from your account dashboard
3. **Voice Selection**: Choose voice IDs from the voice library or create custom voices

### Required Environment Variables

* `HUME_API_KEY`: Your Hume API key for authentication

## Configuration

### HumeTTSService

<ParamField path="api_key" type="str" default="None">
  Hume API key. If omitted, reads the `HUME_API_KEY` environment variable.
</ParamField>

<ParamField path="voice_id" type="str" required deprecated>
  ID of the voice to use. Only voice IDs are supported; voice names are not.

  *Deprecated in v0.0.105. Use `settings=HumeTTSService.Settings(...)` instead.*
</ParamField>

<ParamField path="sample_rate" type="int" default="48000">
  Output sample rate for PCM frames. Hume TTS streams at 48kHz.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  Runtime-configurable synthesis controls. See [InputParams](#inputparams)
  below.

  *Deprecated in v0.0.105. Use `settings=HumeTTSService.Settings(...)` instead.*
</ParamField>

<ParamField path="settings" type="HumeTTSService.Settings" default="None">
  Runtime-configurable settings. See [Settings](#settings) below.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `HumeTTSService.Settings(...)`. These can be updated mid-conversation with `TTSUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter          | Type              | Default     | Description                            |
| ------------------ | ----------------- | ----------- | -------------------------------------- |
| `model`            | `str`             | `None`      | Model identifier. *(Inherited.)*       |
| `voice`            | `str`             | `None`      | Voice identifier. *(Inherited.)*       |
| `language`         | `Language \| str` | `None`      | Language for synthesis. *(Inherited.)* |
| `description`      | `str`             | `NOT_GIVEN` | Description to guide voice synthesis.  |
| `speed`            | `float`           | `NOT_GIVEN` | Speech rate control.                   |
| `trailing_silence` | `float`           | `NOT_GIVEN` | Trailing silence duration in seconds.  |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.hume import HumeTTSService

tts = HumeTTSService(
    api_key=os.getenv("HUME_API_KEY"),
    settings=HumeTTSService.Settings(
        voice="your-voice-id",
    ),
)
```

### With Acting Directions

```python theme={null}
tts = HumeTTSService(
    api_key=os.getenv("HUME_API_KEY"),
    settings=HumeTTSService.Settings(
        voice="your-voice-id",
        description="Speak warmly and reassuringly",
        speed=1.1,
        trailing_silence=0.5,
    ),
)
```

### Updating Settings at Runtime

Voice and synthesis parameters can be changed mid-conversation using `TTSUpdateSettingsFrame`:

```python theme={null}
from pipecat.frames.frames import TTSUpdateSettingsFrame
from pipecat.services.hume.tts import HumeTTSSettings

await task.queue_frame(
    TTSUpdateSettingsFrame(
        delta=HumeTTSSettings(
            speed=1.3,
            description="Speak with excitement",
        )
    )
)
```

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Notes

* **Fixed sample rate**: Hume TTS streams at 48kHz. Setting a different `sample_rate` will produce a warning.
* **Word timestamps**: The service provides word-level timestamps for synchronized text display. Timestamps are tracked cumulatively across utterances within a turn.
* **Description versions**: When `description` is provided, the service uses Hume API version `"1"`. Without a description, it uses the newer version `"2"`.
* **Audio buffering**: Audio is buffered internally until a minimum chunk size is reached before being pushed as frames, reducing audio glitches.