Skip to content
KugelAudioDocs

Text Normalization

SDK reference for text normalization: turn numbers, dates and symbols into spoken words with the normalize and language options, and spell out text with tags.

On this page

Text normalization converts numbers, dates, times, and other non-verbal text into spoken words (for example "3 apples" becomes "three apples"). It is on by default. How it works, the supported languages and their codes are documented in Text processing. The SDKs control it with the normalize and language options:

# 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
audio = client.tts.generate(
    text="Ich habe 3 Artikel für 50,99€ gekauft.",
    voice_id=1071,
    normalize=True,
    # language not specified: recognized from the text (here German)
)

Without a language, the Rust, C++ and Dart SDKs log a warning when normalization is on.

Spell tags

Wrap text in <spell> tags to have it read character by character (emails, codes, acronyms). Tag semantics and per-language character names are in Spell tags. In a streaming session, a tag split across tokens is handled for you:

async with client.tts.streaming_session(
    voice_id=1071,
    normalize=True,
    language="en",
) as session:
    async for chunk in session.send("My code is <spell>"):
        play_audio(chunk.audio)
    async for chunk in session.send("ABC123</spell>"):
        play_audio(chunk.audio)
    async for chunk in session.flush():
        play_audio(chunk.audio)

play_audio / playAudio stands for your own playback function.

Next steps

  • Dictionaries: per-project pronunciation and replacement lists
  • Generate speech: generation parameters including normalize and language