Skip to main content

Usage guide

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

​
DeepgramSTT

Streaming speech-to-text via Deepgram’s Listen WebSocket API. Real-time transcription with interim results, smart formatting, keyterm/keyword boosting, diarization and redaction. Audio format is fixed at 48 kHz mono linear16, so sample_rate/encoding/channels are accepted for backward compatibility but have no effect.

​
Constructor

​
api_key
str | None
Deepgram API key. Falls back to DEEPGRAM_API_KEY.
​
model
DeepgramSTTModel | str
default:"nova-2"
Recognition model: nova-3 family (nova-3, nova-3-general, nova-3-medical), nova-2 family (nova-2, nova-2-phonecall, nova-2-meeting, nova-2-medical, nova-2-finance, nova-2-drivethru, …) or flux-general-en/flux-general-multi. Default "nova-2".
​
language
str
default:"en-US"
BCP-47 language tag (e.g. "en-US"). Default "en-US".
​
interim_results
bool
default:"True"
Emit partial hypotheses while the caller speaks. Default True.
​
punctuate
bool
default:"True"
Add punctuation to the transcript. Default True.
​
smart_format
bool
default:"True"
Apply date/number/currency formatting. Default True.
​
sample_rate
int
default:"48000"
Input rate in Hz. Fixed at 48000; ignored.
​
endpointing
int
default:"50"
Silence in ms before a finalized transcript is emitted. Default 50.
​
filler_words
bool
default:"True"
Keep “uh”/“um” fillers in the transcript. Default True.
​
keywords
list[str] | None
Legacy term-boost list (nova-2). Use keyterm on nova-3.
​
keyterm
list[str] | None
Keyterm-prompting list to boost domain vocabulary (nova-3).
​
profanity_filter
bool
default:"False"
Mask profanity. Default False.
​
numerals
bool
default:"False"
Convert spoken numbers to digits. Default False.
​
tag
Union[str, List[str]] | None
Request tag(s) attached for Deepgram usage reporting.
​
enable_diarization
bool
default:"False"
Label speakers in the transcript. Default False.
​
redact
Union[str, List[str]] | None
Entity type(s) to redact (e.g. "pci", "numbers").
​
base_url
str
default:"wss://api.deepgram.com/v1/listen"
Deepgram Listen WebSocket 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.

​
DeepgramSTTModel