How to Use Pronunciation Dictionaries
How to add, view, and remove rules to pronunciation dictionaries with the Python SDK
In this tutorial, you’ll learn how to use a pronunciation dictionary with the ElevenLabs Python SDK. Pronunciation dictionaries are useful for controlling the specific pronunciation of words. We support both IPA and CMU alphabets. It is useful for correcting rare or specific pronunciations, such as names or companies. For example, the word nginx
could be pronounced incorrectly. Instead, we can add our version of pronunciation. Based on IPA, nginx
is pronounced as /ˈɛndʒɪnˈɛks/
. Finding IPA or CMU of words manually can be difficult. Instead, LLMs like ChatGPT can help you to make the search easier.
We’ll start by adding rules to the pronunciation dictionary from a file and comparing the text-to-speech results that use and do not use the dictionary. After that, we’ll discuss how to add and remove specific rules to existing dictionaries.
If you want to jump straight to the finished repo you can find it here
Alias tags are supported by all models excluding eleven_turbo_v2_5
. Phoneme
tags only work with the models eleven_turbo_v2
and eleven_monolingual_v1
.
If you use phoneme tags with other models, they will silently skip the word.
Requirements
- An ElevenLabs account with an API key (here’s how to find your API key).
- Python installed on your machine
- FFMPEG to play audio
Setup
Installing our SDK
Before you begin, make sure you have installed the necessary SDKs and libraries. You will need the ElevenLabs SDK for the updating pronunciation dictionary and using text-to-speech conversion. You can install it using pip:
Additionally, install python-dotenv
to manage your environmental variables:
Next, create a .env
file in your project directory and fill it with your credentials like so:
Initiate the Client SDK
We’ll start by initializing the client SDK.
Create a Pronunciation Dictionary From a File
To create a pronunciation dictionary from a File, we’ll create a .pls
file for our rules.
This rule will use the “IPA” alphabet and update the pronunciation for tomato
and Tomato
with a different pronunciation. PLS files are case sensitive which is why we include it both with and without a capital “T”. Save it as dictionary.pls
.
In the following snippet, we start by adding rules from a file and get the uploaded result. Finally, we generate and play two different text-to-speech audio to compare the custom pronunciation dictionary.
Remove Rules From a Pronunciation Dictionary
To remove rules from a pronunciation dictionary, we can simply call remove_rules_from_the_pronunciation_dictionary
method in the pronunciation dictionary module. In the following snippet, we start by removing rules based on the rule string and get the updated result. Finally, we generate and play another text-to-speech audio to test the difference. In the example, we take pronunciation dictionary version id from remove_rules_from_the_pronunciation_dictionary
response because every changes to pronunciation dictionary will create a new version, so we need to use the latest version returned from the response. The old version also still available.
Add Rules to Pronunciation Dictionary
We can add rules directly to the pronunciation dictionary with PronunciationDictionaryRule_Phoneme
class and call add_rules_to_the_pronunciation_dictionary
from the pronunciation dictionary. The snippet will demonstrate adding rules with the class and get the updated result. Finally, we generate and play another text-to-speech audio to test the difference. This example also use pronunciation dictionary version returned from add_rules_to_the_pronunciation_dictionary
to ensure we use the latest dictionary version.
Conclusion
You know how to use a pronunciation dictionary for generating text-to-speech audio. These functionailities open up opportunities to generate text-to-speech audio based on your pronunciation dictionary, making it more flexible for your use case.
For more details, visit our example repo to see the full project files which give a clear structure for setting up your application:
env.example
: Template for your environment variables.main.py
: The complete code for snippets above.dictionary.pls
: Custom dictionary example with XML format.requirements.txt
: List of python package used for this example.
If you have any questions please create an issue on the elevenlabs-doc Github.
Was this page helpful?