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.
# 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,
)// With explicit language (recommended)
const audio = await client.tts.generate({
text: 'I bought 3 items for €50.99 on 01/15/2024.',
voiceId: 1071,
normalize: true,
language: 'en',
});
// Without language: normalized in the language the text is written in
const audio2 = await client.tts.generate({
text: 'Ich habe 3 Artikel für 50,99€ gekauft.',
voiceId: 1071,
normalize: true,
});// With explicit language (recommended)
AudioResponse audio = client.tts().generate(
GenerateRequest.builder("I bought 3 items for €50.99 on 01/15/2024.")
.voiceId(1071)
.normalize(true)
.language("en")
.build()
);
// Without language: normalized in the language the text is written in
AudioResponse audio2 = client.tts().generate(
GenerateRequest.builder("Ich habe 3 Artikel für 50,99€ gekauft.")
.voiceId(1071)
.normalize(true)
.build()
);# With explicit language (recommended)
curl -X POST https://api.kugelaudio.com/v1/tts/generate \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "I bought 3 items for €50.99 on 01/15/2024.",
"voice_id": 1071,
"normalize": true,
"language": "en"
}' \
--output output.pcm
# Without language: normalized in the language the text is written in
curl -X POST https://api.kugelaudio.com/v1/tts/generate \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Ich habe 3 Artikel für 50,99€ gekauft.",
"voice_id": 1071,
"normalize": true
}' \
--output output.pcmnormalize: 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
| Code | Language | Code | Language |
|---|---|---|---|
de | German | nl | Dutch |
en | English | pl | Polish |
fr | French | sv | Swedish |
es | Spanish | da | Danish |
it | Italian | no | Norwegian |
pt | Portuguese | fi | Finnish |
cs | Czech | hu | Hungarian |
ro | Romanian | el | Greek |
uk | Ukrainian | bg | Bulgarian |
tr | Turkish | vi | Vietnamese |
ar | Arabic | hi | Hindi |
zh | Chinese | ja | Japanese |
ko | Korean | sk | Slovak |
sl | Slovenian | hr | Croatian |
sr | Serbian | ru | Russian |
he | Hebrew | fa | Persian |
ur | Urdu | bn | Bengali |
ta | Tamil | yue | Cantonese |
th | Thai | id | Indonesian |
ms | Malay |
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:
- Guide: Dictionaries, how pronunciation dictionaries work
- API:
/v1/dictionaries, full CRUD plus idempotent bulk replace - SDKs:
client.dictionaries.*in Python, TypeScript and Java (SDK reference)