Skip to content
KugelAudioDocs

Spell tags

Spell tags read emails, codes, acronyms and serial numbers character by character, with per-language character translations, grouped spelling and pitfalls.

On this page

Wrapping text in <spell> tags causes each character to be read out individually. Useful for email addresses, verification codes, acronyms, and serial numbers.

Text
"Contact us at <spell>hello@kugelaudio.com</spell>"
→  "Contact us at H, E, L, L, O at K, U, G, E, L, A, U, D, I, O Dot C, O, M"

Codes that contain digits are automatically grouped with short pauses so a listener can follow them.

Character translations by language

Letters are read by their names and digits as number words ("one", "zwei"). Symbols are read as:

CharacterEnglishGermanFrenchSpanish
@atatarobasearroba
.DotPunktPointPunto
-DashMinusTiretGuion
/slashschrägstrichbarre obliquebarra
+plusplusplusmás
#hashRautedièsealmohadilla
&andundety
spacespacespaceespaceespacio

Whitespace inside a spell block is read as the language's own word where the voices say it more reliably (French "espace", Spanish "espacio", Italian "spazio", Polish "spacja") and as the English word "space" in the other languages.

Accented letters are read by their spoken name in French, Spanish and Portuguese ("E accent aigu", "eñe", "C cedilha"). Where a language has no name for an accented letter, it is read as its base letter, so José is spelled "J, O, S, E" in English and Dutch.

A few letters use their native name where the voices otherwise fall back to the English one: Spanish "zeta" and "i griega", Italian "i lunga", Polish "igrek" and "fau", Portuguese "agá" and "capa", Dutch "jee".

Other characters without a spoken word, such as _, are passed through unchanged and count as a letter for grouping. Write the word yourself outside the tag when it matters ("underscore", "Unterstrich").

Grouping

Codes are grouped automatically: a 500 ms pause (· below) every four characters, the way a human reads a code aloud.

Text
"The VIN is <spell>1G1RC6E49BU123456</spell>"
→  "one, G, one, R · C, six, E, four · nine, B, U, one · two, three, four, five · six"

A run of characters ends at every space and at every spoken symbol (., -, @, /, ...), and each run is grouped on its own. Only runs that contain a digit are grouped automatically. Runs made only of letters, such as names and the parts of an email address, are read without pauses, because a pause inside a spelled word can make the voice repeat the letter next to it:

Text
"The name is <spell>Anastasiia Masaltseva</spell>"
→  "A, N, A, S, T, A, S, I, I, A space M, A, S, A, L, T, S, E, V, A"

"The code is <spell>CRM-7Z4Q9X</spell>"
→  "C, R, M Dash seven, Z, four, Q · nine, X"

Override the group size with group="N". An explicit size groups every run, letters included:

Text
"Your code is <spell group="2">A4B9XZ</spell>"
→  "A, four · B, nine · X, Z"

Use group="0" to switch grouping off and have the content read as one unbroken run (A, four, B, nine, X, Z).

Examples

Python
# Email address
audio = client.tts.generate(
    text="Email us at <spell>hello@kugelaudio.com</spell>",
    voice_id=1071,
    normalize=True,
    language="en",
)

# Verification code, grouped in pairs
audio = client.tts.generate(
    text='Your code is <spell group="2">A4B9XZ</spell>',
    voice_id=1071,
    normalize=True,
    language="en",
)

# Acronym with context
audio = client.tts.generate(
    text="We use <spell>TTS</spell>, text-to-speech, for audio output.",
    voice_id=1071,
    normalize=True,
    language="en",
)

Pitfalls

  • No nesting. A <spell> tag inside another spell block is read as literal characters.
  • No break tags inside spell blocks. Use grouping for pacing instead.

Spell tags in streaming

When streaming text token by token, a bare <spell> tag may be split across messages: the server buffers text until the closing </spell> arrives before generating audio, and auto-closes an unfinished tag if the stream ends. This buffering does not cover <spell group="N">: send a grouped tag, from opening to closing tag, within one message. See Streaming overview.

When spelling isn't enough

If a brand name or domain term is pronounced wrong (rather than needing to be spelled out), use a pronunciation dictionary instead. It rewrites or IPA-annotates the word without changing your request text.

Next steps