Skip to main content

Usage guide

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

​
GladiaSTT

Gladia real-time speech-to-text via WebSocket streaming. Wraps the Gladia Live Speech Recognition API (v2) using the solaria-1 model, which supports 90+ languages with optional per-utterance language detection (code-switching).

​
Constructor

​
api_key
str | None
Gladia API key. Falls back to the GLADIA_API_KEY environment variable when None.
​
model
str
default:"solaria-1"
Gladia recognition model. "solaria-1" is the only production model and the default.
​
languages
List[str] | None
ISO 639-1 language codes to hint at (e.g. ["en", "fr"]). Only the first element is used. When None the default is "english".
​
code_switching
bool
default:"True"
When True, language is re-detected on every utterance. When False, language is detected once on the first utterance and held for the session. Default: True.
​
input_sample_rate
int
default:"48000"
Sample rate (Hz) of the incoming audio before any resampling. Valid values: 8000, 16000, 32000, 44100, 48000. Default: 48000.
​
output_sample_rate
int
default:"16000"
Sample rate (Hz) forwarded to the Gladia WebSocket session. Default: 16000.
​
encoding
str
default:"wav/pcm"
PCM encoding format sent over the WebSocket. Valid values: "wav/pcm" (default), "wav/alaw", "wav/ulaw".
​
bit_depth
int
default:"16"
Bit depth of the PCM samples. Valid values: 8, 16 (default), 24, 32.
​
channels
int
default:"1"
Number of audio channels (1–8). Default: 1 (mono).
​
receive_partial_transcripts
bool
default:"False"
When True, partial (non-final) transcripts are emitted over the WebSocket before the utterance is complete. Default: 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.

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

Register the coroutine invoked when a transcription event is produced.
​
callback
Callable[[STTResponse], Awaitable[None]]
required
An async callable that receives each STTResponse.

​
process_audio

Process a chunk of audio for transcription. Implementations should consume the audio frames and emit transcription results through the registered transcript callback.
​
audio_frames
bytes
required
Raw audio bytes to transcribe.
​
language
Optional[str]
Optional language code to guide recognition.

​
stream_transcribe

Transcribe a continuous audio stream.
​
audio_stream
AsyncIterator[bytes]
required
An async iterator yielding raw audio byte chunks.
​
returns
AsyncIterator[STTResponse]
STTResponse: Transcription events produced as audio is consumed.