Skip to main content

Usage guide

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

​
OpenAISTT

Streaming speech-to-text via OpenAI’s transcription API. Uses the gpt-4o-transcribe family (or whisper-1) with server-side VAD turn detection and optional input noise reduction.

​
Constructor

​
api_key
Optional[str]
OpenAI API key. Falls back to OPENAI_API_KEY.
​
model
OpenAISTTModel | str
default:"gpt-4o-transcribe"
Transcription model: gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize or whisper-1. Default "gpt-4o-transcribe".
​
language
str
default:"en"
ISO-639-1 language code (e.g. "en"). Default "en".
​
stream
bool
default:"True"
Stream partial transcripts as the caller speaks. Default True.
​
input_sample_rate
int
default:"48000"
Input rate in Hz. Default 48000.
​
output_sample_rate
int
default:"24000"
Resampled rate sent to the model in Hz. Default 24000.
​
prompt
Optional[str]
Optional text prompt to bias vocabulary/style.
​
turn_detection
str
default:"server_vad"
VAD mode: "server_vad" or "semantic_vad". Default "server_vad".
​
vad_threshold
Optional[float]
Speech-detection sensitivity, 0.0–1.0. Default None.
​
vad_prefix_padding_ms
Optional[int]
Audio kept before detected speech, in ms. Default None.
​
vad_silence_duration_ms
Optional[int]
Silence before end-of-turn, in ms. Default None.
​
noise_reduction
Optional[str]
default:"near_field"
Input denoising profile: "near_field", "far_field" or None to disable. Default "near_field".
​
response_format
str
default:"json"
Transcript format ("json", "text", …). Default "json".
​
base_url
Optional[str]
Override the OpenAI API base URL.

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

​
OpenAISTTModel