Text Normalization & Spelling

KugelAudio provides text processing features to ensure your text is spoken naturally. This includes automatic normalization of numbers, dates, and currencies, as well as the ability to spell out text letter by letter.

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”

Enable normalization by setting normalize=True (Python), normalize: true (JavaScript), or "normalize": true (JSON):

Python
JavaScript
Java
cURL

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

# With auto-detection (may cause incorrect normalizations)
audio = client.tts.generate(
    text="Ich habe 3 Artikel für 50,99€ gekauft.",
    normalize=True,
    # language not specified - will auto-detect
)

// With explicit language (recommended - fastest)
const audio = await client.tts.generate({
  text: 'I bought 3 items for €50.99 on 01/15/2024.',
  normalize: true,
  language: 'en',
});

// With auto-detection (may cause incorrect normalizations)
const audio = await client.tts.generate({
  text: 'Ich habe 3 Artikel für 50,99€ gekauft.',
  normalize: true,
  // language not specified - will auto-detect
});

// With explicit language (recommended - fastest)
AudioResponse audio = client.tts().generate(
    GenerateRequest.builder("I bought 3 items for €50.99 on 01/15/2024.")
        .normalize(true)
        .language("en")
        .build()
);

// With auto-detection (may cause incorrect normalizations)
AudioResponse audio2 = client.tts().generate(
    GenerateRequest.builder("Ich habe 3 Artikel für 50,99€ gekauft.")
        .normalize(true)
        // language not specified - will auto-detect
        .build()
);

# With explicit language (recommended - fastest)
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.",
    "normalize": true,
    "language": "en"
  }' \
  --output output.pcm

# With auto-detection (may cause incorrect normalizations)
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.",
    "normalize": true
  }' \
  --output output.pcm

Using normalize without specifying language may cause incorrect normalizations, especially for short texts or languages that share similar vocabulary. Always specify language when you know it.

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

Use <spell> tags to spell out text letter by letter. This is useful for email addresses, codes, acronyms, or any text that should be pronounced character by character.

Spell tags require normalize to be enabled.

Python
JavaScript
Java
cURL

# Spell out an email address
audio = client.tts.generate(
    text="Contact me at <spell>kajo@kugelaudio.com</spell>",
    normalize=True,
    language="en",
)
# Output: "Contact me at K, A, J, O, at, K, U, G, E, L, A, U, D, I, O, dot, C, O, M"

# Spell out an acronym
audio = client.tts.generate(
    text="The <spell>API</spell> is easy to use.",
    normalize=True,
    language="en",
)
# Output: "The A, P, I is easy to use."

# German example with language-specific translations
audio = client.tts.generate(
    text="Meine E-Mail ist <spell>test@beispiel.de</spell>",
    normalize=True,
    language="de",
)
# Output: "Meine E-Mail ist T, E, S, T, ät, B, E, I, S, P, I, E, L, Punkt, D, E"

// Spell out an email address
const audio = await client.tts.generate({
  text: 'Contact me at <spell>kajo@kugelaudio.com</spell>',
  normalize: true,
  language: 'en',
});
// Output: "Contact me at K, A, J, O, at, K, U, G, E, L, A, U, D, I, O, dot, C, O, M"

// Spell out an acronym
const audio2 = await client.tts.generate({
  text: 'The <spell>API</spell> is easy to use.',
  normalize: true,
  language: 'en',
});
// Output: "The A, P, I is easy to use."

// German example with language-specific translations
const audio3 = await client.tts.generate({
  text: 'Meine E-Mail ist <spell>test@beispiel.de</spell>',
  normalize: true,
  language: 'de',
});
// Output: "Meine E-Mail ist T, E, S, T, ät, B, E, I, S, P, I, E, L, Punkt, D, E"

// Spell out an email address
AudioResponse audio = client.tts().generate(
    GenerateRequest.builder("Contact me at <spell>kajo@kugelaudio.com</spell>")
        .normalize(true)
        .language("en")
        .build()
);
// Output: "Contact me at K, A, J, O, at, K, U, G, E, L, A, U, D, I, O, dot, C, O, M"

