Skip to main content

Usage guide

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

โ€‹
AssemblyAISTT

AssemblyAI real-time streaming speech-to-text via WebSocket. Uses the AssemblyAI Streaming Speech-to-Text API (WebSocket) with built-in end-of-turn detection, key-term boosting, and optional automatic language detection.

โ€‹
Constructor

โ€‹
api_key
str | None
AssemblyAI API key. Falls back to the ASSEMBLYAI_API_KEY environment variable when omitted.
โ€‹
speech_model
AssemblyAISTTModel | str
default:"universal-streaming-english"
Streaming model to use. Defaults to "universal-streaming-english" (English-only, lowest latency). Use "universal-streaming" for multilingual recognition across English, Spanish, German, French, Portuguese, and Italian. Accepts any AssemblyAISTTModel enum value or a raw string.
โ€‹
language
str
default:"en-US"
BCP-47 language code for transcription, e.g. "en-US", "fr"ใ€"de". Only relevant when language_detection is False. Defaults to "en-US".
โ€‹
input_sample_rate
int
default:"48000"
Sample rate (Hz) of the incoming audio. Must match the actual capture rate, typically 48000. Defaults to 48000.
โ€‹
output_sample_rate
int
default:"16000"
Sample rate (Hz) used when sending audio to AssemblyAI. The audio is resampled from input_sample_rate to this value before transmission. AssemblyAI accepts 8000โ€“48000 Hz. Defaults to 16000.
โ€‹
encoding
str
default:"pcm_s16le"
PCM encoding format of the audio stream. Must be "pcm_s16le" (16-bit signed little-endian, the AssemblyAI default) or "pcm_mulaw" (8-bit ยต-law). Defaults to "pcm_s16le".
โ€‹
format_turns
bool
default:"True"
When True (default), AssemblyAI returns punctuated, cased transcript segments aligned to speaker turns rather than raw word-level partials.
โ€‹
end_of_turn_confidence_threshold
float
default:"0.4"
Confidence score [0.0, 1.0] above which the model considers a pause as an end-of-turn event. Lower values trigger turns sooner. Defaults to 0.4.
โ€‹
min_end_of_turn_silence_when_confident
int
default:"560"
Minimum silence duration (ms) required to confirm an end-of-turn when confidence exceeds the threshold. Defaults to 560 ms.
โ€‹
max_turn_silence
int
default:"2400"
Maximum silence (ms) before a turn is force-ended regardless of confidence. Defaults to 2400 ms.
โ€‹
keyterms_prompt
Optional[List[str]]
List of domain-specific words or phrases to boost recognition accuracy (e.g. ["Cartesia", "Deepgram"]). Defaults to None (empty list, no boosting).
โ€‹
language_detection
bool
default:"False"
When True, AssemblyAI automatically detects the spoken language per utterance and returns language metadata. Only supported by the multilingual "universal-streaming" model. Overrides language. Defaults to False.
โ€‹
base_url
str | None
Override the AssemblyAI WebSocket endpoint URL. Useful for proxies or self-hosted deployments. Defaults to None (uses the AssemblyAI production endpoint).

โ€‹
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.

โ€‹
AssemblyAISTTModel