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

# HumeAudioClassifier

> HumeAudioClassifier and HumeAudioDecisionsClient answer classifier questions about a clip of audio through Hume's Audio Decisions API.

## Overview

`HumeAudioClassifier` answers [classifier questions](https://docs.pipecat.ai/api-reference/server/classifiers/overview.md) about a clip of audio through Hume's Audio Decisions API. Hume hears the clip, and answers most questions best with 5 seconds or more of it. It reads the state as the clip's context, such as who is speaking and what they said. All the questions about one clip go to Hume in one request. Its probabilities estimate the share of human raters who would give each answer.

A `HumeAudioClassifier` asks through a `HumeAudioDecisionsClient`, which holds the HTTP/2 connection, adds the auth header, retries when Hume is busy, and counts tokens. Build the classifier with an API key to give it a client of its own, or pass a `HumeAudioDecisionsClient` to share one connection between several classifiers.

> [card] [Expressive Conversation](https://github.com/pipecat-ai/pipecat/blob/main/examples/expressive-conversation/expressive-conversation-hume-audio-decisions.py)
>
> A voice bot that reads how the user sounds with Hume and adapts its replies.

## Installation

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

## Prerequisites

A Hume API key, usually set as an environment variable:

```bash theme={null}
HUME_API_KEY=...
```

## Configuration

### HumeAudioClassifier

```python theme={null}
from pipecat.classifiers.hume.audio_decisions.classifier import HumeAudioClassifier
```

**api\_key** `str | None` (default: None)

Hume API key, when the classifier should have a client of its own. One of
`api_key` and `client` is required.

**client** `HumeAudioDecisionsClient | None` (default: None)

A client to share with other classifiers. One of `api_key` and `client` is
required.

**base\_url** `str` (default: [https://api.cloud.hume.ai](https://api.cloud.hume.ai))

Where a client of its own sends its questions.

**timeout** `float` (default: 10.0)

Seconds a client of its own waits for an answer before raising
`ClassifierError`.

**name** `str | None` (default: None)

Name of the classifier, as it appears in logs and metrics.

### HumeAudioDecisionsClient

```python theme={null}
from pipecat.classifiers.hume.audio_decisions.client import HumeAudioDecisionsClient
```

**api\_key** `str` *required*

Hume API key.

**base\_url** `str` (default: [https://api.cloud.hume.ai](https://api.cloud.hume.ai))

Where the API is served.

**timeout** `float` (default: 10.0)

Seconds to wait for a reply before raising `ClassifierError`.

**max\_retries** `int` (default: 2)

How many times to retry a request Hume couldn't answer because it was busy
(HTTP 429, 500 or 503).

## Usage

### Basic Usage

Every call needs exactly one clip in `inputs`. A call without one raises `ClassifierError`.

```python theme={null}
import os

from pipecat.classifiers.base_classifier import ClassifierAudio, YesNoQuestion
from pipecat.classifiers.hume.audio_decisions.classifier import HumeAudioClassifier

classifier = HumeAudioClassifier(api_key=os.getenv("HUME_API_KEY"))

clip = ClassifierAudio(audio=pcm_bytes, sample_rate=16000)  # 1 second to 5 minutes
results = await classifier.yes_no(
    "A caller on the phone.",
    {"angry": YesNoQuestion(instructions="Does the caller sound angry?")},
    inputs=[clip],
)
results["angry"].probability
```

### Reading How the User Sounded

Give the classifier, with its questions, to a [`PerceptionSource`](https://docs.pipecat.ai/api-reference/server/expressive/overview#perceptionsource) of a [`PerceptionReader`](https://docs.pipecat.ai/api-reference/server/expressive/overview#perceptionreader), which cuts a clip of the user's speech each time they stop speaking and adds the answers to the transcription's `perception`.

### Sharing a Client

Several classifiers can share one `HumeAudioDecisionsClient`, and with it one connection pool and one token count:

```python theme={null}
from pipecat.classifiers.hume.audio_decisions.client import HumeAudioDecisionsClient

client = HumeAudioDecisionsClient(api_key=os.getenv("HUME_API_KEY"))
first = HumeAudioClassifier(client=client)
second = HumeAudioClassifier(client=client)
```

A client the classifier created is closed in the classifier's `cleanup()`. A shared client is left open, so close it yourself with `await client.close()` when every classifier using it is done.

### Opening the Connection Early

`setup()` opens the connection to Hume ahead of the first question. Components that own a classifier, such as `PerceptionReader`, call it for you. If the connection cannot be opened at setup, a warning is logged and the first question opens it instead.

## HumeAudioClassifier Properties

| Property | Type | Description |
| - | - | - |
| `client` | `HumeAudioDecisionsClient` | The client this classifier asks through. |
| `supports_audio` | `bool` | Always `True`: Hume hears audio. |
| `min_audio_secs` | `float` | `1.0`: the shortest clip Hume hears. |
| `preferred_audio_secs` | `float` | `5.0`: the clip length Hume answers best with. |
| `max_audio_secs` | `float` | `300.0`: the longest clip Hume hears. |
| `audio_sample_rate` | `int` | `16000`: clips are resampled to 16 kHz before they're sent. |

## HumeAudioDecisionsClient Reference

### Properties

| Property | Type | Description |
| - | - | - |
| `usage` | `HumeAudioDecisionsUsage` | Input tokens billed so far over every request, as `input_tokens`. |

### Methods

#### connect

```python theme={null}
await client.connect()
```

Opens the connection to Hume with a lightweight request that also checks the key. It counts toward the rate limit like any request. It connects once: a client shared by several classifiers is connected by each of them, and only the first call sends anything. Raises `ClassifierError` if Hume could not be reached or refused the request.

#### close

```python theme={null}
await client.close()
```

Closes the connection pool.

## Metrics

After every call, a `HumeAudioClassifier` reports the time it took as `ProcessingMetricsData` and the input tokens used as `LLMUsageMetricsData` through its [`on_metrics`](https://docs.pipecat.ai/api-reference/server/classifiers/overview#on_metrics) event.

## Notes

* **Context**: the state is sent to Hume as the clip's context, as text or as JSON for structured state. Hume reads at most 1000 characters of it, so a longer state keeps its last 1000 characters. The limit is available as `HUME_MAX_CONTEXT` in `pipecat.classifiers.hume.audio_decisions.classifier`.
* **Audio**: a call takes exactly one clip in `inputs`; any other number raises `ClassifierError`. Clips are sent as 16 kHz mono WAV, which is how the model hears them.
* **Images**: `HumeAudioClassifier` cannot see images. Passing some raises `ClassifierError`.
* **Errors**: a rejected request, a busy Hume after every retry, an unreachable server, or a reply missing an answer all raise `ClassifierError`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.