Functional load

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:

{
  "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.

{
  "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:

none
low
medium
high
critical

How to use it

For most products:

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

Example:

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:

How close was the learner's production to the target?

Functional load answers:

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:

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:

sw, te, th

Getting started

Reference

Preview

When it appears

Example

Fields

How to use it

Accuracy vs functional load

Supported languages

​When it appears

​Example

​Fields

​How to use it

​Accuracy vs functional load

​Supported languages

When it appears

Example

Fields

How to use it

Accuracy vs functional load

Supported languages