Move a legacy Hume speech workflow to oruk

Choose the output your application needs

The runnable example below uses English Resonance 1 with timed segments. Multilingual file analysis and acoustic-only analysis are available through different models. Changing a model ID can change the input limits, response shape and billing lifecycle.

These routes use existing Oruk account access and shared speech-understanding plan minutes. Check entitlement before sending customer audio. Usage receipts are not a final invoice; overlapping Resonance 2 commits are separate analyses and can consume minutes separately.

What this migration does not supply

• Hume-compatible scores, thresholds or a 48/600-dimension taxonomy
• EVI session, tool, voice or audio-generation compatibility
• First-party text-to-speech or automatic voice portability
• Face/image analysis, text sentiment or a dedicated vocal-burst API

If you are replacing a voice agent, start with the EVI planning guide. To assess your requirements, use the migration hub.

A dimension inventory, with the gaps visible

The versioned inventory covers the 48 dimensions in Hume’s legacy EVI chat-event example: 20 have candidates for investigation and 28 remain unmapped. Zero mappings are validated. Candidate names are hypotheses; the file supplies no conversion formula, score equivalence or missing-as-zero values.

Before comparing measurements, establish recording and annotation permissions, the selected model and revision, an annotation protocol and a separate held-out evaluation set. Preserve unmeasured outputs and uncertainty. This inventory describes legacy EVI dimensions; it is not a map of Hume’s current 600-plus-dimension Tagger product.

For a research project, describe the study and required measurements. Data access, capacity, model-version support and any academic allowance need confirmation before processing. No free-minute entitlement or response-time commitment is offered on this page.

Replace upload-and-poll with a file request

Install the SDK and set ORUK_API_KEY in your shell using a key from the developer portal. This example requests a transcript, emotion, speaking style, and speaker turns together. It saves the complete response before your application interprets it.

python3 -m venv .venv
# macOS / Linux. On Windows: .venv\Scripts\activate
source .venv/bin/activate
python -m pip install https://oruk.ai/sdk/oruk-0.2.15-py3-none-any.whl

Save the code below as migrate.py, put your English recording beside it as recording.wav, and run python migrate.py.

import json
import os
from pathlib import Path
from oruk import Oruk

with Oruk(api_key=os.environ["ORUK_API_KEY"], max_retries=0) as client:
    result = client.analyze(
        "recording.wav", model="oruk-resonance", diarize=True
    )

Path("analysis.json").write_text(
    json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
)
for segment in result["segments"]:
    print(segment["start"], segment["end"], segment.get("speaker"))
    print("Words:", segment.get("text"))
    print("Emotion scores:", segment["emotions"])
    print("Speaking styles:", segment["styles"])

Use client.emotions for emotion alone, or client.affect for emotion and speaking style without transcription. Diarization requires oruk-resonance. These Resonance 1 requests use English recordings. For short multilingual recordings, choose Spectra-2 and adapt to its recording-level output; it does not return these timed segments.

A successful request uses plan minutes. The example disables automatic retries; if a response is interrupted, check request details and usage before resending the recording. For a saved response you can inspect without a key, use the Python walkthrough.

Review label meaning before changing rules

The legacy Hume prosody output exposed 48 dimensions. The Resonance 1 example scores 15 emotion labels and 16 speaking styles, then returns selected labels. These names are useful starting points for a review; they are not a conversion table for scores or thresholds.

Do not turn Calmness into neutral, or Interest into energetic, simply because those labels seem related. Dimensions such as awe, nostalgia, or craving have no direct Oruk equivalent. Keep them explicitly unsupported in your application unless you build and validate a separate feature.

In this Resonance 1 response, a missing label is not a zero score. An emotion can also be returned as the highest-score fallback when no label passes its threshold. Speaking styles have no fallback and may be empty. The label and score reference defines the model-specific behavior. Resonance 2 does not force a top label; Spectra-2 returns every recording-level score.

Compare saved responses by time

Keep your archived legacy batch predictions as hume-predictions.json and the Oruk response above as analysis.json. The command below assumes you have checked that both use the same untrimmed recording and time origin. The local tool finds overlapping intervals and saves a JSON report. It requires Python 3.10+ and no additional packages, API key, or uploads.

curl --fail --location -o compare-legacy-hume.py \
  https://oruk.ai/examples/compare-legacy-hume.py
python3 compare-legacy-hume.py \
  --hume hume-predictions.json --oruk analysis.json \
  --output migration-review.json

Use the JSON array saved by the legacy job.download_predictions method, containing results.predictions[].models.prosody.grouped_predictions. If the export contains several sources, add --source-index 0 to select the first; a source with several files also requires --file-index. Choose the entries for your recording. Current Tagger responses, EVI messages, and streaming payloads use different contracts and are outside this tool’s scope.

Read the matching intervals

Each alignment entry points from an Oruk segment to every Hume interval with positive time overlap. For example, an interval from 4–6 seconds overlaps both 3–5 and 5–7 seconds by one second each. Intervals that only touch at an endpoint do not match. Overlap alone does not mean the same speaker or emotion was detected.

Keep the original evidence

The report includes the selected Hume source, complete Oruk response, original group and prediction indices, and hashes of the two input JSON files. It preserves scores and empty arrays. It does not rename labels, fill missing scores with zero, average overlapping predictions, or infer whether Oruk used a fallback.

Review what did not match

Unmatched intervals remain listed on both sides, including zero-duration intervals. A failed Hume source or missing prosody result stays visible with a note. Malformed timestamps and invalid scores stop the comparison; existing output files are never overwritten.

For an explicit local recording check, add --audio and --manifest using the comparison operator guide. The manifest binds recording and response hashes, the selected Hume entry, and each declared time origin. These checks do not prove which audio the providers processed or verify the declared alignment. Observed native labels remain unmapped, including shared names; unsupported Hume modalities and unhandled fields stay visible. The report contains your transcript and returned labels, so store it with the recording’s access permissions. This is an inspection aid, not an accuracy score or a measurement of current Hume products.

Format reference: Hume’s versioned batch response types. Download the standalone Python tool. Download the manifest template.

Validate the migration on the same recordings

1. 1. Freeze the inputs. Keep the same untrimmed audio, source hash, permitted-use record, and original responses. Exclude development speakers from the final evaluation.
2. 2. Preserve each response’s timing. Compare overlapping intervals. Do not attach labels by array position, reuse a score for every word, or treat a speaker label as a permanent identity.
3. 3. Review the application’s actual decisions. Measure precision, recall, and missed events for the labels you use. Tune thresholds on development audio and report the untouched evaluation separately.
4. 4. Keep failed and unscored cases visible. Track decode failures, timeouts, rate limits, empty style arrays, and weak fallback emotions. Dropping difficult recordings makes the migration look more reliable than it is.
5. 5. Check the full user experience. Verify request handling, response parsing, account usage, and how a person reviews an uncertain result before changing a production rule.

The local call-review example lets you replay each returned interval beside its transcript and scores. The evaluation guide explains how to measure the results. Neither replaces a study on your own workload.