Skip to main content

Usage guide

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

​
SmallestAITTS

Smallest AI Lightning TTS plugin for ultra-low-latency speech synthesis. Uses Smallest AI’s Lightning v3.1 model (optimised for real-time voice agents) to stream synthesised audio with minimal time-to-first-byte. Supports 12 languages and a large catalogue of pre-built voices.

​
Constructor

​
api_key
str | None
Smallest AI API key. Falls back to the SMALLESTAI_API_KEY environment variable when None.
​
voice
Optional[str]
Voice name to use for synthesis (e.g. 'magnus', 'lauren', 'meher', 'devansh'). Takes precedence over voice_id when both are provided. Defaults to 'magnus' when neither argument is given.
​
voice_id
Optional[str]
Alias for voice; provided for API-compatibility. Ignored when voice is also set.
​
model
SmallestAITTSModel | str
default:"lightning_v3.1"
Smallest AI model ID. Defaults to 'lightning_v3.1'. 'lightning_v3.1_pro' is the premium variant with a different per-language voice catalogue.
​
sample_rate
int
default:"24000"
Output audio sample rate in Hz. Defaults to 24000. Supported values: 8000, 16000, 24000, 44100.
​
language
str
default:"en"
ISO 639-1 language code for the target voice. Defaults to 'en'. Supported values: 'en', 'hi', 'mr', 'kn', 'ta', 'bn', 'gu', 'te', 'ml', 'pa', 'or', 'es'.
​
speed
Optional[float]
Speaking rate multiplier relative to the voice default. 1.0 is normal speed; None (default) uses the model default.
​
stream
bool
default:"True"
When True (default), audio is returned as a stream of chunks for lower latency. Set to False for a single synchronous response.

​
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.

​
SmallestAITTSModel