How do I fix TTS mispronouncing a specific word or name?

Create a pronunciation dictionary in Gradium Studio (on the pronunciation page) or via the API, define the mapping from the word to its intended spoken form, and attach the dictionary to your TTS session by passing the dictionary ID as `pronunciation_id` in the WebSocket setup message. The mapping applies server-side to every occurrence of that word in the session. The full guide is at How to Use Pronunciation Dictionaries in Gradium TTS.

What is the difference between pronunciation dictionaries and rewrite_rules?

`rewrite_rules` handle structural patterns: numeric date formats, phone number grouping conventions, email address expansion, URL expansion, and alphanumeric code spelling. They apply algorithmically to any input matching the pattern. Pronunciation dictionaries handle lexical exceptions: specific words, names, acronyms, and technical terms with non-standard pronunciation. The two mechanisms are complementary and can be applied simultaneously in the same TTS session.

How do I make TTS pronounce an acronym correctly?

Add the acronym to a pronunciation dictionary with its intended spoken form. For a spelled-out acronym like "API," the dictionary maps the string "API" to the spoken sequence "A P I." For a word-form acronym like "NASA," the dictionary maps it to the spoken word "NASA." The dictionary resolves the ambiguity that a TTS model without explicit guidance cannot determine on its own.

Can I use a pronunciation dictionary for brand names?

Yes. This is one of the primary documented use cases for Gradium pronunciation dictionaries: "brand names, technical terminology, and industry-specific acronyms are pronounced correctly every time." A brand name with non-obvious pronunciation (such as "Hermes" or "Audi" or a proprietary product name) is mapped to its correct spoken form in the dictionary and applied consistently across every synthesis request in the session.

Why is a word being mispronounced even though it looks phonetically straightforward?

If the word appears in your LLM output split across two WebSocket messages in a streaming pipeline, the Gradium server inserts a whitespace between the message contents, changing the pronunciation. Ensure that words are not split at message boundaries when streaming LLM tokens to the TTS API incrementally. This is a common source of unexpected mispronunciation in LLM-TTS interleaving setups.

Can pronunciation dictionaries also filter out unwanted content?

Yes. Beyond pronunciation control, Gradium pronunciation dictionaries support content filtering: words or phrases can be configured to be silently skipped or replaced in the TTS output. This makes them useful for profanity filtering and brand-safety compliance in addition to pronunciation correction. Both capabilities are managed through the same dictionary interface in Gradium Studio.

How to Fix TTS Mispronouncing Names, Acronyms, and Technical Terms

A TTS model's training data determines what it can pronounce reliably. Standard vocabulary is covered well. Proper nouns, brand names, technical acronyms, domain-specific terms, and industry jargon are underrepresented in most training corpora, which means the model applies phonological guessing rules that are frequently wrong.

Gradium's TTS handles these edge cases natively and offers a custom pronunciation dictionary API for domain-specific terms. For the lexical items the model does not know, pronunciation dictionaries are the mechanism that gives developers direct control over exactly how specific words or phrases are spoken.

This article covers the two tools available for fixing TTS pronunciation of names, acronyms, and technical terms in Gradium: pronunciation dictionaries (for lexical control) and rewrite_rules (for structural pattern handling), and how to use each.

Why do TTS models mispronounce names, acronyms, and technical terms?

The cause is the same as for structured content like phone numbers: training data distribution. A TTS model learns pronunciation from the text-audio pairs it was trained on. Standard English vocabulary is well-represented. Domain-specific vocabulary is not.

Three specific failure modes appear consistently in production:

Names with non-obvious pronunciation. Personal names, company names, and geographic names frequently have pronunciations that do not follow standard English phonological rules. "Siobhan" does not sound like it looks. Neither does "Nguyen," "Cholmondeley," or "Featherstonehaugh." A model that has not encountered these names in its training data will apply rules that produce incorrect output.

