Skip to main content

Usage guide

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

​
GoogleSTT

Google Cloud Speech-to-Text V2 plugin with streaming support. Uses Google Cloud Speech-to-Text V2 recognition models (latest_long by default, plus the Chirp family). Supports live streaming, speaker diarization, word-level timing, and per-utterance voice-activity events.

​
Constructor

​
credentials_json
Optional[str]
Service-account credentials as a raw JSON string or a path to a JSON key file. Takes highest precedence for authentication.
​
service_account_path
Optional[str]
Path to a service-account JSON key file. Used when credentials_json is not provided.
​
api_key
Optional[str]
Google API key. Used as a fallback credential source if the above are absent; the value is treated as a JSON file path first. For STT, service-account auth is recommended over API keys.
​
project_id
Optional[str]
Google Cloud project ID. Extracted automatically from the service-account JSON when not provided explicitly.
​
stream
bool
default:"True"
When True (default), audio is transcribed over a low-latency streaming connection. When False, a single-request (batch) call is used.
​
location
str
default:"us"
Cloud Speech-to-Text regional endpoint. "us" (default) or "eu".
​
languages
Union[str, list[str]]
default:"en-US"
BCP-47 language code(s) for recognition, e.g. "en-US" (default) or ["en-US", "fr-FR"]. Multiple codes enable multi-language detection.
​
model
GoogleSTTModel | str
default:"latest_long"
Recognition model ID. Known values (GoogleSTTModel): "latest_long" (default), "latest_short", "chirp_3", "chirp_2", "telephony", "telephony_short".
​
sample_rate
int
default:"48000"
Input audio sample rate in Hz. Default: 48000.
​
audio_channel_count
int
default:"1"
Number of audio channels in the input. Default: 1 (mono).
​
interim_results
bool
default:"True"
When True (default), partial transcripts are emitted before an utterance is finalised.
​
punctuate
bool
default:"True"
When True (default), automatic punctuation is added to transcripts.
​
profanity_filter
bool
default:"False"
When True, profane words are replaced with placeholder characters. Default: False.
​
enable_spoken_punctuation
bool
default:"False"
When True, spoken punctuation cues (e.g. “period”) are transcribed as punctuation marks. Default: False.
​
enable_spoken_emojis
bool
default:"False"
When True, spoken emoji names are transcribed as emoji characters. Default: False.
​
enable_word_time_offsets
bool
default:"False"
When True, start and end timestamps are returned for each recognised word. Default: False.
​
enable_word_confidence
bool
default:"False"
When True, per-word confidence scores are included in results. Default: False.
​
max_alternatives
int
default:"1"
Maximum number of alternative transcriptions to return. Default: 1.
​
enable_voice_activity_events
bool
default:"False"
When True, speech-start and speech-end events are emitted independently of transcripts. Default: False.
​
speech_start_timeout
Optional[float]
Seconds to wait for speech to begin before a voice-activity timeout is triggered. None uses the API default.
​
speech_end_timeout
Optional[float]
Seconds of silence after speech before an end-of-speech voice-activity event is fired. None uses the API default.
​
min_speaker_count
Optional[int]
Minimum expected number of speakers for diarization. None disables diarization.
​
max_speaker_count
Optional[int]
Maximum expected number of speakers for diarization. None disables diarization.
​
min_confidence_threshold
float
default:"0.0"
Client-side filter; transcripts with a confidence score below this value are discarded. Range 0.0–1.0. Default: 0.0 (no filtering).

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

​
GoogleSTTModel