Move your Hume Expression Measurement workload to Behavioral Signals

Quickstart

Send one recording you already sent to Hume

Every new account includes 30 minutes of behavioral batch processing, so you can run your own audio through before adding any credit. No credit card required. The SDK needs Python 3.10 or later. The REST interface is language-agnostic and covers everything the SDK does.

Step 2. Install and set credentials

pip install behavioralsignals
export BEHAVIORALSIGNALS_CID=<your-client-id>
export BEHAVIORALSIGNALS_API_KEY=<your-api-key>

Step 3. Send a recording and read the result

from behavioralsignals import Client
from behavioralsignals.utils import print_results

client = Client()
process = client.behavioral.upload_audio(file_path="call.wav")
result = client.behavioral.wait_for_result(pid=process.pid, timeout=600)
print_results(result.results)

Client() reads those two environment variables. To pass credentials in code instead, use Client("your_cid", "your_api_key"). Over REST, the key goes in the X-Auth-Token header and the client ID goes in the path, replacing Hume's X-Hume-Api-Key.

The developer reference has a live console on every endpoint, so you can call the API straight from the docs page.

Quickstart

Every field your code reads has a counterpart

Submit a recording, wait for the process, read the results. Where there is no equivalent, the table says so rather than suggesting something close.

Batch, before and after

Before, with Hume

curl -X POST https://api.hume.ai/v0/batch/jobs \
  -H "X-Hume-Api-Key: $HUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/call.wav"],
       "models": {"prosody": {"granularity": "utterance"}}}'

After, over REST. The submit call returns a process ID. Pass it to the results call.

curl -X POST \
  "https://api.behavioralsignals.com/v5/clients/$BEHAVIORALSIGNALS_CID/processes/audio" \
  -H "X-Auth-Token: $BEHAVIORALSIGNALS_API_KEY" \
  -F file=@call.wav -F name=call-0142

curl "https://api.behavioralsignals.com/v5/clients/$BEHAVIORALSIGNALS_CID/processes/$PID/results" \
  -H "X-Auth-Token: $BEHAVIORALSIGNALS_API_KEY"

Hume batch jobs could take a list of URLs. We take one recording per process, by file upload or S3 signed URL, so loop over your recordings. Files can be wav, mp3 or other non-proprietary audio encodings.

Reading the response

Hume nested results by speaker and segment. We return a flat results array. Each element names one task for one utterance id, with startTime, endTime, a prediction array and a finalLabel. Times and posteriors arrive as JSON strings, so cast them.

from collections import defaultdict

def num(s):
    return float(s) if s not in ("", None) else None

def utterances(payload):
    rows = defaultdict(dict)
    for r in payload["results"]:
        u = rows[r["id"]]
        u["start"], u["end"] = num(r["startTime"]), num(r["endTime"])
        task = r["task"]
        if task == "intensity":
            u["intensity"] = num(r["prediction"][0]["score"])
        elif task != "features":
            u[task] = r["finalLabel"]
            u[task + "_p"] = {p["label"]: num(p["posterior"])
                              for p in r["prediction"] if p.get("label")}
    return [rows[k] for k in sorted(rows, key=lambda k: rows[k]["start"])]

Each row then carries keys such as u["emotion"] and u["emotion_p"]["sad"]. In batch, utterances of one second or less return only diarization, asr and language, so those rows have no behavioral keys.

With the SDK, result.model_dump() returns the same field names as the REST payload, such as startTime and finalLabel, without by_alias=True. It also drops empty fields and adds st and et, so read optional keys with .get() if you pass its output to the parser above.

Streaming

Replace the WebSocket with a gRPC stream of 16-bit linear PCM. We take raw mono PCM at any sample rate and resample to 16 kHz. Chunks of 100 to 500 ms work best.

from behavioralsignals import Client, StreamingOptions
from behavioralsignals.utils import make_audio_stream