// Spell out an acronym
AudioResponse audio2 = client.tts().generate(
    GenerateRequest.builder("The <spell>API</spell> is easy to use.")
        .normalize(true)
        .language("en")
        .build()
);
// Output: "The A, P, I is easy to use."

// German example with language-specific translations
AudioResponse audio3 = client.tts().generate(
    GenerateRequest.builder("Meine E-Mail ist <spell>test@beispiel.de</spell>")
        .normalize(true)
        .language("de")
        .build()
);
// Output: "Meine E-Mail ist T, E, S, T, ät, B, E, I, S, P, I, E, L, Punkt, D, E"

# Spell out an email address
curl -X POST https://api.kugelaudio.com/v1/tts/generate \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Contact me at <spell>kajo@kugelaudio.com</spell>",
    "normalize": true,
    "language": "en"
  }' \
  --output output.pcm
# Output: "Contact me at K, A, J, O, at, K, U, G, E, L, A, U, D, I, O, dot, C, O, M"

# Spell out an acronym
curl -X POST https://api.kugelaudio.com/v1/tts/generate \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The <spell>API</spell> is easy to use.",
    "normalize": true,
    "language": "en"
  }' \
  --output output.pcm
# Output: "The A, P, I is easy to use."

Language-Specific Character Translations

Special characters within <spell> tags are translated based on the language:

Character	English	German	French	Spanish
`@`	at	ät	arobase	arroba
`.`	dot	Punkt	point	punto
`-`	dash	Strich	tiret	guión
`_`	underscore	Unterstrich	underscore	guión bajo

Spell Tags with Streaming

Spell tags work seamlessly with streaming. When streaming text token-by-token (e.g., from an LLM), tags that span multiple chunks are automatically handled:

Python
JavaScript
Java
cURL

async with client.tts.streaming_session(
    voice_id=123,
    normalize=True,
    language="en",
) as session:
    # Even if the tag is split across tokens, it works correctly
    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)

await client.tts.stream(
  {
    text: 'My verification code is <spell>ABC-123-XYZ</spell>.',
    normalize: true,
    language: 'en',
  },
  {
    onChunk: (chunk) => playAudio(chunk.audio),
  }
);

import com.kugelaudio.sdk.StreamingSession;
import com.kugelaudio.sdk.StreamConfig;

try (StreamingSession session = client.tts().streamingSession(
        StreamConfig.builder()
            .normalize(true)
            .language("en")
            .build())) {

    // Even if the tag is split across sends, it works correctly
    session.send("My code is <spell>", false);
    session.send("ABC123</spell>", true);
}

curl -X POST https://api.kugelaudio.com/v1/tts/generate \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "My verification code is <spell>ABC-123-XYZ</spell>.",
    "normalize": true,
    "language": "en"
  }' \
  --no-buffer | ffplay -f s16le -ar 24000 -ac 1 -nodisp -

Streaming Safety: The system buffers text until the closing </spell> tag arrives before generating audio. If the stream ends unexpectedly, incomplete tags are auto-closed so the content still gets spelled out.

Model recommendation: For clearer letter-by-letter pronunciation, use kugel-1 instead of kugel-1-turbo.

Using Spell Tags with LLMs

When integrating with language models, add instructions to your system prompt so the LLM wraps appropriate text in spell tags:

SYSTEM_PROMPT = """You are a helpful assistant. When you need to spell out text 
(like email addresses, codes, or acronyms), wrap it in <spell> tags.

Examples:
- "My email is <spell>kajo@kugelaudio.com</spell>"
- "The code is <spell>ABC123</spell>"
- "That stands for <spell>API</spell>, Application Programming Interface"
"""

For more details, see the LLM Integration guide.

Next Steps

Generate Speech

Basic speech generation

Streaming

Real-time audio streaming

LLM Integration

Integrate with GPT-4, Claude, and more

Getting Started

Speech Generation

Voices

Integrations

Self-Hosted

SDK Reference

Text Normalization & Spelling