> ## 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.

# Output reference

> Field-by-field guide to the Speech API JSON response

## Overview

The API returns a single JSON object describing per‑phoneme scoring, edits, and prosody.

## Top‑level fields

* `language`, `dialect`: Language settings used during analysis (e.g., `language: "en"`, `dialect: "en-us"`).
* `match_score_mode`: Scoring style used for `match_score_pct`. `lenient` is the default and gives near-matches some credit. `strict` only gives credit for accepted matches.
* `model`: Optional public model selector. Send `aurora-1` for multilingual adult speech, `nova-1` for early-childhood speech, or leave it unset for standard English analysis. The response phone predictions and `topk` values follow the selected analysis mode.
* `reference_text`: Text used for alignment. If you supply `text`, this is that value; otherwise it is the auto‑transcription.
* `reference_phones`: IPA phone sequence derived from the reference (array of tokens).
* `predicted_phones`: IPA phone sequence predicted from the audio (array of tokens).
* `audio`: `{ duration_sec }` for the analyzed clip.
* `audio_duration_sec`: Audio duration in seconds (top-level convenience alias).
* `pause_threshold_sec`: Minimum gap size (seconds) used to count a pause.
* `pauses`: List of detected pause spans from model phone timings.
* `pause_metrics`: Aggregate pause statistics for the utterance.
* `speech_rate_wpm`: Words per minute including silence.
* `articulation_rate_wpm`: Words per minute excluding detected silence.
* `rate_metrics`: Expanded speaking-rate object with word count and speaking-time details.
* `summary`: Aggregate accuracy metrics and counts.
* `word_groups`: Intended/reference words used for pronunciation scoring, with canonical IPA, aligned phones, and summaries.

Optional fields (present when available):

* `recording_quality`: Preview signal-quality measurements and recommended
  result handling. It does not change pronunciation scores or grades. See
  [Recording quality](/recording-quality).
* `transcription`: Auto-transcribed text with word timings, timestamped surface-phone observations, and, in verbatim mode, normalized speech events. See [Transcription modes](/transcription-modes).
* `pronunciation_lattice`: Pronunciation selection metadata (when `pronunciation_debug=true`).
* `proficiency_metrics`: Fluency, prosody, and intelligibility scores (when `enable_proficiency_metrics=true`).

## Recording quality

The optional top-level `recording_quality` preview describes whether noise,
speech level, clipping, or reverberation may make the pronunciation result less
reliable. It includes:

* `status`: `good`, `marginal`, `poor`, or `unknown`;
* `score_action`: `use_result`, `confirm_negative`, or `retry_recording`;
* `metrics`: estimated SNR, speech and noise levels, clipping, duration, and
  experimental reverberation risk;
* `reasons`: stable machine-readable reason codes;
* `recommendation`: a stable instruction code and whether a retry is
  recommended;
* `gate_applied`: always `false` during the preview.

See [Check recording quality](/recording-quality) for the complete schema,
thresholds, and integration guidance.

## Summary object

* `avg_match_score_pct`: Mean match score across phones.
* `total_phones`: Number of target phones included in the summary.
* `matches`: Count of phones graded `match`.
* `num_insertions`: Count of inserted phones.
* `num_deletions`: Count of deleted phones.
* `num_substitutions`: Count of substituted phones.

```json theme={null}
{
  "summary": {
    "avg_match_score_pct": 96.37,
    "total_phones": 648,
    "matches": 511,
    "num_insertions": 19,
    "num_deletions": 44,
    "num_substitutions": 100
  }
}
```

## Word groups

Each entry in `word_groups` includes:

* `index`: Zero‑based word index.
* `text`: Word text from the reference.
* `ipa`: IPA phone sequence for that word (array of tokens).
* `syllables`: Written syllable chunks and their canonical-phone spans. Supported
  requests can also include preview lexical-stress metadata. See
  [Lexical stress](/lexical-stress).
* `phones`: Phone entries belonging to the word.
* `insertions`: Extra predicted phones aligned within this word’s span that do not appear in the reference for that word.
* `summary`: Per‑word aggregates.
* `prosody`: Word‑level pitch and stress contours (when `enable_prosody_contours=true`).

Optional (when available):

* `acceptable_pronunciations`: Candidate pronunciations.
* `selected_pronunciation`: Chosen pronunciation.
* `selected_pronunciation_index`: Index into `acceptable_pronunciations`.

Each item in `insertions` contains:

* `predicted`: The predicted phone.
* `position`: `before` or `after` relative to `word_phone_index`.
* `word_phone_index`: Index within this word’s `ipa`/`phones` the insertion anchors to (or `null`).
* `word_phone_insert_index`: Index where the insertion should be placed inside the word’s `ipa` array.
* `predicted_index`: Index into the utterance‑level `predicted_phones` sequence for this inserted phone.
* `word_phone`: The anchor phone token from the word's IPA (or `null`).
* `timestamp_ms`: `{ start, end }` boundaries for the inserted phone in milliseconds; either value can be `null` when no reliable boundary is available.

