Skip to content

Developer documentation

Implement a Hume speech-analysis migration

Move a speech-analysis step to Oruk by changing the request lifecycle, parser and decision rules together. Start with a saved response, test one native request, then evaluate your own audio before cutover. This guide covers implementation; the comparison guide maps current Hume and legacy endpoints separately.

1. Select the native contract

Record which Hume product, API version, scores and timestamps your application uses. Read the current-v1 and legacy-batch endpoint map before replacing a client. The model choices below are not interchangeable protocols.

  • Resonance 1: English file analysis with transcript, timed segments and optional recording-local speaker labels.
  • Spectra-2: short multilingual files, final transcript and whole-clip emotion/style scores. Optional prosody output is separate from timed emotion segments.
  • Resonance 2: expression scores without transcription, using HTTP or explicit PCM-range commits. New organizations need model approval as well as available usage.
  • Realtime: live transcript tokens and independent phrase-emotion events; rebuild stream handling around its own events.

Oruk does not replace Hume image analysis, EVI session handling, voice generation or voice IDs. For a conversation stack, see the EVI migration checklist. Hosted Hume compatibility routes remain unavailable; use the native contracts documented here.

2. Inspect a saved response first

Python 3.10 or later is sufficient for saved mode. These commands download the public example and captured JSON, then read them locally. They require no API key and submit no audio for inference.

Saved-response replay · no inference request
curl --fail --location --max-time 30 -o hume-to-oruk.py https://oruk.ai/examples/hume-to-oruk.py
curl --fail --location --max-time 30 -o saved-analysis.json https://oruk.ai/examples/acquisition/hume-replacement.json
python3 hume-to-oruk.py --saved-response saved-analysis.json

The script prints the first segment. This shorter field view comes from the same captured response; first_segment below is a presentation label, not a response field.

Selected fields from the captured November 11, 2026 response
{
  "model": "oruk-resonance",
  "duration": 14.45,
  "first_segment": {
    "speaker": "speaker_0",
    "start": 0.185,
    "end": 4.325,
    "emotions": [
      {
        "label": "disappointed",
        "score": 0.8679338097572327
      }
    ],
    "styles": [
      {
        "label": "casual",
        "score": 0.8688268065452576
      }
    ]
  }
}

Keep missing labels distinct from zero, retain timestamps in seconds, and treat speaker IDs as local to one recording. The full saved response includes transcript, segments and usage. Its execution record identifies the original request; this is integration evidence, not a quality benchmark.

3. Run one native request

Use an active Oruk account, approved account API access and available subscription or trial usage. The existing example calls POST /v1/audio/analysis with model=oruk-resonance and diarize=true. The following command consumes account usage and saves the complete successful response to a new file.

Optional live request · Python SDK
python3 -m venv .venv
. .venv/bin/activate
python -m pip install https://oruk.ai/sdk/oruk-0.2.15-py3-none-any.whl
curl --fail --location --max-time 30 -o recording.wav https://oruk.ai/samples/conversations/02-grocery-prices.wav
# Set ORUK_API_KEY in your shell first; analysis.json must not exist.
python hume-to-oruk.py --audio recording.wav --output analysis.json

The example reports API status, error code and request ID, and makes no automatic retry. A timeout can leave a processed request without a received result; inspect usage before resending. Keep keys on your server. Read the complete Python source.

Sample audio: 14.45-second grocery conversation. Open Yap 1K / The Agentic Data Company, CC BY 4.0. Future model output may differ.

4. Validate the application before switching traffic

  1. Preserve original audio, Hume output, request metadata and your application’s existing decisions.
  2. Check response units, interval boundaries, missing labels, speaker assignment and failure handling. Similar label names do not make score values comparable.
  3. Re-estimate thresholds on representative annotated audio. Acoustic expression is not a person’s inner state or verified intent.
  4. Measure complete request latency and usage under the actual selected model. Budget separate speech generation or agent services independently.
  5. Switch only after your acceptance checks pass; retain your own verified archive and an application-level recovery plan.

Compare saved legacy responses · Assess migration requirements · Subscription pricing and limits