Acronyms that should be spelled out vs pronounced as words. "API" should be "A P I," letter by letter. "NASA" should be "NASA" as a word. "URL" is "U R L." "SCUBA" is a word. A model without explicit guidance on which acronyms are pronounced which way will guess, and its guesses are inconsistent. In Gradium's June 2026 TTS upgrade evaluation, spelling and acronym handling is one of the four primary categories measured in pass/fail listening tests alongside numbers, common expressions, and audio artifacts.

Technical terms from specific industries. Drug names, legal terms, financial instrument names, engineering standards, and medical abbreviations all carry pronunciations that are domain conventions rather than phonological derivations. "Fluoxetine," "LIBOR," "OAuth," "HIPAA," "GLP-1" each requires a pronunciation that most general TTS training data does not contain.

Which tool fixes which pronunciation problem?

Before reaching for a pronunciation dictionary, it helps to know which tool actually solves which problem.

Pronunciation dictionaries are the right tool for lexical exceptions: specific words, names, acronyms, and technical terms with non-standard or domain-specific pronunciations. The dictionary maps a word or phrase to its intended spoken form, and the mapping applies every time that word appears in the input text during that session.

rewrite_rules are the right tool for structural patterns: numeric formats, date conventions, phone number groupings, email address expansion, URL handling. These are covered in detail in How to Make TTS Pronounce Numbers, Dates, and Phone Numbers Correctly.

For names, acronyms, and technical terms, pronunciation dictionaries are the correct mechanism. They provide word-level control that normalization rules cannot derive algorithmically.

How do pronunciation dictionaries work in Gradium?

Pronunciation dictionaries allow you to customize how specific words or phrases are pronounced in your TTS output, so brand names, technical terminology, and industry-specific acronyms come out correctly every time. They are particularly useful for healthcare, finance, and other industry-specific applications. The API reference is at docs.gradium.ai.

A dictionary is created once and assigned an ID. The ID is passed as the pronunciation_id parameter in the TTS WebSocket setup message, and the dictionary applies to every synthesis request in that session. The session does not need to be aware of which words are in the dictionary: the lookup happens server-side before synthesis.

Pronunciation dictionaries are also used for content filtering: words or phrases can be marked to be silently skipped or replaced in the output, which makes them useful for profanity filtering and brand-safety compliance on top of their pronunciation use cases.

How do you create a pronunciation dictionary in Gradium Studio?

The simplest way to create and manage pronunciation dictionaries is through Gradium Studio, on the pronunciation page. Once you have created a dictionary and obtained its ID, you can use it in your TTS requests by passing the pronunciation_id parameter.

The Studio interface lets you add word-to-pronunciation mappings, test them immediately against the TTS model, and update the dictionary without changing your API integration. Once the dictionary ID is obtained from Studio, it is passed to the API at session setup.

How do you use a pronunciation dictionary with the Python SDK?

For teams managing pronunciation dictionaries programmatically, the Gradium API exposes full CRUD operations: list dictionaries for the authenticated organization, get a dictionary by its UID, create a new dictionary, and update an existing dictionary by its UID.

A minimal TTS stream with a pronunciation dictionary attached:

stream = await client.tts_stream(
    setup={
        "voice_id": "YTpq7expH9539ERJ",
        "output_format": "pcm",
        "pronunciation_id": "your-pronunciation-dict-id"
    },
    text=text_generator()
)
async for chunk in stream.iter_bytes():
    pass

The pronunciation_id is set once in the setup object and applies for the duration of that stream session. It can be combined with json_config in the same setup object to apply both normalization rules and pronunciation dictionary corrections simultaneously.

Can you combine pronunciation dictionaries with rewrite_rules?

In production, most voice agents need both mechanisms. A healthcare voice agent might need date and time normalization (rewrite_rules) for appointment confirmations and a pronunciation dictionary for drug names and medical terminology. A financial voice agent might need number and currency normalization alongside a dictionary for fund names and ticker symbols.

