> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dolva.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Interpreting Dolva Cognitive and Emotion Signal Values

> Learn how to read and use the cognitive and emotion signal values returned by the Dolva API, including score ranges and confidence indicators.

When Dolva analyzes an audio file, it returns a JSON object containing the detected signals. This page explains how to interpret the response, what the signal values mean, and how to use them in your application.

## Response Structure

Both analysis endpoints (`/v1/analyze/cognitive` and `/v1/analyze/emotion`) return an `application/json` body on success. The top-level structure contains a status indicator and a `signals` object with the extracted data:

```json Cognitive Response Example theme={null}
{
  "status": "ok",
  "signals": {
    "cognitive_load": 0.72,
    "clarity": 0.85
  }
}
```

```json Emotion Response Example theme={null}
{
  "status": "ok",
  "signals": {
    "valence": 0.6,
    "arousal": 0.4,
    "dominant_emotion": "calm"
  }
}
```

<Note>The exact fields in the `signals` object may vary as Dolva's models evolve. Design your integration to handle additional or missing fields gracefully — use optional chaining or null checks rather than assuming all fields are always present.</Note>

## Cognitive Signals

Cognitive signals describe the speaker's mental state as reflected in their speech patterns.

| Field            | Range         | Interpretation                                                 |
| ---------------- | ------------- | -------------------------------------------------------------- |
| `cognitive_load` | `0.0` – `1.0` | Higher values indicate greater cognitive effort or mental load |
| `clarity`        | `0.0` – `1.0` | Higher values indicate clearer, more organized speech patterns |

**Reading the scores**: values closer to `1.0` indicate stronger expression of that signal. A `cognitive_load` of `0.8` suggests high mental effort; a value of `0.2` suggests relaxed, low-effort processing.

## Emotion Signals

Emotion signals describe the affective properties of the audio.

| Field              | Range         | Interpretation                                                          |
| ------------------ | ------------- | ----------------------------------------------------------------------- |
| `valence`          | `0.0` – `1.0` | Emotional positivity: `1.0` = very positive, `0.0` = very negative      |
| `arousal`          | `0.0` – `1.0` | Energy level: `1.0` = highly activated/energized, `0.0` = calm/subdued  |
| `dominant_emotion` | string        | The strongest detected emotion (e.g., `"calm"`, `"tense"`, `"engaged"`) |

## Using Signals in Your Application

Here are practical patterns for working with the response data:

```python Python theme={null}
import requests
import os

token = os.environ["DOLVA_API_TOKEN"]

with open("audio.wav", "rb") as f:
    resp = requests.post(
        "https://api.dolva.ai/v1/analyze/emotion",
        headers={"Authorization": f"Bearer {token}"},
        files={"audio": f}
    )

data = resp.json()
signals = data.get("signals", {})

valence = signals.get("valence", None)
if valence is not None and valence < 0.3:
    print("Low valence detected — consider flagging for review")
```

## Tracking Changes Over Time

Dolva's signals are most powerful when compared across multiple recordings of the same person or conversation context. A single data point gives you a snapshot; a series of recordings reveals trends — cognitive fatigue accumulating across a workday, or emotional tone shifting across a therapy program.

Store the full response JSON alongside a timestamp and a subject identifier, then compute trends in your own data layer.

<Tip>Normalize signals to your own baseline before drawing conclusions. Individual speakers differ in their natural acoustic profiles — what counts as "high" cognitive load varies person to person.</Tip>