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

# Fix pronunciation with dictionaries in Hamsa Media

> Create a pronunciation dictionary of words and corrections, test each one on a voice, import or export it as a file, and use it in text to speech and more.

A pronunciation dictionary tells a voice how to say specific words. You list a word as it appears in your text (the source) and how it should be said (the correction), and the voice says the correction instead. Use it for brand names, people's names, places and Arabic words a voice gets wrong.

Dictionaries belong to the project. The same dictionaries are used in Hamsa Media and in [Hamsa Agents](https://docs.tryhamsa.com/agents/voices/dictionaries.md), so a dictionary you make here can be turned on for an agent too.

## Before you start

Owners and admins create, save and delete dictionaries by default. Members can open and test them. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).

## Write a good correction

"Write the correction the way the voice should say the word." Two common Arabic cases:

| Problem | Correction | Example |
| - | - | - |
| An Arabic word is pronounced wrong | Spell it phonetically, with harakat | علم → عِلْم |
| A foreign word is spelled in Arabic | Use its original spelling | جوجل → Google |

Keep corrections short, and test each one on the voice you will use: "a correction isn't guaranteed to sound right on every voice", and "Corrections don't always carry over between voices." Test again after you switch voices.

## Create a dictionary

**1. Open Dictionaries**

In **Voices library**, switch the section to **Dictionaries**. The list shows each dictionary's **Name**, **Entries** and **Updated at**, with **Search dictionaries...** above it.