```json theme={null}
{
  "word_groups": [
    {
      "index": 4,
      "text": "cities",
      "ipa": ["s", "ɪ", "ɾ", "i", "z"],
      "phones": ["..."],
      "insertions": [
        {
          "predicted": "z",
          "position": "after",
          "word_phone_index": 1,
          "word_phone_insert_index": 2,
          "predicted_index": 15,
          "word_phone": "ɪ",
          "timestamp_ms": {"start": 1860.39, "end": 1920.41}
        }
      ],
      "summary": {
        "avg_match_score_pct": 90.44,
        "total_phones": 5,
        "matches": 3,
        "num_insertions": 1,
        "num_deletions": 0,
        "num_substitutions": 1
      },
      "acceptable_pronunciations": ["s ɪ ɾ i z", "s ɪ t i z"],
      "selected_pronunciation": "s ɪ ɾ i z",
      "selected_pronunciation_index": 0
    }
  ]
}
```

## Phone entries

Each phone entry contains:

* `index`: Zero‑based phone index in the utterance.
* `target`: Expected IPA phone.
* `predicted`: Predicted IPA phone.
* `timestamp_ms`: `{ start, end }` in milliseconds.
* `match_score_pct`: Match score between target and predicted phones.
  In `lenient` mode, near-matches can still receive partial credit.
  In `strict` mode, substitutions score `0` and accepted matches score `100`.
* `grade`: `match`, `substitute`, or `delete`.

For deletions, `predicted` is `null`. `match_score_pct` is nullable, so clients should handle `null` values.

Optional:

* `topk`: The model's top alternative guesses for that phone, with a `confidence_pct` for each option.
* `functional_load`: Priority metadata for substituted phones when the error can affect meaning or involves an important phoneme contrast. See [Functional load](/functional-load).

```json theme={null}
{
  "index": 15,
  "target": "s",
  "predicted": "z",
  "timestamp_ms": {"start": 1860.39, "end": 2060.44},
  "match_score_pct": 90.48,
  "grade": "substitute",
  "topk": [
    {"token": "z", "confidence_pct": 91.5},
    {"token": "s", "confidence_pct": 7.81}
  ]
}
```

### Prosody

Word‑level prosody appears on each `word_groups[i].prosody` (when `enable_prosody_contours=true`):

* `pitch_contour_hz`: Frame‑level pitch contour (Hz) across the word span, sampled every 10 ms. Unvoiced frames are `0`.
* `stress_contour`: Frame‑level stress values (unitless 0–1) sampled every 10 ms. Derived by normalizing log‑energy and relative pitch (semitones vs. the utterance median) and averaging them, so it is best interpreted as **relative emphasis within the word**, not absolute loudness.

```json theme={null}
{
  "prosody": {
    "pitch_contour_hz": [169.08, 168.46, 168.55, 167.49, 165.06, 164.52],
    "stress_contour": [0.49, 0.5, 0.54, 0.52, 0.56, 0.55]
  }
}
```

## Proficiency metrics

Returned when `enable_proficiency_metrics=true`. Evaluates the speech audio holistically.
Set `enable_proficiency_metrics=true` in the analyze request (form field or JSON body) to include this object.

### Pause metrics

* `audio_duration_sec`: Clip duration in seconds.
* `pause_threshold_sec`: Minimum duration required for a silence gap to be counted as a pause.
* `pauses[].start`: Pause start time in seconds.
* `pauses[].end`: Pause end time in seconds.
* `pauses[].duration_sec`: Pause length in seconds.
* `pause_metrics.pause_count`: Number of pauses detected.
* `pause_metrics.average_pause_duration_sec`: Mean pause duration.
* `pause_metrics.total_silence_time_sec`: Sum of all detected pause durations.
* `pause_metrics.pause_ratio`: `total_silence_time_sec / audio_duration_sec`.

```json theme={null}
{
  "audio_duration_sec": 12.0,
  "pause_threshold_sec": 0.25,
  "pauses": [
    {"start": 2.1, "end": 2.6, "duration_sec": 0.5},
    {"start": 5.2, "end": 5.45, "duration_sec": 0.25}
  ],
  "pause_metrics": {
    "pause_count": 2,
    "average_pause_duration_sec": 0.38,
    "total_silence_time_sec": 0.75,
    "pause_ratio": 0.06
  }
}
```

### Speaking rate metrics

* `speech_rate_wpm`: Words per minute including pauses/silence.
* `articulation_rate_wpm`: Words per minute excluding detected pause time.
* `rate_metrics.word_count`: Words used for the rate calculation.
* `rate_metrics.speaking_time_sec`: `audio_duration_sec - total_silence_time_sec`.

```json theme={null}
{
  "speech_rate_wpm": 110.3,
  "articulation_rate_wpm": 132.6,
  "rate_metrics": {
    "word_count": 22,
    "speech_rate_wpm": 110.3,
    "articulation_rate_wpm": 132.6,
    "speaking_time_sec": 9.95
  }
}
```

Each of `fluency`, `prosody`, and `intelligibility` contains:

* `value`: Score out of 100.
* `note`: Short English explanation of the score.

