Skip to main content
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 both Cartesia and ElevenLabs, 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
  4. Tavus resolves the correct provider-specific dictionary at save time, so conversations have zero extra latency
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.

​
Rule types

Each rule requires a type that determines how the pronunciation is interpreted:
TypeDescriptionExample
aliasReplace the matched text with a different spoken phrase"Tavus" → "TAH-vus"
ipaUse 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:
ParameterTypeDefaultDescription
case_sensitivebooleanfalseWhether matching is case-sensitive
word_boundariesbooleantrueWhether to match only whole words
{
  "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: 
{
  "persona_name": "Sales Agent",
  "system_prompt": "You are a helpful sales agent.",
  "layers": {
    "tts": {
      "tts_engine": "cartesia",
      "pronunciation_dictionary_id": "pd_abc123def456"
    }
  }
}
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.

​
Limits

LimitValue
Text field max length200 characters
Pronunciation field max length500 characters
Dictionary name max length255 characters

​
API reference