> This page is for Audio Decisions. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://dev.hume.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server. # Primitives **A primitive is the type of a question, and it sets what the answer describes.** Answers to `noul`, `choice` and `score` questions estimate how a panel of human raters would respond to the question: each probability is the estimated share of raters who would give that answer. A `span` answer locates an event in the audio and gives the time spans where it may occur.
Primitive Asks The answer gives
[`noul`](#noul) Whether something is true of the audio. The share of raters who would answer yes.
[`choice`](#choice) Which of several options applies. Each option's share of raters, and the option with the largest share.
[`score`](#score) Where the audio falls on an ordered scale. Each level's share of raters, and the mean level.
[`span`](#span) When an event occurs. The time spans where the event may occur, each with a probability.
> **Info** > > **`span` is experimental.** Ongoing training is refining how precisely the model locates events. The question and answer formats are stable. ## What the numbers describe A probability estimates the share of human raters who would give that answer, so a value near 0.5 means raters would split, not that the model is unsure. `confidence` measures how much raters would agree, not how certain the model is. ## What the model reads For each question, the model reads: 1. The question's `instructions`. 2. The question's `criteria`: a `noul` question's `true` and `false` guidance, each `choice` option's `name` with its `description` when it has one, or the text of each `score` level. 3. The request's `context`. 4. The audio. A `noul`, `choice` or `score` answer estimates how raters would respond if they heard the audio and read the same question, criteria and context. All the questions in a request are answered in one model inference, so an answer can change when other questions are added, removed or reordered. To compare answers across recordings, send the same questions in the same order. Each question is keyed by an ID you choose, such as `agent_tone`, which can be any non-empty string of up to 256 characters. The response returns each answer under the same ID. ## Choosing a primitive 1. **Use `noul` for a yes or no question.** A `noul` answer is a share of raters, not a degree: 0.6 means an estimated 60% of raters would answer yes, not that the answer is "somewhat yes". To measure degree, such as how natural a voice sounds, use `score`. 2. **Use `choice` when the options have no order, and `score` when they do.** Tone (warm, neutral, curt) is a `choice`. Naturalness from "Not at all" to "Extremely" is a `score`, because its levels have an order that the answer's mean level and `confidence` take into account. 3. **Use `span` to find when an event occurs, and `noul` to ask whether it occurs.** A `span` answer gives times but no share of raters, and a `noul` answer gives a share of raters but no times. #### [Writing questions](/audio-decisions/docs/writing-questions) Learn how to word instructions and criteria so questions get useful answers. #### [Interpreting answers](/audio-decisions/docs/interpreting-answers) Learn how to read each answer and set thresholds for acting on it. ## noul **A `noul` question asks a yes or no question.** Each rater would answer yes or no, and the answer is the estimated share who would answer yes. The name comes from the Bernoulli distribution, which describes a single yes or no outcome. `criteria` is optional. Add it when what counts as yes or no is not clear from the question alone. #### Question ```json { "questions": { "talks_over_caller": { "type": "noul", "instructions": "Does the agent talk over the caller?", "criteria": { "true": "The agent starts speaking while the caller is still mid-sentence.", "false": "The agent waits for the caller to finish, or overlaps only with a brief acknowledgement such as \"mm-hmm\"." } } } } ``` **`criteria.true`** What counts as a yes answer. --- **`criteria.false`** What counts as a no answer. --- #### Answer ```json { "talks_over_caller": { "type": "noul", "noul": 0.1274 } } ``` **`noul`** The estimated share of human raters who would answer yes, from 0 to 1. --- Does the agent talk over the caller? Yes 0.13 0 0.5, raters split 1 An estimated 13% of raters would say the agent talks over the caller. A `noul` answer has no `confidence`, because the share already shows how raters would split: they agree most when `noul` is near 0 or 1, and least when it is near 0.5. ## choice **A `choice` question asks which of two or more unordered options applies.** Each rater would choose one option, and the answer gives the estimated share of raters who would choose each. The options are presented to the model in the order listed. #### Question ```json { "questions": { "agent_tone": { "type": "choice", "instructions": "Which best describes the tone of the agent?", "criteria": [ { "name": "warm", "description": "Warm and friendly toward the caller" }, { "name": "neutral", "description": "Polite but impersonal" }, { "name": "curt", "description": "Short or dismissive with the caller" } ] } } } ``` **`criteria[].name`** — required The option, unique within the question. The model reads it and answers are keyed by it, so make it short and self-explanatory. --- **`criteria[].description`** More detail on when the option applies, which the model reads along with the name. --- #### Answer ```json { "agent_tone": { "type": "choice", "choice": "warm", "confidence": 0.3072, "probabilities": { "warm": 0.5381, "neutral": 0.3926, "curt": 0.0693 } } } ``` **`choice`** The name of the option with the highest probability: the option with the largest share of raters, which can be less than half. --- **`confidence`** How much human raters would agree, from 0 to 1. --- **`probabilities`** The estimated share of raters who would choose each option, keyed by option name. Together they sum to 1, within rounding. --- Which best describes the tone of the agent? warm 0.54 neutral 0.39 curt 0.07 0 0.5 1 About 54% of raters would call the agent warm and 39% neutral. `warm` is the most common choice, but raters would split between the first two options. `confidence` measures how far the top option's share stands above an even split across all options. It is 0 when every option is equally likely, and 1 when every rater would choose the same option. With `n` options and a top probability of `p_max`: #### choice confidence ```text confidence = (p_max - 1/n) / (1 - 1/n) ``` For the answer above, `(0.5381 - 1/3) / (1 - 1/3)` gives 0.3072. Only the top share counts, so the split among the other options does not change `confidence`. ## score **A `score` question asks where the audio falls on a scale of two or more ordered levels.** Each rater would choose one level, and the answer gives the estimated share of raters who would choose each. List the levels in `criteria` from lowest to highest. They are indexed from 0, and the model reads each level's text. #### Question ```json { "questions": { "naturalness": { "type": "score", "instructions": "How natural does the voice sound?", "criteria": ["Not at all", "2", "3", "4", "Extremely"] } } } ``` #### Answer ```json { "naturalness": { "type": "score", "score": 2.9167, "confidence": 0.4503, "probabilities": { "0": 0.0186, "1": 0.0642, "2": 0.1873, "3": 0.4417, "4": 0.2882 }, "legend": { "0": "Not at all", "1": "2", "2": "3", "3": "4", "4": "Extremely" } } } ``` **`score`** The mean level raters would choose: the probability-weighted mean of the level indices, from 0 to the index of the highest level. --- **`confidence`** How much human raters would agree, from 0 to 1. --- **`probabilities`** The estimated share of raters who would choose each level, keyed by level index as a string. Together they sum to 1, within rounding. --- **`legend`** The text of each level, keyed by level index like `probabilities`. Read levels through `legend` rather than relying on the key order of a JSON object. --- How natural does the voice sound? 0.02 0.06 0.19 0.44 0.29 Not at allindex 0 2index 1 3index 2 4index 3 Extremelyindex 4 Mean level 2.92 Level indices count from 0, so they differ from this scale's labels: index 1 is the level labeled "2", and index 3 is the level labeled "4". `legend` maps each index back to its text. The most common rating is index 3 ("4"), chosen by about 44% of raters. The mean level of 2.9167 sits just below index 3, pulled down by the raters who would choose lower levels. The same `score` can come from different splits. A `score` of 2 on this scale results when most raters would choose index 2, and also when raters would split between the two ends of the scale. Read `probabilities` and `confidence` to tell these apart. Two answers with a `score` of 2 Most raters would choose index 2`confidence` 0.68 0.03 0.13 0.68 0.13 0.03 0 1 2 3 4 Mean level 2 Raters would split between the two ends`confidence` 0 0.34 0.12 0.08 0.12 0.34 0 1 2 3 4 Mean level 2 `confidence` measures how closely raters would cluster around the median level, compared with raters spread evenly across every level. Shares one level away from the median lower it less than shares at the far end of the scale. It is 1 when every rater would choose the same level, and 0 when the shares are at least as spread out as an even split. With `p_i` the share for level `i`, `m` the median level, and `MAD_u` the mean absolute deviation of an even split over the same levels: #### score confidence ```text confidence = max(0, 1 - sum_i(p_i * |i - m|) / MAD_u) ``` For the answer to "How natural does the voice sound?", the median level is 3, the weighted distance from it is 0.6597, and `MAD_u` for five levels is 1.2, which gives `1 - 0.6597 / 1.2` = 0.4503. In the two answers with a `score` of 2, `confidence` is 0.68 when most raters would choose index 2, and 0 when raters would split between the two ends. ## span **A `span` question asks when an event occurs in the audio.** It takes no `criteria`. The answer lists the time spans where the model locates the event, each with the model's estimate that the event occurs in it. `span` is experimental: ongoing training is refining how precisely the model locates events, and the question and answer formats are stable. It is most reliable for vocal bursts, such as laughs and sighs, and for sound events, such as a phone ringing. #### Question ```json { "questions": { "vocal_bursts": { "type": "span", "instructions": "When does the speaker laugh, sigh, gasp or make another vocal burst?" } } } ``` #### Answer ```json { "vocal_bursts": { "type": "span", "spans": [ { "audio_start_ms": 9840, "audio_end_ms": 10630, "probability": 0.9127 }, { "audio_start_ms": 27450, "audio_end_ms": 28390, "probability": 0.8364 } ] } } ``` **`spans`** The time spans where the event may occur, in order of `audio_start_ms`. Overlapping candidates are merged into one span. An empty array means the event was not found. --- **`spans[].audio_start_ms, spans[].audio_end_ms`** Where the span begins and ends, in milliseconds from the start of the audio file. --- **`spans[].probability`** The model's estimate that the event occurs in the span, from 0 to 1. --- When does the speaker laugh, sigh, gasp or make another vocal burst? 9.8 to 10.6 sProbability 0.91 27.5 to 28.4 sProbability 0.84 0 s 10 s 20 s 30 s The model locates vocal bursts at about 9.8 and 27.5 seconds into the file. ## Invalid questions A question that does not match its primitive's schema is rejected with `question_invalid`, and `param` points to where the error was found, which can be the question rather than the field. This includes a `choice` question with fewer than two options or more than 20, or with duplicate names, a `score` question with fewer than two levels or more than 10, or with duplicate levels, and a question whose `instructions` or criteria text is longer than its limit. See [Limits](/audio-decisions/docs/limits#questions-and-context) and [Errors](/audio-decisions/docs/errors). ## Next steps #### [Writing questions](/audio-decisions/docs/writing-questions) Learn how to write questions that get useful answers, and which questions to avoid. #### [Interpreting answers](/audio-decisions/docs/interpreting-answers) Learn how to read each answer and set thresholds for acting on it.