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

# Pronunciation dictionaries

> Control how your persona pronounces specific words, names, and terms during conversations.

Pronunciation dictionaries let you define custom pronunciation rules so your persona says words exactly how you want. This is useful for brand names, technical terms, acronyms, and foreign words that TTS engines may mispronounce.

Tavus automatically syncs your dictionary to your TTS provider, so rules work regardless of which TTS engine your persona uses.

## How it works

1. You create a pronunciation dictionary with a set of rules
2. Each rule maps a **text** (the word to match) to a **pronunciation** (how it should be spoken)
3. You attach the dictionary to a persona via the `pronunciation_dictionary_id` field in the TTS layer

When you update a dictionary's rules, all personas referencing it are automatically updated. When you delete a dictionary, it is cleanly removed from all linked personas.

## Bring your own TTS API key

If you provide your own TTS API key, you can use Tavus pronunciation dictionaries the same way — just set `pronunciation_dictionary_id` on the TTS layer. Tavus will sync the dictionary rules to your provider account automatically.

## Rule types

Each rule requires a `type` that determines how the pronunciation is interpreted:

| Type    | Description                                             | Example                 |
| ------- | ------------------------------------------------------- | ----------------------- |
| `alias` | Replace the matched text with a different spoken phrase | `"Tavus"` → `"TAH-vus"` |
| `ipa`   | Use IPA (International Phonetic Alphabet) notation      | `"bayou"` → `"ˈbɑju"`   |

### Alias rules

Alias rules perform simple text substitution. The TTS engine speaks the `pronunciation` value instead of the original `text`.

```json theme={null}
{
  "text": "Tavus",
  "pronunciation": "TAH-vus",
  "type": "alias"
}
```

### IPA rules

IPA rules let you specify exact phonetic pronunciation. You can provide IPA in two formats:

* **Raw IPA**: Standard IPA string (e.g., `"hɛloʊ"`)
* **Pipe-delimited IPA**: Pre-tokenized phonemes separated by `|` (e.g., `"ˈ|b|ɑ|j|u"`)

```json theme={null}
{
  "text": "bayou",
  "pronunciation": "ˈ|b|ɑ|j|u",
  "type": "ipa"
}
```

## Rule options

Each rule supports optional matching parameters:

| Parameter         | Type    | Default | Description                        |
| ----------------- | ------- | ------- | ---------------------------------- |
| `case_sensitive`  | boolean | `false` | Whether matching is case-sensitive |
| `word_boundaries` | boolean | `true`  | Whether to match only whole words  |

<Note>
  `word_boundaries` is only applied by ElevenLabs. When syncing to Cartesia, this option is ignored and the rule is applied without word-boundary matching.
</Note>

```json theme={null}
{
  "text": "UN",
  "pronunciation": "United Nations",
  "type": "alias",
  "case_sensitive": false,
  "word_boundaries": false
}
```

## Attaching a dictionary to a persona

Set `pronunciation_dictionary_id` in the TTS layer when creating or updating a persona:

<CodeGroup>
  ```json Create persona theme={null}
  {
    "persona_name": "Sales Agent",
    "system_prompt": "You are a helpful sales agent.",
    "layers": {
      "tts": {
        "tts_engine": "cartesia",
        "pronunciation_dictionary_id": "pd_abc123def456"
      }
    }
  }
  ```

  ```json Patch persona theme={null}
  [
    {
      "op": "add",
      "path": "/layers/tts/pronunciation_dictionary_id",
      "value": "pd_abc123def456"
    }
  ]
  ```
</CodeGroup>

<Note>
  Each persona supports one pronunciation dictionary at a time. Setting a new `pronunciation_dictionary_id` replaces the previous one. Setting it to an empty string removes the dictionary.
</Note>

## Limits

| Limit                          | Value          |
| ------------------------------ | -------------- |
| Text field max length          | 200 characters |
| Pronunciation field max length | 500 characters |
| Dictionary name max length     | 255 characters |

## API reference

* [Create pronunciation dictionary](/api-reference/pronunciation-dictionaries/create-pronunciation-dictionary)
* [Get pronunciation dictionary](/api-reference/pronunciation-dictionaries/get-pronunciation-dictionary)
* [List pronunciation dictionaries](/api-reference/pronunciation-dictionaries/list-pronunciation-dictionaries)
* [Update pronunciation dictionary](/api-reference/pronunciation-dictionaries/update-pronunciation-dictionary)
* [Delete pronunciation dictionary](/api-reference/pronunciation-dictionaries/delete-pronunciation-dictionary)