Check recording quality

Recording-quality diagnostics help your app distinguish a likely pronunciation issue from audio that may be difficult to analyze reliably. Successful speech-analysis responses can include a top-level recording_quality object. It reports signal measurements, a quality status, and a recommended way to handle the result.

Example

{
  "recording_quality": {
    "version": "1",
    "status": "marginal",
    "score_action": "confirm_negative",
    "metrics": {
      "estimated_snr_db": 17.8,
      "snr_confidence": 0.91,
      "active_speech_level_dbfs": -27.1,
      "noise_floor_dbfs": -44.9,
      "clipped_fraction": 0.0,
      "duration_sec": 1.12,
      "reverberation": {
        "risk": "moderate",
        "score": 0.54,
        "confidence": 0.71,
        "estimated_rt60_ms": null
      }
    },
    "reasons": [
      "marginal_snr",
      "moderate_reverberation"
    ],
    "recommendation": {
      "code": "move_closer_and_reduce_echo",
      "retry_recommended": false
    },
    "gate_applied": false
  }
}

Quality status

Status	Meaning
`good`	The available measurements do not indicate a recording-quality reason to distrust the result.
`marginal`	The recording may affect analysis. Confirm a negative result before giving corrective feedback.
`poor`	Noise, echo, clipping, or a very low speech level makes a new recording advisable.
`unknown`	The clip does not contain enough reliable context to make a complete quality assessment.

The initial SNR bands are:

Estimated SNR	Interpretation
`20 dB` or higher	Can be `good` when reverberation risk is also low and no other issue is detected.
`15 dB` to less than `20 dB`	`marginal`
Less than `15 dB`	`poor`

Moderate or unavailable reverberation prevents a definitive good status. High reverberation, material clipping, or extremely quiet speech can produce a poor status.

Recommended score handling

score_action describes how a future quality-aware integration can handle the pronunciation result:

Value	Recommended handling
`use_result`	Use the pronunciation result normally.
`confirm_negative`	Keep the result, but ask for another recording before acting on a negative pronunciation verdict.
`retry_recording`	Ask for a new recording before presenting corrective feedback.

For schema version 1, recommendation.code is always one of the following values:

Code	Suggested instruction
`none`	No recording change is needed.
`keep_result_but_confirm_if_negative`	Confirm the result if pronunciation analysis found an error.
`move_closer_or_reduce_noise`	Move closer to the microphone or reduce nearby noise.
`move_closer_or_find_quieter_space`	Move closer or record in a quieter space.
`move_closer_and_reduce_echo`	Move closer and record in a less echoing space.
`move_closer_and_retry`	Move closer and record again.
`reduce_input_level_and_retry`	Reduce the input level and record again.

Metrics

Field	Type	Meaning
`estimated_snr_db`	number or `null`	Estimated speech-to-background-noise ratio in decibels. Higher is cleaner.
`snr_confidence`	number	Confidence in the SNR estimate, from `0` to `1`.
`active_speech_level_dbfs`	number or `null`	Estimated active speech level relative to digital full scale.
`noise_floor_dbfs`	number or `null`	Estimated background-noise level relative to digital full scale.
`clipped_fraction`	number or `null`	Fraction of samples at or near the digital clipping limit.
`duration_sec`	number or `null`	Duration of the decoded audio used for the measurements.
`reverberation.risk`	string	Experimental `low`, `moderate`, `high`, or `unknown` reverberation risk.
`reverberation.score`	number or `null`	Experimental tail-persistence score from `0` to `1`.
`reverberation.confidence`	number	Confidence in the reverberation-risk estimate, from `0` to `1`.
`reverberation.estimated_rt60_ms`	`null`	Reserved for a future validated RT60 estimator.

SNR is returned only when the clip contains enough low-energy context and active speech to estimate both the noise floor and speech level. Otherwise, estimated_snr_db is null.

Reason codes

For schema version 1, every value in the reasons array comes from the following exhaustive set:

Reason code	Meaning
`clipping`	At least 1% of the audio samples are at or near the digital clipping limit.
`speech_too_quiet`	Active speech is below `-48 dBFS`. A new recording is recommended.
`speech_level_marginal`	Active speech is from `-48 dBFS` up to, but not including, `-40 dBFS`.
`low_snr`	A reliable estimated SNR is below `15 dB`.
`marginal_snr`	A reliable estimated SNR is from `15 dB` up to, but not including, `20 dB`.
`snr_unavailable`	SNR could not be estimated with sufficient confidence.
`excessive_reverberation`	Reverberation risk is classified as `high`.
`moderate_reverberation`	Reverberation risk is classified as `moderate`.
`reverberation_unavailable`	Reverberation risk could not be determined reliably.
`audio_metrics_unavailable`	The decoded audio is empty or has no valid sample rate, so recording metrics cannot be calculated.
`estimator_unavailable`	Recording-quality analysis failed unexpectedly; pronunciation analysis may still be available.

Getting started

Reference

Preview

Example

Quality status

Recommended score handling

Metrics

Reason codes

​Example

​Quality status

​Recommended score handling

​Metrics

​Reason codes

Example

Quality status

Recommended score handling

Metrics

Reason codes