Both can be set in a single WebSocket setup message:

{
  "type": "setup",
  "voice_id": "your-voice-id",
  "output_format": "pcm",
  "pronunciation_id": "your-pronunciation-dict-id",
  "json_config": {
    "rewrite_rules": "en"
  }
}

The two mechanisms are applied in sequence: rewrite_rules normalization expands structural patterns in the input text first, then the pronunciation dictionary corrects specific word pronunciations during synthesis.

Why can streaming message boundaries change pronunciation?

One technical note from the Gradium documentation is specifically relevant to pronunciation: when text is sent incrementally across multiple messages in a WebSocket stream, the server inserts a single whitespace between consecutive messages. Sending "foo" followed by "bar" is synthesized as "foo bar", not "foobar", so splitting a single word across two messages will change its pronunciation.

The practical implication for LLM-TTS pipelines: when streaming LLM tokens to the TTS API as they arrive, do not split a single word across two message boundaries. Punctuation must also stay attached to the preceding word: "sending 'foo' followed by '.' produces 'foo .' rather than 'foo.'". Trailing punctuation must be included in the same message as the preceding word to ensure correct prosody and pronunciation.

This is unrelated to pronunciation dictionaries themselves, but it is a common source of unexpected mispronunciation in streaming pipelines that is easy to miss in integration.

Which industries need pronunciation dictionaries most?

The Gradium documentation explicitly positions pronunciation dictionaries as the right tool for healthcare, finance, and industry-specific applications. The same mechanism applies across other domains:

Healthcare: drug names (fluoxetine, tirzepatide, adalimumab), procedure names, anatomical terms, medical abbreviations (GLP-1, SSRI, IV, NG), regulatory acronyms (HIPAA, ICD, CPT).

Finance: fund names, index names (MSCI, LIBOR), regulatory terms (AML, KYC, FATCA), ticker symbols that should be spelled letter by letter vs those pronounced differently.

Legal: case citations, Latin terms with established English legal pronunciations, regulatory body names, jurisdiction-specific terminology.

Enterprise software: product names, internal code systems, organizational units with non-standard names, technical standards (OAuth, SAML, GDPR, API, SDK).

Branded products: company names with non-obvious pronunciation, product line names, trademark-specific pronunciation conventions.

Glossary

Pronunciation dictionary

A developer-defined mapping from specific words or phrases to their intended spoken form in TTS output. Applied to a session via the pronunciation_id parameter in the Gradium TTS WebSocket setup message. Used for brand names, domain-specific terms, acronyms, and proper nouns with non-standard pronunciation. Also supports content filtering.

pronunciation_id

The parameter in the Gradium TTS WebSocket setup message that attaches a pronunciation dictionary to a session. The dictionary is created in Gradium Studio or via the API and identified by a unique UID. Applies server-side to every synthesis request on that session.

rewrite_rules

A field in json_config that enables structural text normalization rules (dates, phone numbers, email addresses, URLs, alphanumeric codes) applied before synthesis. Complementary to pronunciation dictionaries, which handle lexical exceptions rather than structural patterns.

Lexical exception

A word or phrase whose pronunciation cannot be derived from its spelling using standard phonological rules. Examples: proper names, brand names, domain-specific acronyms, foreign-origin terms. The correct tool for lexical exceptions in Gradium TTS is a pronunciation dictionary, not a normalization rule.

Acronym handling

The TTS behavior that determines whether a string of letters is spelled out character by character (API → "A P I") or pronounced as a word (NASA → "NASA"). TTS models without explicit guidance guess on a pattern basis, which is inconsistent. Pronunciation dictionaries specify the intended behavior for each acronym in the system.

Message boundary (WebSocket streaming)

In Gradium's TTS WebSocket API, the server inserts a whitespace between the content of consecutive text messages. Splitting a word or a word's trailing punctuation across two messages changes pronunciation. Words and their trailing punctuation must be kept in the same message in streaming pipelines.