```json theme={null}
{
  "proficiency_metrics": {
    "fluency": {
      "value": 100,
      "note": "The speaker delivers the sentence without any hesitations, fillers, or interruptions."
    },
    "prosody": {
      "value": 95,
      "note": "Natural intonation and rhythm with appropriate emphasis on key words."
    },
    "intelligibility": {
      "value": 100,
      "note": "Every word is pronounced clearly and is easy to understand."
    }
  }
}
```

## Notes

* `pitch_contour_hz` includes values for every frame and is not voiced‑masked.
* Per‑word stress is normalized within each word, so values are relative rather than absolute.

## Example response (abridged)

```json theme={null}
{
  "language": "en",
  "dialect": "en-us",
  "reference_text": "In recent years, many cities have begun redesigning public spaces...",
  "reference_phones": ["ɪ", "n", "r", "iː", "s", "ə", "n", "t", "..."],
  "predicted_phones": ["ɪ", "n", "r", "iː", "s", "ə", "n", "t", "..."],
  "audio": {"duration_sec": 56.83},
  "audio_duration_sec": 56.83,
  "pause_threshold_sec": 0.25,
  "pauses": [{"start": 2.1, "end": 2.6, "duration_sec": 0.5}],
  "pause_metrics": {
    "pause_count": 1,
    "average_pause_duration_sec": 0.5,
    "total_silence_time_sec": 0.5,
    "pause_ratio": 0.01
  },
  "speech_rate_wpm": 138.66,
  "articulation_rate_wpm": 139.9,
  "rate_metrics": {
    "word_count": 131,
    "speech_rate_wpm": 138.66,
    "articulation_rate_wpm": 139.9,
    "speaking_time_sec": 56.33
  },
  "summary": {
    "avg_match_score_pct": 96.37,
    "total_phones": 648,
    "matches": 511,
    "num_insertions": 19,
    "num_deletions": 44,
    "num_substitutions": 100
  },
  "word_groups": [
    {
      "index": 4,
      "text": "cities",
      "ipa": ["s", "ɪ", "ɾ", "i", "z"],
      "summary": {
        "avg_match_score_pct": 90.44,
        "total_phones": 5,
        "matches": 3,
        "num_insertions": 1,
        "num_deletions": 0,
        "num_substitutions": 1
      },
      "prosody": {
        "pitch_contour_hz": [169.08, 168.46, 168.55, 167.49, 165.06, 164.52],
        "stress_contour": [0.49, 0.5, 0.54, 0.52, 0.56, 0.55]
      },
      "phones": [
        {
          "index": 15,
          "target": "s",
          "predicted": "z",
          "timestamp_ms": {"start": 1860.39, "end": 2060.44},
          "match_score_pct": 90.48,
          "grade": "substitute",
          "topk": [
            {"token": "z", "confidence_pct": 91.5},
            {"token": "s", "confidence_pct": 7.81}
          ]
        },
        {
          "index": 16,
          "target": "ɪ",
          "predicted": "ɪ",
          "timestamp_ms": {"start": 2060.44, "end": 2220.47},
          "match_score_pct": 100.0,
          "grade": "match",
          "topk": [
            {"token": "ɪ", "confidence_pct": 90.95},
            {"token": "iː", "confidence_pct": 4.55}
          ]
        },
        {
          "index": 17,
          "target": "ɾ",
          "predicted": "t",
          "timestamp_ms": {"start": 2220.47, "end": 2260.48},
          "match_score_pct": 61.72,
          "grade": "substitute",
          "topk": [
            {"token": "t", "confidence_pct": 54.07},
            {"token": "ɾ", "confidence_pct": 33.33}
          ]
        }
      ],
      "insertions": [
        {
          "predicted": "z",
          "position": "after",
          "word_phone_index": 1,
          "word_phone_insert_index": 2,
          "predicted_index": 15,
          "word_phone": "ɪ"
        }
      ]
    },
    {
      "index": 9,
      "text": "spaces",
      "ipa": ["s", "p", "eɪ", "s", "ᵻ", "z"],
      "summary": {
        "avg_match_score_pct": 96.0,
        "total_phones": 6,
        "matches": 4,
        "num_insertions": 0,
        "num_deletions": 1,
        "num_substitutions": 1
      },
      "phones": [
        {
          "index": 45,
          "target": "eɪ",
          "predicted": null,
          "timestamp_ms": {"start": 4680.99, "end": 4801.01},
          "match_score_pct": null,
          "grade": "delete",
          "topk": [
            {"token": "eɪ", "confidence_pct": 5.22},
            {"token": "ɪ", "confidence_pct": 0.29}
          ]
        }
      ],
      "insertions": []
    }
  ],
  "proficiency_metrics": {
    "fluency": {
      "value": 82,
      "note": "Generally smooth delivery with minor hesitations between phrases."
    },
    "prosody": {
      "value": 78,
      "note": "Intonation is mostly natural but slightly flat on longer phrases."
    },
    "intelligibility": {
      "value": 91,
      "note": "Nearly all words are clearly articulated and easy to understand."
    }
  }
}
```