Skip to main content

Usage guide

Setup, environment variables, and Python/JavaScript/Go usage examples.

​
SarvamAITTS

Sarvam AI text-to-speech plugin using the bulbul:v3 model. Converts text to speech via the Sarvam AI TTS API with support for 11 Indic languages, 43+ speaker voices, and fine-grained prosody controls (pace, temperature). Streaming mode emits audio chunks as they arrive to minimise time-to-first-byte for real-time voice agents.

​
Constructor

​
api_key
str | None
Sarvam AI API key. Falls back to the SARVAM_API_KEY environment variable when None.
​
model
SarvamAITTSModel | str
default:"bulbul:v3"
TTS model ID. Defaults to 'bulbul:v3', the latest model supporting 30+ voices and temperature control. 'bulbul:v2' is the legacy alternative with pitch and loudness controls.
​
language
str
default:"en-IN"
BCP-47 language code for synthesised speech. Defaults to 'en-IN'. Supported values: 'bn-IN', 'en-IN', 'gu-IN', 'hi-IN', 'kn-IN', 'ml-IN', 'mr-IN', 'od-IN', 'pa-IN', 'ta-IN', 'te-IN'.
​
speaker
str
default:"shubh"
Speaker/voice name. Defaults to 'shubh'. bulbul:v3 supports 43 voices including 'aditya', 'ritu', 'priya', 'neha', 'rahul', 'pooja', 'rohan', 'simran', 'kavya', 'amit', 'dev', 'ishita', 'shreya', 'ratan', 'varun', 'manan', 'sumit', 'roopa', 'kabir', 'aayan', and others.
​
streaming
bool
default:"True"
When True (default), audio is streamed back in chunks. Set to False for a single-response download.
​
sample_rate
int
default:"24000"
Output audio sample rate in Hz. Defaults to 24000. Supported values: 8000, 16000, 22050, 24000; bulbul:v3 also supports 32000, 44100, 48000 via the REST API.
​
output_audio_codec
str
default:"linear16"
Audio encoding for the returned audio. Defaults to 'linear16' (PCM). Other options: 'mp3', 'mulaw', 'alaw', 'opus', 'flac', 'aac', 'wav'.
​
pitch
float | None
default:"0.0"
Pitch adjustment (bulbul:v2 only). Range -0.75 to 0.75; 0.0 is neutral. Has no effect on bulbul:v3.
​
pace
float | None
default:"1.0"
Speaking rate multiplier. Defaults to 1.0 (normal speed). bulbul:v3 range: 0.5–2.0; bulbul:v2 range: 0.3–3.0.
​
loudness
float | None
default:"1.0"
Volume multiplier (bulbul:v2 only). Range 0.3– 3.0; 1.0 is neutral. Has no effect on bulbul:v3.
​
temperature
float | None
default:"0.6"
Expressiveness/variability control (bulbul:v3 only). Range 0.01–2.0; default 0.6. Lower values produce more deterministic output.
​
bitrate
str
default:"128k"
MP3 bitrate when output_audio_codec='mp3'. Defaults to '128k'.
​
min_buffer_size
int
default:"50"
Minimum number of characters to accumulate before sending a synthesis request in streaming mode. Defaults to 50.
​
max_chunk_length
int
default:"150"
Maximum number of characters per synthesis chunk. Defaults to 150.
​
preprocessing
bool
default:"False"
When True, enables server-side text pre-processing (e.g. number normalisation, acronym expansion) before synthesis. Defaults to False.

​
aclose

Release any resources held by the provider.

​
emit

Emit an event, invoking all registered handlers with the given arguments. Handlers are called in registration order. Coroutine handlers are scheduled on the running event loop. If the emitter is closed, the call is a no-op.
​
event
T
required
The event to emit.

​
interrupt

Interrupt and cancel the current synthesis for the active session, if any.

​
off

Remove a previously registered handler for an event. If the handler is not registered for the event, the call is a no-op.
​
event
T
required
The event the handler was registered for.
​
callback
Callable[..., Any]
required
The handler to remove.

​
on

Register a handler for an event. Can be used directly by passing a callback, or as a decorator when callback is omitted.
​
event
T
required
The event to listen for.
​
callback
Callable[..., Any] | None
The handler to invoke when the event is emitted. If None, a decorator is returned that registers the decorated function.
​
returns
Callable[..., Any]
The registered callback when callback is provided, otherwise a decorator that registers and returns the function it wraps.

​
on_first_audio_byte

Register the callback invoked when the first audio byte is produced.
​
callback
'Callable[[int, int], Awaitable[None] | None]'
required
A callable, optionally async, invoked with synthesis timing information when the first audio byte is emitted.

​
synthesize

Synthesize the given text into speech. Implementations should convert the text to audio. The default behavior forwards the text to the active session for playback when one is present.
​
text
Any
required
The text to synthesize; coerced to a string if needed.

​
SarvamAITTSModel