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

# Check recording quality

> Use SNR and reverberation diagnostics to identify recordings that may need confirmation or a retry

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

```json theme={null}
{
  "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.     |