Pronunciation dictionaries let you define custom pronunciation rules so your PAL 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 PAL uses.
How it works
- You create a pronunciation dictionary with a set of rules
- Each rule maps a text (the word to match) to a pronunciation (how it should be spoken)
- You attach the dictionary to a PAL via the
pronunciation_dictionary_id field in the TTS layer
When you update a dictionary’s rules, all PALs referencing it are automatically updated. When you delete a dictionary, it is cleanly removed from all linked PALs.
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.
{
"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")
{
"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 |
word_boundaries is only applied by ElevenLabs. When syncing to Cartesia, this option is ignored and the rule is applied without word-boundary matching.
{
"text": "UN",
"pronunciation": "United Nations",
"type": "alias",
"case_sensitive": false,
"word_boundaries": false
}
Attaching a dictionary to a PAL
Set pronunciation_dictionary_id in the TTS layer when creating or updating a PAL:
{
"pal_name": "Sales Agent",
"system_prompt": "You are a helpful sales agent.",
"layers": {
"tts": {
"tts_engine": "cartesia",
"pronunciation_dictionary_id": "pd_abc123def456"
}
}
}
Each PAL 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.
Limits
| Limit | Value |
|---|
| Text field max length | 200 characters |
| Pronunciation field max length | 500 characters |
| Dictionary name max length | 255 characters |
API reference
