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

# Functional load

> Prioritize pronunciation errors that can change word meaning

Functional load helps your app decide which phoneme errors matter most. It is
returned as optional metadata on substituted phones in `/v1/speech/analyze`.

## When it appears

`functional_load` appears only on phone objects where:

```json theme={null}
{
  "grade": "substitute"
}
```

It does not appear on matched phones, insertions, deletions, or languages where
functional load is not available.

If the field is absent, use the normal `grade`, `match_score_pct`, and word-level
scores.

## Example

For English, confusing the vowel in `ship` so it sounds like `sheep` can change
the word meaning.

```json theme={null}
{
  "text": "ship",
  "phones": [
    {
      "index": 1,
      "target": "ɪ",
      "predicted": "iː",
      "grade": "substitute",
      "functional_load": {
        "meaning_risk": true,
        "priority_score": 82,
        "priority_category": "critical",
        "meaning_risk_score": 82,
        "meaning_risk_category": "critical",
        "contrast_category": "critical",
        "examples": ["ship/sheep"]
      }
    }
  ]
}
```

## Fields

| Field                   | Type      | Meaning                                                                                 |
| ----------------------- | --------- | --------------------------------------------------------------------------------------- |
| `meaning_risk`          | boolean   | `true` when this substitution can make the target word collide with another known word. |
| `priority_score`        | integer   | Main correction-priority score from `0` to `100`. Use this for ranking.                 |
| `priority_category`     | string    | Human-readable category for `priority_score`.                                           |
| `meaning_risk_score`    | integer   | Word-specific collision strength from `0` to `100`.                                     |
| `meaning_risk_category` | string    | Human-readable category for `meaning_risk_score`.                                       |
| `contrast_category`     | string    | How important this phone contrast is across the language dictionary.                    |
| `examples`              | string\[] | Minimal-pair examples that explain the risk.                                            |

Categories are:

```text theme={null}
none
low
medium
high
critical
```

## How to use it

For most products:

1. Prioritize corrections where `priority_category` is `high` or `critical`.
2. If `meaning_risk` is `true`, explain that the pronunciation can sound like a
   different word.
3. Use `examples[0]` as the clearest minimal-pair explanation when available.
4. Use `priority_score` for sorting. Avoid showing raw functional-load scores to
   learners unless your product is explicitly score-oriented.

Example:

```ts theme={null}
const fl = phone.functional_load;

if (fl?.meaning_risk && ["high", "critical"].includes(fl.priority_category)) {
  // Prioritize this correction in tutor feedback.
  // Example: "This can sound like 'sheep' instead of 'ship'."
}
```

## Accuracy vs functional load

Functional load is not a replacement for pronunciation accuracy.

Accuracy answers:

```text theme={null}
How close was the learner's production to the target?
```

Functional load answers:

```text theme={null}
How much does this specific phoneme substitution matter linguistically?
```

Use normal word and phone scores to judge recognizability. Use
`functional_load` to decide which phoneme errors are most important to correct.

## Supported languages

Functional load is currently available for these base language codes:

```text theme={null}
ar, bn, ca, cs, da, de, el, en, es, fa, fi, fr, he, hi, hr, hu,
it, ja, ko, lt, no, nl, pl, pt, ro, ru, sk, sv, ta, tr, uk, vi, zh
```

Currently missing:

```text theme={null}
sw, te, th
```