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.
"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:
| Character | English | German | French | Spanish |
|---|---|---|---|---|
@ | at | at | arobase | arroba |
. | Dot | Punkt | Point | Punto |
- | Dash | Minus | Tiret | Guion |
/ | slash | schrägstrich | barre oblique | barra |
+ | plus | plus | plus | más |
# | hash | Raute | dièse | almohadilla |
& | and | und | et | y |
| space | space | space | espace | espacio |
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.
"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:
"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:
"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
# 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",
)// Email address
const audio = await client.tts.generate({
text: 'Email us at <spell>hello@kugelaudio.com</spell>',
voiceId: 1071,
normalize: true,
language: 'en',
});
// Verification code, grouped in pairs
const audio2 = await client.tts.generate({
text: 'Your code is <spell group="2">A4B9XZ</spell>',
voiceId: 1071,
normalize: true,
language: 'en',
});curl -X POST https://api.kugelaudio.com/v1/tts/generate \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Your code is <spell group=\"2\">A4B9XZ</spell>",
"voice_id": 1071,
"normalize": true,
"language": "en"
}' --output output.pcmPitfalls
- 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.