Pronunciation dictionaries
Overview
Section titled “Overview”Pronunciation dictionaries allow you to customize how your AI agent pronounces specific words or phrases. This is particularly useful for:
- Correcting pronunciation of names, places, or technical terms
- Ensuring consistent pronunciation across conversations
- Customizing regional pronunciation variations
Configuration
Section titled “Configuration”Attach a dictionary to your agent
Section titled “Attach a dictionary to your agent”Update via the dashboard
Section titled “Update via the dashboard”Open your agent in the dashboard, navigate to Voice Settings, and add a pronunciation dictionary. Save your changes.
Update via the CLI
Section titled “Update via the CLI”Pull the agent configuration
Section titled “Pull the agent configuration”elevenlabs agents pull --agent "<agent-name>"Edit `agent_configs/<agent-name>.json`
Section titled “Edit `agent_configs/<agent-name>.json`”Set conversation_config.tts.pronunciation_dictionary_locators:
{
"conversation_config": {
"tts": {
"pronunciation_dictionary_locators": [
{
"pronunciation_dictionary_id": "<dictionary-id>",
"version_id": "<version-id>"
}
]
}
}
}Push your changes
Section titled “Push your changes”elevenlabs agents push --agent "<agent-name>"Update via the API
Section titled “Update via the API”from elevenlabs import ElevenLabs
elevenlabs = ElevenLabs()
elevenlabs.conversational_ai.agents.update(
agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
conversation_config={
"tts": {
"pronunciation_dictionary_locators": [
{
"pronunciation_dictionary_id": "<dictionary-id>",
"version_id": "<version-id>",
}
]
},
},
)import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const elevenlabs = new ElevenLabsClient();
await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
conversationConfig: {
tts: {
pronunciationDictionaryLocators: [
{
pronunciationDictionaryId: "<dictionary-id>",
versionId: "<version-id>",
},
],
},
},
});Dictionary file format
Section titled “Dictionary file format”Pronunciation dictionaries use XML-based .pls files. Here's an example structure:
<?xml version="1.0" encoding="UTF-8"?>
<lexicon version="1.0"
xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2005/01/pronunciation-lexicon
http://www.w3.org/TR/2007/CR-pronunciation-lexicon-20071212/pls.xsd"
alphabet="ipa" xml:lang="en-GB">
<lexeme>
<grapheme>Apple</grapheme>
<phoneme>ˈæpl̩</phoneme>
</lexeme>
<lexeme>
<grapheme>UN</grapheme>
<alias>United Nations</alias>
</lexeme>
</lexicon>Supported formats
Section titled “Supported formats”Pronunciation dictionaries support two types of pronunciation notation:
-
IPA (International Phonetic Alphabet)
- More precise control over pronunciation
- Requires knowledge of IPA symbols
- Example: "nginx" as
/ˈɛndʒɪnˈɛks/
-
CMU (Carnegie Mellon University) Dictionary format
- Simpler ASCII-based format
- More accessible for English pronunciations
- Example: "tomato" as "T AH M EY T OW"
Best practices
Section titled “Best practices”- Case sensitivity: Create separate entries for capitalized and lowercase versions of words if needed
- Testing: Always test pronunciations with your chosen voice and model
- Maintenance: Keep your dictionary organized and documented
- Scope: Focus on words that are frequently mispronounced or critical to your use case
Which models support phoneme-based pronunciation?
Section titled “Which models support phoneme-based pronunciation?”Pronunciation dictionary phoneme tags only work with eleven_v4, eleven_flash_v2 and eleven_v3 models.
Other models skip dictionary phoneme tags and use the default pronunciation. For other models, use alias tags instead to substitute spellings or phrases that produce the pronunciation you need.
If you want to use IPA and CMU pronunciations in languages other than English, you will have to switch to the eleven_v4 or eleven_v3 model.
Can I use multiple dictionaries?
Section titled “Can I use multiple dictionaries?”Yes, you can upload multiple dictionary files to handle different sets of pronunciations.
What happens if a word isn't in the dictionary?
Section titled “What happens if a word isn't in the dictionary?”The model will use its default pronunciation rules for any words not specified in the dictionary.