Detect emotion from audio in Python

Read a saved result first

These commands download a small response reader and an existing analysis result. They make no inference request and need no key or installed package.

curl --fail --location -o inspect-emotions.py https://oruk.ai/examples/inspect-emotions.py
curl --fail --location -o response.json https://oruk.ai/samples/conversations/02-grocery-prices.oruk.json
curl --fail --location -o attribution.txt https://oruk.ai/examples/call-review-attribution.txt
python3 inspect-emotions.py response.json

{
  "id": "speech_a852195bbb04415d8b506d94d5a09148",
  "task": "analysis",
  "model": "oruk-resonance",
  "duration": 14.45,
  "segments": [
    {
      "start": 0.185,
      "end": 4.325,
      "emotions": [
        {
          "label": "disappointed",
          "score": 0.8679338097572327
        }
      ]
    }
  ]
}

The second interval contains both happy and neutral. This is a multilabel output, so the labels are not mutually exclusive. A label missing from the array was not selected; its absence does not give you its raw score.

Analyze your own recording

Create a virtual environment, then install the versioned SDK. Create a key in the developer portal and set ORUK_API_KEY in your shell. Keep it out of browser code and source control.

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

1. 1. Install the SDK. Create a Python 3.10+ virtual environment, then run python -m pip install https://oruk.ai/sdk/oruk-0.2.15-py3-none-any.whl.
2. 2. Send an English recording. Set ORUK_API_KEY, then call client.emotions with model="oruk-resonance" and a supported local audio file.
3. 3. Keep and inspect the response. Save the complete JSON after success. Read selected labels from emotions, timed results from segments, and measured duration from usage.audio_seconds.

Save the following as emotion-example.py, place your recording beside it, and run python emotion-example.py. The endpoint accepts WAV, FLAC, MP3, M4A, OGG, and WebM files up to 30 MB and 60 minutes. This request uses your plan minutes.

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

# Set ORUK_API_KEY in your shell before running this file.
with Oruk(api_key=os.environ["ORUK_API_KEY"], max_retries=0) as client:
    result = client.emotions("recording.wav", model="oruk-resonance")

# Write only after a successful response. Keep the full result for inspection.
Path("emotions.json").write_text(
    json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
)
print("Audio seconds:", result["usage"]["audio_seconds"])
for emotion in result["emotions"]:
    print(emotion["label"], emotion["score"])

Run python inspect-emotions.py emotions.json to inspect the saved result. For a command-line wrapper with task and model options, download analyze-file.py. This short example disables automatic retries so a failed response does not silently resend audio.

import json
import os
import requests

with open("recording.wav", "rb") as audio:
    response = requests.post(
        "https://speech-api.oruk.ai/v1/audio/emotions",
        headers={"Authorization": f"Bearer {os.environ['ORUK_API_KEY']}"},
        files={"file": ("recording.wav", audio, "audio/wav")},
        data={"model": "oruk-resonance"},
        timeout=(10, 120),
    )
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))

Add a transcript and speaker turns

Use client.analyze when you need words and speaking styles alongside emotion. With diarize=True, Resonance returns speaker-labeled turns. The labels identify speakers within this recording; they do not identify people across recordings.

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"])

Keep each segment’s start and end times with its scores. Do not assign a recording-level score to every word, or fill an empty style array with a guessed label. For an existing Whisper pipeline, follow the Whisper plus emotion example.

When something goes wrong

Missing key or HTTP 401

Set ORUK_API_KEY in the same shell that runs Python. Confirm the key is active in your account.

HTTP 400 or an unsupported file

Check the error code, current model ID, file size, duration, and whether the file contains decodable English speech. Use oruk-resonance for diarization.

HTTP 429, server failure, or a timeout

Check your plan, rate limits, and the service status. An interrupted response does not tell you whether the server processed the recording. Inspect the request ID and usage before retrying.

A low-scoring label or no style labels

Emotion has a highest-score fallback; speaking styles do not. Preserve that distinction instead of treating every returned label as high confidence. See the score reference.