Skip to content
KugelAudioDocs

Text normalization

How KugelAudio text normalization reads numbers, dates, times and currencies aloud before speech synthesis, the supported languages, and how to control it.

On this page

KugelAudio normalizes request text so it is spoken naturally: numbers, dates, times, and currencies become words before synthesis.

Text Normalization

Text normalization converts numbers, dates, times, and other non-verbal text into spoken words:

  • "I have 3 apples" → "I have three apples"
  • "The meeting is at 2:30 PM" → "The meeting is at two thirty PM"
  • "€50.99" → "fifty euros and ninety-nine cents"

Normalization is on by default (normalize=True in Python, normalize: true in JavaScript and JSON). It runs in the request language. If you omit language, each sentence is normalized in the language it is written in, so English text sent to a German voice is read with English numbers, dates and currencies (in the voice's own accent). The language is recognized from common words in English, German, French, Spanish, Italian, Portuguese, Dutch, Polish, Czech, Turkish, Danish, Norwegian, Swedish and Finnish. When a sentence gives no clear sign of another language (a short fragment, only digits, or another language), it keeps the language of the sentence before it, starting with the voice's primary language (the first entry of its supported_languages), and English if the voice has none.

Python
# With explicit language (recommended)
audio = client.tts.generate(
    text="I bought 3 items for €50.99 on 01/15/2024.",
    voice_id=1071,
    normalize=True,
    language="en",
)

# Without language: normalized in the language the text is written in
audio2 = client.tts.generate(
    text="Ich habe 3 Artikel für 50,99€ gekauft.",
    voice_id=1071,
    normalize=True,
)

normalize: false does not turn normalization off: it skips the language-model pass, and basic expansion of numbers, dates, times, and currencies still runs on every request. The language-model pass runs only in the languages its model was trained on, so in any other supported language normalize: true produces the same text as normalize: false. To line word timestamps up with the text you sent, use their original_char_start/original_char_end offsets (Word timestamps), not your own normalization.

Supported Languages

CodeLanguageCodeLanguage
deGermannlDutch
enEnglishplPolish
frFrenchsvSwedish
esSpanishdaDanish
itItaliannoNorwegian
ptPortuguesefiFinnish
csCzechhuHungarian
roRomanianelGreek
ukUkrainianbgBulgarian
trTurkishviVietnamese
arArabichiHindi
zhChinesejaJapanese
koKoreanskSlovak
slSlovenianhrCroatian
srSerbianruRussian
heHebrewfaPersian
urUrdubnBengali
taTamilyueCantonese
thThaiidIndonesian
msMalay

Spell Tags

Content inside <spell> tags is read character by character and bypasses normalization; the surrounding text is still normalized. Syntax, grouping, and per-language symbol words are on Spell tags.

Custom Pronunciation Dictionaries

When normalization and <spell> tags aren't enough (brand names, product names, acronyms the model gets wrong), use a per-project dictionary. It applies to requests that send the dictionary's project_id, and a change takes effect on the next request.

Manage dictionaries from the dashboard or the API:

Next Steps