Best Practices for Writing Text for TTS

A guide to writing text that produces natural-sounding speech output. Covers both text-formatting tips and model configuration recommendations for production use.

1. Punctuation for Pauses

Tip: Use … (ellipsis) to create a hesitation or trailing-off effect — it signals the speaker is thinking or pausing mid-thought. Use sparingly for natural results.

Tip: Use line breaks between paragraphs for natural breathing pauses:

हमारी technology सबको समझती है।
हमारा mission है कि हर Indian अपनी mother tongue में technology use कर सके।

2. Fillers & Hesitations for Natural Speech

Add fillers and hesitation markers to make speech sound conversational:

Combining fillers with ellipsis for natural hesitation:

So basically… हमारा goal है कि um हर Indian language को support करें।
I mean... यह easy नहीं है... but we're getting there.

3. Code-Mixing (Hinglish)

For natural Indian speech, mix English words where they’re commonly used. This is how most urban Indians speak — the model handles it well.

Rule: Write English words in English script, Hindi words in Devanagari:

• ✅ “Sarvam AI में आपका स्वागत है”
• ❌ “सरवम एआई में आपका स्वागत है”

Common code-mixed categories:

Full code-mixed examples:

So basically... हम India की हर language को voice देते हैं।
चाहे आप um Hindi बोलते हों, Tamil, Telugu, Bengali या like... कोई भी Indian language।
अगर आपको koi doubt है तो please हमें contact करें।
Meeting actually postpone हो गई है, I mean... tomorrow रखते हैं।

Keep Hindi sentence structure, swap key nouns/verbs with English:

• “हर Indian अपनी mother tongue में technology use कर सके”
• “आज का weather actually बहुत pleasant है”
• “यह app basically आपकी daily life को simple बना देगा”

4. Avoid These

5. Language-Specific Tips

Sentence-ending punctuation

• If a sentence ends in Hindi or a regional language, use ।: "हमारी technology सबको समझती है।"
  • If a sentence ends in English, use . : "प्लान simple है, just execute."

Writing Conventions

• Write language names in English: Tamil, Telugu, Bengali (not तमिल, तेलुगु)
• Keep brand names in English: Sarvam AI, Google, WhatsApp

6. Target Language Code

The target_language_code parameter is required for every TTS request. It is primarily effective for handling language-specific processing of numbers, abbreviations, and special characters.

Supported Languages

Example

1
audio = client.text_to_speech.convert(
2
    text="नमस्ते! Sarvam AI में आपका स्वागत है।",
3
    model="bulbul:v3",
4
    target_language_code="hi-IN",  
5
    speaker="shubh"
6
)

7. Understanding the Audio Output (Base64)

The TTS API returns audio data as a base64-encoded string. You must decode this string before saving or playing the audio file.

REST API Response

The REST API returns a response with an audios field — an array of base64-encoded audio strings. You need to decode them:

1
import base64
2
from sarvamai import SarvamAI
3
4
client = SarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")
5
6
audio = client.text_to_speech.convert(
7
    text="नमस्ते! Sarvam AI में आपका स्वागत है।",
8
    model="bulbul:v3",
9
    target_language_code="hi-IN",
10
    speaker="shubh"
11
)
12
13
# The response contains base64-encoded audio in the 'audios' field
14
# Combine all audio chunks and decode from base64
15
combined_audio = "".join(audio.audios)
16
audio_bytes = base64.b64decode(combined_audio)
17
18
with open("output.wav", "wb") as f:
19
    f.write(audio_bytes)

Streaming API Response

For the streaming (WebSocket) API, each chunk arrives as a base64-encoded audio string. Decode each chunk as it arrives:

1
import asyncio
2
import base64
3
from sarvamai import AsyncSarvamAI, AudioOutput
4
5
async def tts_stream():
6
    client = AsyncSarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")
7
8
    async with client.text_to_speech_streaming.connect(model="bulbul:v3") as ws:
9
        await ws.configure(
10
            target_language_code="hi-IN",
11
            speaker="shubh"
12
        )
13
14
        await ws.convert("नमस्ते! Sarvam AI में आपका स्वागत है।")
15
        await ws.flush()
16
17
        with open("output.wav", "wb") as f:
18
            async for message in ws:
19
                if isinstance(message, AudioOutput):
20
                    # Each chunk is base64-encoded — decode before writing
21
                    audio_chunk = base64.b64decode(message.data.audio)
22
                    f.write(audio_chunk)
23
24
asyncio.run(tts_stream())

8. Choosing the Right API Mode

Bulbul v3 supports two API modes. Choosing correctly has a significant impact on latency and user experience.

9. Voice Parameter Tuning — Pace & Temperature

Two parameters give you fine-grained control over how Bulbul v3 sounds. Getting these right is the single most impactful tuning lever available to developers.

Pace (Range: 0.5 – 2.0)

pace controls the speaking rate relative to the model’s natural speed. 1.0 is native speed.

Default recommendation: Start at 1.0 (natural) or 1.1 (brisk, professional contexts). Avoid values above 1.5 unless specifically building speed-listening features.

Temperature (Range: 0.01 – 1.0)

temperature controls expressiveness and prosodic variation. Lower values produce consistent, predictable delivery; higher values introduce more natural pitch variation and emotional colour.

10. Speaker Selection by Language

Not all speakers perform equally across all languages. Always use the language-specific recommendations below rather than arbitrary speaker selection.

Top picks: priya & ishita (best female, excellent across Hindi, Telugu, Kannada, Tamil, Marathi, Gujarati, English) · mani (best male overall, Punjabi) · shubh (best male for hi, te, kn, od, ml) · ratan (best male for en, te, kn, ta, mr, gu).

11. Use-Case Quick Reference

Recommended parameter and speaker combinations for common production scenarios:

12. Output Format Recommendations

13. Known Limitations

14. Key Considerations

• For numbers greater than 4 digits, use commas (e.g., 10,000 instead of 10000) for correct pronunciation.