ElevenLabs Pronunciation Dictionary: Setup Guide (2026)

An ElevenLabs pronunciation dictionary is a set of custom rules that tell the voice exactly how to say specific words, names, and terms. You write them in .pls format and upload them to ElevenLabs, where they apply to text-to-speech in Studio, voice agents, and the API. Dictionaries support IPA and CMU phoneme tags plus alias-style substitutions. Setup takes about 10 minutes and costs nothing beyond your plan’s credits.

What a pronunciation dictionary does

Every text-to-speech voice guesses how to read unusual words from spelling patterns. Most of the time it guesses right — but with uncommon names, place names, acronyms, and technical terms it can guess wrong in a way that sounds broken to anyone who knows the word. A pronunciation dictionary is a lookup table that overrides those guesses: whenever the text contains a word from your list, the voice uses your specified pronunciation instead of its default reading.

ElevenLabs implements dictionaries with the .pls (Pronunciation Lexicon Specification) format, a standard that maps written words to spoken pronunciations. You can define pronunciations with IPA or CMU phoneme tags for exact control, or use alias-style substitutions — telling the voice to say a word “as” another spelling — when phoneme control is not available. The official docs page (elevenlabs.io/docs/eleven-agents/customization/voice/pronunciation-dictionary) lists exactly which entry types work where.

How to set up a pronunciation dictionary

The basic flow: identify the mispronounced words, write their correct pronunciations in a .pls file, upload it to ElevenLabs, and attach it where you generate speech. Here is the full process in four steps.

Step 1 — Collect the words that sound wrong (0 credits)

Generate a test clip of your script and listen for mispronounced names, brands, places, and technical terms. Write each one down with its correct spoken form. Most scripts need only 5–15 dictionary entries — one-off words you can fix by respelling do not need dictionary rules. Focus on words that appear repeatedly across many generations, because the dictionary pays off through reuse. Our TTS tips guide covers respelling tricks for one-off fixes.

Step 2 — Write the .pls file (0 credits)

Create a file with the .pls extension containing one lexeme entry per word: the written word plus its pronunciation. For exact control, use IPA or CMU phoneme tags — for example, specifying that an uncommon surname should be read with a particular vowel. Where phoneme tags are not supported, use alias-style substitutions that tell the voice to read the word “as” a differently spelled string. Keep entries narrow: one pronunciation per word, no duplicate entries for the same spelling.

Step 3 — Upload the dictionary to ElevenLabs (0 credits)

Upload the .pls file in the ElevenLabs dashboard. In Studio, you create a pronunciation dictionary for the project; for voice agents, dictionaries attach to the agent’s voice configuration; via the API you pass the dictionary on the relevant text-to-speech calls. Uploads and dictionary management cost 0 credits — you only pay credits for the audio you generate, at the normal rate of 1 credit per character. Our credits guide explains the math.

Step 4 — Test and refine (a few credits)

Regenerate the sentences that contained the mispronounced words and confirm each one now sounds right. Fixing one word sometimes changes how neighboring words sound, so test full sentences rather than isolated words. A 100-word test script costs about 600 credits at 1 credit per character — cheap enough to iterate. If a rule misbehaves, check the docs entry types: some phoneme formats only work in certain products, and the alias fallback covers the rest.

Phoneme tags vs alias substitutions

IPA and CMU phoneme tags give you exact control: you specify the sound of each syllable, so the voice cannot misinterpret your intent. This is the right choice for brand names and technical terms where the correct pronunciation is non-obvious. Alias-style substitutions are simpler: you tell the voice to read “X” as if it were spelled “Y”. They work when phoneme control is unavailable and are easier to write, but they inherit the voice’s default reading of the alias spelling — which can surprise you with compound words. Use phoneme tags for precision, aliases for speed.

Where dictionaries work

Pronunciation dictionaries apply across ElevenLabs products: Studio projects, conversational AI voice agents, the text-to-speech API, and most TTS streaming models. This matters because pronunciation problems are not confined to one workflow — a brand name mispronounced in a Studio narration will also be mispronounced when your API-driven app reads it aloud, unless the dictionary travels with the voice. Attach the dictionary at the voice or project level rather than per-generation, so every output benefits automatically.

Troubleshooting: dictionary not working

The most common cause is a mismatch between the entry type and the product: phoneme tags that work in Studio may not be honored by every agent or API model. Check the docs page for which entry types each product supports and switch to alias substitutions if needed. Second, confirm the dictionary is actually attached — uploading a file without attaching it to the voice or project changes nothing. Third, watch for spelling differences: dictionaries match the written text exactly, so a plural or possessive form the dictionary does not cover falls back to the default reading. Add variants explicitly.

Dictionary best practices

Keep dictionaries small and purposeful. Every rule is a maintenance obligation: if a brand renames itself or you stop using a term, a stale rule can mispronounce words that would otherwise sound fine. Name the dictionary after the project or client so you can find it months later. Version your .pls files — save a copy each time you edit, because a bad edit that breaks twenty pronunciations is easier to roll back than to debug. Finally, never use a dictionary to paper over a script problem: if a sentence only makes sense with a pronunciation hack, rewriting the sentence is usually the better fix.

Who should NOT use a pronunciation dictionary

Skip the dictionary if your scripts use everyday vocabulary — the default pronunciations handle common words well, and a dictionary adds maintenance for no benefit. Skip it for one-off projects with a handful of odd words: respelling them phonetically inline is faster. And skip it if your text changes constantly — a dictionary built for this week’s script may fight next week’s content. Dictionaries pay off for recurring content: series, client work, and apps that read the same vocabulary every day.

Frequently asked questions

What is an ElevenLabs pronunciation dictionary?

It is a set of custom rules, written in .pls format, that tell ElevenLabs voices exactly how to pronounce specific words, names, and terms. The rules override the voice’s default reading of those words in Studio, voice agents, and the API.

How do I create a pronunciation dictionary?

Write a .pls file with one entry per word — the written word plus its pronunciation as IPA or CMU phoneme tags, or an alias substitution. Upload it in the ElevenLabs dashboard and attach it to your Studio project, agent, or API voice, then test with a short generation.

Do pronunciation dictionaries cost extra credits?

No. Creating, uploading, and attaching dictionaries is free — you pay credits only for the audio you generate, at the normal rate of 1 credit per character (checked 5 Nov 2026). Test generations cost a few hundred credits.

Can I use IPA phonemes in ElevenLabs dictionaries?

Yes — ElevenLabs dictionaries support IPA and CMU phoneme tags for exact pronunciation control. If a particular product does not honor phoneme tags, alias-style substitutions are the supported fallback.

Why is my dictionary not changing the pronunciation?

Usually one of three things: the entry type is not supported in that product (check the docs), the dictionary is uploaded but not attached to the voice or project, or the text differs from the dictionary entry (plurals and possessives need their own entries).

Do dictionaries work with the ElevenLabs API?

Yes. Dictionaries apply to API text-to-speech calls and most TTS streaming models, not just Studio and voice agents. Attach the dictionary at the voice level so every API generation uses it automatically.

Should I use phoneme tags or alias substitutions?

Use phoneme tags when you need exact control — brand names and technical terms with non-obvious pronunciations. Use alias substitutions for speed and in products that do not support phoneme tags. Both are documented on the official pronunciation dictionary docs page.

Sources checked

We verified the facts above on the official ElevenLabs pages on 5 Nov 2026: elevenlabs.io/docs/eleven-agents/customization/voice/pronunciation-dictionary (dictionary format, IPA/CMU tags, alias substitutions, Studio/Agents/API support) and elevenlabs.io/pricing (1 credit per character; plan credit allowances).