> ## Documentation Index > Fetch the complete documentation index at: https://docs.zeptar.com/llms.txt > Use this file to discover all available pages before exploring further. # Pronunciation dictionaries > Control how an agent pronounces brand names, acronyms, and technical terms across every supported TTS provider. A **pronunciation dictionary** is a lexicon of rules attached to one or more agents. At synthesis time, the runtime applies its rules so a word the model would otherwise say wrong — your product name, a domain term, a tricky loanword — comes out the way you want. Use one when the default TTS output is repeatedly wrong on a specific word; reach for a knowledge-base entry or a system-prompt tweak instead when the issue is *what* the agent says rather than *how* it says it. ## Rule types Each rule is either an **alias** or a **phoneme** rule. * **Alias** — the replacement is verbatim spoken text. `"UN"` → `"United Nations"`, `"v2"` → `"version two"`. Works on every TTS provider because the substitution happens before the text ever reaches the model. * **Phoneme** — the replacement is a phonetic string in the **IPA** or **CMU** alphabet (set per rule). For digraphs like `dʒ`, `aɪ`, or `kʰ`, prefer whitespace-delimited input — it converts more reliably than tightly-packed Unicode. ## Provider behaviour matrix How a phoneme rule actually reaches your listener depends on the agent's TTS provider. This is the most operationally important table on the page. | Provider / model | Alias rules | Phoneme rules | How it works | | ----------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Cartesia** (Sonic 3 / 3.5, via the LiveKit Cartesia plugin) | Applied | **IPA only** | Zeptar uploads the dictionary version to Cartesia's hosted **Pronunciation Dictionary API**, caches the returned `cartesia_dict_id`, and the runtime passes it to `cartesia_plugin.TTS(pronunciation_dict_id=…)`. Cartesia applies the rules server-side. IPA strings are converted to Cartesia's pipe format (`<>`) automatically. **CMU phonemes are forwarded verbatim** — Cartesia doesn't speak CMU natively, so those entries fall back to the default pronunciation. Author phoneme rules in IPA when you need them on Cartesia. | | **ElevenLabs Flash v2** (`eleven_flash_v2`) | Applied | Applied | Aliases via in-runtime text substitution; phonemes via inline `grapheme` SSML tags. | | **AWS Polly Neural** | Applied | Applied | Aliases via substitution; phonemes via inline SSML. | | **Everything else** — `eleven_flash_v2_5`, `eleven_turbo_v2_5`, `openai/*`, and the LiveKit Inference Cartesia fallback | Applied | **Passthrough only** | Alias rules apply via in-runtime substitution. Phoneme rules pass through with no audible effect. `eleven_flash_v2_5` and `eleven_turbo_v2_5` silently drop SSML `` tags; OpenAI's TTS doesn't support SSML at all. | If a phoneme rule is critical, route the agent through Cartesia, ElevenLabs Flash v2, or Polly. If you don't control the model, lean on alias rules — they apply everywhere. ## Lifecycle Versions are **immutable**. Every rule edit (add, remove, set) creates a new version row; the old version is preserved. On every version-creating mutation the API fires a **Cartesia sync**: it uploads the new version to Cartesia and caches the returned `pronunciation_dict_id` on that version row. Subsequent reads of the same version reuse the cached ID — Cartesia is never re-asked for it. ## Limits **V1 single-attach to Cartesia.** When more than one dictionary is attached to an agent, the runtime currently passes only the **first** locator's `pronunciation_dict_id` to the Cartesia plugin and logs `cartesia.multi_dict_attach` for the rest. Multi-dictionary support will follow when the LiveKit Cartesia plugin signature widens to accept a list. ## Operator workflow 1. Dashboard → **Pronunciation dictionaries** → **New**. 2. Add rules (alias, or phoneme with IPA / CMU). 3. **Save**. The API syncs to Cartesia in the background. Look for `cartesia.uploadVersion synced … cartesia_dict_id=…` in the API logs. 4. Attach the dictionary to an agent: **Agent → Voice → Pronunciation dictionaries**. 5. Start a call. The runtime logs `tts.using_cartesia_plugin cartesia_dict_id_count=1` when it picks up the cached ID, and the rules apply during synthesis. ## Troubleshooting **`cartesia.uploadVersion` doesn't appear in the API logs after saving rules.** `CARTESIA_API_KEY` is most likely unset on the API. The sync service skips silently and emits `cartesia.uploadVersion CARTESIA_API_KEY unset, skipping`. Set the key, restart the API, then re-save the dictionary to force a fresh sync. **The runtime logged `tts.using_cartesia_plugin cartesia_dict_id_count=1` but the rule didn't fire on the call.** Confirm the version's rules are what you expect: `GET /v1/pronunciation-dictionaries/:id/versions/:versionId`. If a phoneme rule is the suspect, retype the IPA with whitespace between codepoints — digraphs like `dʒ` and `aɪ` survive the Cartesia pipe conversion more reliably when delimited. **`Invalid origin` on sign-in across dev ports.** This isn't a dictionary problem but it shows up while you're iterating. `BETTER_AUTH_URL` on the API and the browser's Origin must match. Set the API's `BETTER_AUTH_URL` to the API's own URL and the web app's `NEXT_PUBLIC_APP_URL` to the web URL.