Best Practices for Writing Text for TTS

A guide to writing text that produces natural-sounding speech output.

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())

9. Key Considerations

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