![The Dictionaries section: Newsroom names, Brand names and Pharmacy products with their entry counts and update dates, search and Create](https://mintcdn.com/hamsa-452fa79a/etUfiFCo8p_6XpY_/images/media/voices/dictionaries-list-light.webp?fit=max\&auto=format\&n=etUfiFCo8p_6XpY_\&q=85\&s=7c6d8a94089cf07df41f7b0ba220b8f0)

**2. Create it**

Click **Create**, enter a **Dictionary name** (up to 100 characters), and click **Create**. The new dictionary opens.

![The Create Dictionary dialog with a dictionary name typed in](https://mintcdn.com/hamsa-452fa79a/etUfiFCo8p_6XpY_/images/media/voices/dictionary-create-light.webp?fit=max\&auto=format\&n=etUfiFCo8p_6XpY_\&q=85\&s=9c8868df8000210377b1020e6d3d0188)

**3. Select a voice**

Click **Select voice** and pick the voice to test with, usually the one you will generate with. A voice is required to save. It is only used for previews: it doesn't change which voice speaks your scripts.

![The voice picker opened from a dictionary, the same library with Select on each voice](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/voices/dictionary-select-voice-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=27f8fdef1032bb781265b62d2b85eefb)

**4. Add entries**

Click **Add entry**. Under **Source**, type the word as it appears in your text. Under **Correction**, type how it should be said. A source can be a phrase of several words.

![A dictionary open: the tips on getting good results, the status filters, the selected voice with Import, Export and Save, and the Source and Correction rows](https://mintcdn.com/hamsa-452fa79a/etUfiFCo8p_6XpY_/images/media/voices/dictionary-editor-light.webp?fit=max\&auto=format\&n=etUfiFCo8p_6XpY_\&q=85\&s=d7279c0b3ea30f48087220debce7bc5b)

**5. Test each entry**

Click **Preview pronunciation on the selected voice** on the row, then mark it **Sounds right** or **Doesn't sound right**. To hear the word in context, use **Preview with your own sentence**, type a sentence under **Text to test** and click **Test**.

![Preview in your own sentence, with a sentence under Text to test and the Test button](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/voices/dictionary-test-sentence-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=90129e8570ead3630c36a6561ce3ab0b)

**6. Save**

While you have unsaved changes, a bar at the bottom counts them. Click **Save** in the bar, or press Cmd+S (Ctrl+S on Windows). "Dictionary saved successfully". **Discard** drops the changes. If two rows have the same word, **Save** stays off: "Repeated words. Keep one row per word to save."

![Four entries tested on Fayez: one marked Sounds right, one Doesn't sound right with a hint to try another spelling, two Untested, and the filter counts above](https://mintcdn.com/hamsa-452fa79a/etUfiFCo8p_6XpY_/images/media/voices/dictionary-entries-tested-light.webp?fit=max\&auto=format\&n=etUfiFCo8p_6XpY_\&q=85\&s=876963b37897f42a021ee3525438d9ae)

Saving is blocked, and the app says why, while:

* no voice is selected ("Please select a voice before saving"),
* two rows have the same source word, whatever the letter case ("Keep only one row per word."), or
* a row has a source without a correction, or a correction without a source.

Empty rows are dropped when you save.

### Track what you tested

Each entry has a status for the selected voice: **Untested**, **Attempted** (previewed but not marked), **Passed** (**Sounds right**) or **Failed** (**Doesn't sound right**). Filter by status to see what is left to check, or search the entries.

The marks are notes for you: "They don't change which words or corrections are used. Every entry you save is applied." Changing an entry's correction resets its mark. Marks are saved with **Save**.

If a correction doesn't sound right: "Try a different phonetic spelling (harakat), or use the word's original spelling, then preview again."

## Import entries from a file

**1. Open Import**

In the dictionary, click **Import**. The **Import dictionary** dialog opens.

**2. Get the template (optional)**

If you don't have a file yet, click **Download Excel template** or **Download CSV template**. The template has a `source` column and a `correction` column, with two example rows. Fill it in with one word or phrase per row and keep the header row. A file of your own works too, as long as it has those two columns.

![The Import dictionary dialog with Download Excel template, Download CSV template and the drop area](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/voices/dictionary-import-templates-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=ef545e649393819e183421b3bfbb7ba7)

**3. Upload it**

Drop the file in the dialog or click to choose it. It takes an Excel (.xlsx) or CSV file with `source` and `correction` columns. The dialog reads it and shows what will happen.

**4. Import and save**

Click **Import \{n} entries**. The entries are added to the editor. Click **Save** to keep them.

![Import dictionary after reading a CSV: 5 entries ready to import, 1 will update existing words, 1 duplicate source, and 2 rows that won't be imported, with Import 5 entries](https://mintcdn.com/hamsa-452fa79a/etUfiFCo8p_6XpY_/images/media/voices/dictionary-import-light.webp?fit=max\&auto=format\&n=etUfiFCo8p_6XpY_\&q=85\&s=3c521ab56aa07a4651589e9f0f4ca0f5)

### What is imported, updated or skipped

| In the file | What happens |
| - | - |
| A new source word | Added ("entries ready to import") |
| A source already in the dictionary | Its correction is replaced ("will update existing words"). Letter case is ignored when comparing. |
| The same source twice in the file | The last row wins ("duplicate sources (last value kept)") |
| An empty row, or a row missing the source or the correction | Skipped, listed by row number ("rows won't be imported") |
| Empty rows at the end of the sheet | Ignored |

File rules:

* Only .xlsx and .csv files. Older .xls files aren't read.
* In Excel, only the first sheet is read.
* The first row that isn't empty is the header. It must have a `source` column (or `word`) and a `correction` column (or `replacement`), in any letter case. Other columns are ignored.
* If the header doesn't match: "This file doesn't match the template, so nothing can be imported." The dialog lists the columns it found.

## Export a dictionary

Click **Export** > **Export as Excel (.xlsx)** or **Export as CSV**. The file is named after the dictionary and has the same `source` and `correction` columns as the template, so you can edit it and import it again. Rows missing a source or a correction aren't exported.

![The Export menu: Export as Excel (.xlsx) and Export as CSV](https://mintcdn.com/hamsa-452fa79a/etUfiFCo8p_6XpY_/images/media/voices/dictionary-export-light.webp?fit=max\&auto=format\&n=etUfiFCo8p_6XpY_\&q=85\&s=c7f6aea88d4706c289615ff9f9b6e00d)

## Where dictionaries apply

| Where | How |
| - | - |
| [Text to speech](https://docs.tryhamsa.com/media/text-to-speech/generate-speech.md) | Turn dictionaries on for a script in the voice settings, under **Dictionaries**. Words they will change are highlighted in the script. **Add pronunciation** on a word saves an entry to a dictionary. |
| [Project defaults](https://docs.tryhamsa.com/media/workspace/project-defaults.md) | Set the dictionaries text to speech starts with in this project |
| [Transcript editor](https://docs.tryhamsa.com/media/speech-to-text/transcript-editor.md) | **Add pronunciation** from a transcript segment saves an entry to a dictionary |
| [Web reader](https://docs.tryhamsa.com/media/web-reader/set-up-a-site.md) (beta) | A site's settings take dictionaries for its readings |
| [Hamsa Agents](https://docs.tryhamsa.com/agents/voices/dictionaries.md) | Turn dictionaries on per agent |

Voice overs don't use dictionaries.

## How a dictionary changes the audio

* Right before the speech is made, each source word or phrase in your script is replaced by its correction. Your saved script keeps the words you wrote; only the audio changes.
* Only whole words and phrases are replaced. An entry for "AI" doesn't change "AIR", and an entry for جوجل doesn't change وجوجل. Add attached forms as their own entries.
* Arabic harakat are ignored when matching: an entry for علم also changes عِلْم in your script. If an entry with the exact harakat exists, it is used first.
* Letter case must match. Add each spelling your text uses, for example both "Hamsa" and "HAMSA".
* When entries overlap, the longest one is used. An entry for "Hamsa Media" wins over one for "Hamsa" in that phrase. A correction is never changed again by another entry.
* If two dictionaries you turned on have the same source word, only one of the corrections is used. Keep each word in one dictionary.

Hamsa Agents matches the same way. See [Dictionaries in Hamsa Agents](https://docs.tryhamsa.com/agents/voices/dictionaries.md).

Edits to a dictionary apply to the next audio you generate. Audio you already made doesn't change.

## Delete a dictionary

In the list, open the row's menu and click **Delete**, then confirm. The dictionary leaves the list at once, and a message says "Deleted Brand names" with **Undo**. You have 6 seconds to click **Undo** and get it back; after that it's gone for good. See [Undo a delete](https://docs.tryhamsa.com/media/workspace/lists-and-uploads.md#undo-a-delete).

![A dictionary row's menu open, with Copy ID and Delete](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/voices/dictionary-row-menu-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=cf85a7bc7e74748f17c9489f8ac1c747)

To delete several, tick their rows (or the box in the header), click **Delete** in the bar that appears and confirm once ("Delete 3 items?"). One **Undo** brings them all back. See [Act on several rows](https://docs.tryhamsa.com/media/workspace/lists-and-uploads.md#act-on-several-rows).

A dictionary that an agent in Hamsa Agents has turned on can't be deleted: "Dictionary is used in the following agent/s: \{agents}". Turn it off in those agents first.

## Good to know

* A dictionary name is 1 to 100 characters.
* **Copy ID** in the row menu copies the dictionary's ID, for the API.
* Use a dictionary for words a voice says wrong. To change the words themselves, edit your script.

## Related

> [card] [Generate speech](https://docs.tryhamsa.com/media/text-to-speech/generate-speech.md)
>
> Turn dictionaries on for a script.

> [card] [Voices library](https://docs.tryhamsa.com/media/voices/voices-library.md)
>
> Find the voice to test your corrections on.

> [card] [Dictionaries in Hamsa Agents](https://docs.tryhamsa.com/agents/voices/dictionaries.md)
>
> Use the same dictionaries on calls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.