Pronunciation dictionaries

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"
    }
  }
}

[
  {
    "op": "add",
    "path": "/layers/tts/pronunciation_dictionary_id",
    "value": "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

Getting started

Build

Deploy

Debug

Guides

Resources

Pronunciation dictionaries

How it works

Bring your own TTS API key

Rule types

Alias rules

IPA rules

Rule options

Attaching a dictionary to a PAL

Limits

API reference

​How it works

​Bring your own TTS API key

​Rule types

​Alias rules

​IPA rules

​Rule options

​Attaching a dictionary to a PAL

​Limits

​API reference

How it works

Bring your own TTS API key

Rule types

Alias rules

IPA rules

Rule options

Attaching a dictionary to a PAL

Limits

API reference