> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voicy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Pronunciation Guide

> Fix mispronounced words with per-agent pronunciation dictionaries

## Overview

Voice agents may occasionally mispronounce certain words — especially proper nouns, brand names, or Hebrew words with ambiguous pronunciation (Hebrew is written without vowels, so one spelling can be read several ways). The pronunciation dictionary lets you define a per-word override for each agent.

<Note>
  Pronunciation overrides apply to **flow agents** (the chained Speech-to-Text → LLM → Text-to-Speech pipeline). Prompt agents on Gemini Live have no pronunciation surface — the dictionary is hidden in the dashboard when a Gemini Live voice is selected.
</Note>

## Format

The override format is **provider-aware** — it depends on the voice your agent uses. The dashboard always asks for the Hebrew **word**, then a second field whose format matches the voice provider:

| Voice provider | Override format                       | Example (שקל) | Direction |
| -------------- | ------------------------------------- | ------------- | --------- |
| **Soniox**     | Niqqud-pointed Hebrew                 | `שֶׁקֶל`      | RTL       |
| **DeepDub**    | IPA (International Phonetic Alphabet) | `ˈʃekel`      | LTR       |

Each entry stores both formats independently, so switching an agent's voice between Soniox and DeepDub never reinterprets a niqqud string as IPA (or vice-versa) — the non-matching field is simply ignored.

## How to Use

1. Go to your agent's settings in the [dashboard](https://app.voicy.co)
2. Open the **Pronunciation** accordion section (the title shows the active format — "Pronunciation (Niqqud)" or "Pronunciation (IPA)")
3. Click **Add** to create a new entry
4. Enter the Hebrew word, then its override in the format shown for your voice (niqqud for Soniox, IPA for DeepDub)
5. Save — the pronunciation takes effect on the next call

## Tips

* **Only add mispronounced words** — most Hebrew words are pronounced correctly by default
* **Keep the list short** — focus on the words that matter most
* **Test after adding** — make a test call to verify the pronunciation improved
* **Iterate** — if the first override doesn't sound right, try a different one
* **Include meaning for homographs** — if a word has multiple readings (like שקל), add separate entries with context in the word field (e.g., "שקל מטבע" and "שקל פועל")

## Generating Overrides

If you're unsure how to write the override:

* **Soniox (niqqud)** — [nakdan.dicta.org.il](https://nakdan.dicta.org.il/) adds vowel points to plain Hebrew text.
* **DeepDub (IPA)** — [phonikud-tts](https://huggingface.co/spaces/thewh1teagle/phonikud-tts) converts Hebrew text to IPA.

The dashboard links to the matching tool directly under the override field.

## How It Works

For a flow agent, the word is rewritten before the text reaches the Text-to-Speech engine:

* **Soniox voices** — the word is replaced with its niqqud-pointed form, which Soniox renders faithfully.
* **DeepDub voices** — the word is wrapped in an inline SSML `<phoneme>` tag carrying the IPA, which DeepDub honors.

Because this is a deterministic text substitution (not a hint to a model), an override applies on every utterance where the word appears.

## Limitations

* Works best for **proper nouns, brand names, and uncommon words**
* Common Hebrew words are usually pronounced correctly without overrides
* An override only applies when the word appears exactly as written in the **word** field
* Maximum 50 entries per agent