client = Client()
audio_stream, sample_rate = make_audio_stream("call.wav", chunk_size=0.25)
options = StreamingOptions(sample_rate=sample_rate, encoding="LINEAR_PCM")

for message in client.behavioral.stream_audio(audio_stream=audio_stream,
                                              options=options):
    handle(message.results)

Signal mapping

We have already mapped Hume's 48 prosody dimensions

Three have a class of the same meaning. 38 can be approximated from one or more outputs. Seven have no reliable proxy, and we say so rather than pointing you at the nearest-sounding label. This is a mapping by meaning, not a statistical fit between the two models, so validate it on your own audio before you rely on it.

How to read a row: "positivity = negative" means use that class's posterior, or the final label, in place of the Hume score. Where a row names two signals, combine them, usually by requiring both. Even a Direct row shares meaning, not scale, so scores and thresholds do not carry over. Re-fit them on representative audio.

How the two outputs differ

Every value is an estimate of what is expressed in the speech signal. It is not a measurement of what the speaker feels, intends or believes.

When there is no direct equivalent

Do not force one. Pointing a rule at the nearest-sounding class swaps the signal your product relied on for a different one under the same name. Three options:

For the third option, the inputs available per utterance are the class posteriors for emotion, arousal and valence, the hesitation "yes" probability, the posteriors for speaking rate and engagement, the intensity score, and the behavioral embeddings if you request them. You build and run this layer yourself: it needs your own labeled utterances to train on and a held-out set to validate against, and it does not add labels to the API's output.

Signal mapping

Port the rule, not the number

Your thresholds do not carry over, and that is the one part worth slowing down for. A Hume score and a Behavioral Signals posterior are different quantities. Keep the rule your product applies. Swap in the mapped signals. Fit a new threshold on a few hundred of your own labeled utterances.

Before, a threshold on one of Hume's 48 scores

if scores["Fear"] > 0.35:
    flag(utterance)

After, the mapped signals, with a threshold fitted on your own labels

if u["positivity_p"]["negative"] > T and u["strength"] == "strong":
    flag(utterance)

The flag, and whatever it triggers, belongs to your application. The API supplies the per-utterance estimates the rule reads.

Intent, churn risk, fraud, customer satisfaction and escalation are not API outputs. They are what an integration builds on top of the per-utterance estimates, in the same way that rules built on Hume scores were.

Talk to us about mapping your implementation.

Performance and limits

Known limits, stated plainly

Performance and limits

What we do not do

Behavioral Signals is a speech analysis API. It is not a drop-in replacement for any Hume product. If your product depends on one of these, plan a separate path for it before you cut over.

Migration

Seven steps from inventory to cutover

Most of the work is mechanical. The one part that needs care is porting rules built on Hume scores, because the two APIs' numbers mean different things.

1. 1

   Inventory. List every Hume model, option and dimension your code reads, and every rule or threshold that uses them.

2. 2

   Scope the gaps. Mark anything that used vocal bursts, text emotion, toxicity, entities or face models, and every Gap-rated prosody dimension. Decide how each gets replaced or retired.

3. 3

   Connect. Create an account, issue a key, install the SDK, and run one recording through batch.

4. 4

   Swap the client. Replace the request, polling and parsing code using the field table.

5. 5

   Port the rules. Re-express each rule over the mapped signals, then fit its thresholds on your own labeled audio.

6. 6

   Move streaming. Switch live paths to gRPC with linear PCM, choose your level, and add your own transcription if the live path needs text.

7. 7

   Cut over. Release behind a flag, compare against your held-out results, and remove the Hume dependency.

For production-scale migrations, an optional dedicated support service gives you direct engineering contact, prioritized response and named ownership, agreed per engagement.

Migration

Validating on your own audio

Hume's legacy API is no longer available, so a side-by-side run is only possible against outputs you stored before the retirement. Either way the steps are the same.

Help

Migration questions

Help

Developer resources

Backwards compatibility covers one major version, from v5. Major updates are announced in advance with migration notes.