/docs · General · Intro

Read a response: what each field means and how far to trust it

A real answer from the API, field by field: what it says, its status and margin, and what you may and may not conclude from it.

A real answer, annotated

This is a real answer from POST /v1/voicelab/qa with "round": true and "measureStatus": true. The file is a synthetic voice that you can analyse yourself: https://audiolab.tools/samples/voice/speech-male-plain.mp3.

{
  "durationSec": 32.193,
  "speechRatio": 0.644,
  "longSilences": 2,
  "averageSpeechRmsDb": -30.75,
  "noiseFloorDb": -76.33,
  "signalToNoiseDb": 45.58,
  "clipping": { "count": 0, "severity": "None" },
  "sceneBackground": "unsteady",
  "activeKind": "music",
  "roomEchoScore": 0.223,
  "sibilanceRisk": "Low",
  "measureStatus": {
    "legend": "https://audiolab.tools/docs/start/read-a-response#the-five-statuses",
    "measures": {
      "roomEchoScore": {
        "status": "withdrawn",
        "method": "dsp",
        "lens": "voice.roomEcho"
      },
      "signalToNoiseDb": {
        "status": "validated",
        "basis": "analytic",
        "method": "dsp",
        "lens": "voice.snr",
        "margin": {
          "plusMinus": 6,
          "unit": "dB",
          "note": "Holds for read speech with steady background noise at..."
        }
      },
      "speechRatio": {
        "status": "proxy",
        "method": "dsp",
        "lens": "voice.speechRatio"
      }
    }
  }
}

A cut-down answer: 11 of its 50 fields, and 3 of the entries in measureStatus. The note of the margin is shortened here and shown in full below.

speechRatio 0.644 Proxy

The share of the recording where the voice is loud enough to count as speech. It reads about 12 points low on clean speech: soft word starts and endings count as pause.
longSilences 2 Proxy

Pauses longer than 1.5 s between stretches of speech. Compare vendors on the same text.
averageSpeechRmsDb -30.75 Validated

How loud the voice is while it speaks, in dBFS.
noiseFloorDb -76.33 Validated

The level of the quietest tenth of the recording: the background.
signalToNoiseDb 45.58 Validated

Holds within its margin when the true ratio is 10 to 30 dB with steady noise. Above about 50 dB it only says that the pauses are very quiet, often digital silence. This sample is far above the range where the margin holds, so read it as "very clean", not as a precise figure.

Margin ±6 dB. Holds for read speech with steady background noise at a true ratio of 10 to 30 dB (90 percent of cases). Below 10 dB it reads too high, by 3 dB or more.
clipping { "count": 0, "severity": "None" } Validated

No samples were flattened.
sceneBackground "unsteady" Proxy

One word for what fills the pauses. Tested on synthetic scenes only, not on real recordings. On this clean synthetic voice it says "unsteady": do not read it as a fact about the room.
activeKind "music" Proxy

A guess at the kind of sound. It says "music" for this voice: another reason to treat guesses as guesses.
roomEchoScore 0.223 Withdrawn

Not a reverb measure: it tracked measured reverberation times at Spearman 0.06. It stays in the answer so nothing breaks. At most it says how much energy is left in the pauses.
sibilanceRisk "Low" Proxy

Low, Medium or High. Only the direction is tested: more energy around 7 kHz moves it up.

Reproduce it:

curl -s https://audiolab.tools/v1/voicelab/qa \
  -H "Authorization: Bearer $AUDIOLAB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://audiolab.tools/samples/voice/speech-male-plain.mp3","round":true,"measureStatus":true}'

Without a key you get a trial of 20 calls a month, 3 a minute.

The five statuses

Every measure carries one of five words. They are the same words and colours on /lenses, in the OpenAPI document, in the labs and in the measureStatus of an answer.

Validated

Tested against a standard or against a known value, and the page says which. You can state the number. If there is a margin, stay inside it. Read "Tested against" on /lenses for the conditions: a measure tested on built signals is exact for what it computes, not necessarily meaningful on every real recording.

Proxy

An approximation. Only the direction is tested, or the limits were chosen by hand, or it leans on something that was measured and found imperfect. Use it to compare two recordings, not to state a fact.

Beta

No ground-truth test yet. It may be right; it is not shown to be. It can change. New measures start here.

Withdrawn

The claim failed its test. The field can still be in the answer so that nothing breaks, but do not read it as what its name promised. Its entry on /lenses says what is left to read, if anything, and why it was withdrawn.

Planned

In the list of measures, not built yet. It is not in any answer.

What you may conclude

You see	You may say	You may not say
Validated, with a margin	The number, with its margin: “22 dB, give or take 6”	That a gap between two recordings that is smaller than the margin is a real difference
Validated, no margin	The number is right for what it measures	That it means more than its description: read “What it is not” on /lenses
Proxy	”Vendor A leaves more pauses than vendor B on the same text"	"A speaks 64% of the time”, “the room is unsteady”
Withdrawn	Only what its entry on /lenses still stands behind	What the old name promised: `roomEchoScore` is not a room measure

A margin is how far the number can be off. It comes from the standard the measure was tested against or from our own measurements on real recordings, and the answer says which conditions it holds for.

Where the numbers come from

The API, the labs, the MCP servers and /lenses all read the same list of measures, so a status cannot differ between them. When a measure is tested again and moves, the change is in the changelog and the answer shows the new status the next time you ask. How changes are announced: changes and deprecation.