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

# Custom spelling

> Normalize spelling variants to your preferred forms

<Badge color="blue" size="lg" icon="file-audio">
  Pre-recorded
</Badge>

<Badge color="green" icon="tower-broadcast" size="lg">
  Live
</Badge>

As Speech-to-text models are trained on general vocabulary, under-represented words such as brand names, proper nouns, or domain-specific terms are often transcribed incorrectly.

Custom Spelling is a post-processing operation that applies literal matching between the correct word and the pronunciations entries. When there is a literal match, the transcribed text is replaced with your term.

<Note>
  If the word comes out garbled or replaced by something phonetically similar (e.g.
  **"le vin"** instead of **"Levain"**), use **[Custom
  vocabulary](/chapters/audio-intelligence/custom-vocabulary)** instead. Custom
  vocabulary matches on phonemes, not literal text.
</Note>

## How it works

Gladia runs custom spelling on the **transcript text** after transcription:

1. Gladia scans the output for strings listed in your dictionary **values**.
2. When a variant is found, it is replaced with the corresponding **key**.
3. Each entry supplies:
   * **Key** — the spelling to write (case-sensitive).
   * **Values** — variant strings to find (case-insensitive; can be multiple words).

Custom spelling is **precise but strict**: Gladia replaces only strings listed in your dictionary and leaves everything else unchanged.

### Example: name "Gorish"

If the model outputs **"gaurish"** or **"ghorish"**, Gladia replaces them with **"Gorish"** when they appear in your dictionary:

```json theme={"system"}
"Gorish": ["ghorish", "gaurish", "gaureish", "geurish", "go rich"]
```

Custom spelling is not based on phoneme-matching but **literal matching** so make sure to list every spelling carefully as missing variants are never inferred.

## When to use custom vocabulary vs. custom spelling

Use **[Custom spelling](/chapters/audio-intelligence/custom-spelling)** when the model outputs a recognizable but wrong form. It applies **literal string matching** on variants you list (e.g. **"data-science"** → **"Data Science"**). **List every close variant** the model might output.

Use **[Custom vocabulary](/chapters/audio-intelligence/custom-vocabulary)** when the model outputs garbled or sound-alike text. It applies **phoneme-based matching** on entries you define (e.g. **"le vin"** / **"levine"** → **"Levain"**). **Add pronunciations** for each spelling the model might produce.

|                 | Custom spelling                              | Custom vocabulary                       |
| --------------- | -------------------------------------------- | --------------------------------------- |
| **Matches on**  | Exact text in the transcript                 | How words sound                         |
| **Best for**    | Wrong spelling, punctuation, formatting      | Phonetically similar mis-transcriptions |
| **You provide** | All the words that the model outputs wrongly | `value`, `pronunciations`, `intensity`  |

**Rule of thumb:** start with a transcription run *without* any custom vocabulary. Look at what the output actually says. If the word appears but is just misspelled, custom spelling is the simpler and safer fix. If the word is completely garbled, that's when custom vocabulary is the right tool.

## Example configuration

<CodeGroup>
  ```json Pre-recorded theme={"system"}
  {
    "custom_spelling": true,
    "custom_spelling_config": {
      "spelling_dictionary": {
        "Gorish": ["ghorish", "gaurish", "gaureish", "geurish", "go rich"],
        "Data Science": ["data-science", "data science"],
        ".": ["period", "full stop"],
        "SQL": ["sequel"]
      }
    }
  }
  ```

  ```json Live theme={"system"}
  {
    "realtime_processing": {
      "custom_spelling": true,
      "custom_spelling_config": {
        "spelling_dictionary": {
          "Gorish": ["ghorish", "gaurish", "gaureish", "geurish", "go rich"],
          "Data Science": ["data-science", "data science"],
          ".": ["period", "full stop"],
          "SQL": ["sequel"]
        }
      }
    }
  }
  ```
</CodeGroup>

## Parameter reference

<ParamField body="spelling_dictionary" type="object">
  <Expandable title="properties">
    Map of preferred spellings (**keys**) to variant strings the model might output (**values**).

    <ParamField body="key" type="string" required>
      The correct word to transcribe. This parameter is **case-sensitive** so `"Gorish"` and `"gorish"` are different keys.
    </ParamField>

    <ParamField body="values" type="string[]" required>
      Variant strings to search for in the transcript. Those strings are **case-insensitive.** and can be multiple words (e.g. `"full stop"`).
    </ParamField>
  </Expandable>
</ParamField>

## Tuning tips

* **Collect variants from real transcripts** — run without custom spelling first, then add keys and values from what the model actually outputs.
* **Match key capitalization** to how the word should appear in the final transcript.
* **List phonetically different strings separately** — custom spelling will not group them the way custom vocabulary does.
* **Move garbled or sound-alike output to [custom vocabulary](/chapters/audio-intelligence/custom-vocabulary)** when listing every variant becomes impractical.

## Recommended workflow

1. **Transcribe without custom spelling** and note misspelled terms.
2. **Route each term:** recognizable but wrong spelling → custom spelling; garbled or phonetically wrong → custom vocabulary.
3. **Build the dictionary** — correct form as the key, every variant you have seen as values.
4. **Transcribe again** — confirm replacements and check that nothing else was changed unexpectedly.
5. **Refine:** add new variants as they appear in production audio.