Azure

Usage guide

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

AzureSTT

Azure Cognitive Services Speech-to-Text provider. Streams audio to Azure Speech SDK for real-time transcription. Supports 100+ BCP-47 languages and optional phrase-list hints for domain-specific vocabulary boosting.

Constructor

AzureSTT(*, speech_key: 'Optional[str]' = None, speech_region: 'Optional[str]' = None, language: 'str' = 'en-US', sample_rate: 'int' = 16000, enable_phrase_list: 'bool' = False, phrase_list: 'Optional[List[str]]' = None, **kwargs: 'Any') -> 'None'

speech_key

Optional[str]

Azure Speech resource subscription key. Falls back to the AZURE_SPEECH_KEY environment variable when omitted.

speech_region

Optional[str]

Azure region identifier for the Speech resource (e.g. "eastus", "westeurope", "southeastasia"). Falls back to the AZURE_REGION environment variable, then "eastus" as a hard default. Must match the region where your Azure Speech resource was created. Keys are region-scoped.

language

str

default:"en-US"

BCP-47 locale tag for the spoken language. Defaults to "en-US". Examples: "fr-FR", "de-DE", "zh-CN", "ja-JP", "pt-BR". Over 100 locales are supported; see the Azure Speech language-support docs for the full list.

sample_rate

int

default:"16000"

PCM input sample rate in Hz sent to Azure. Defaults to 16000.

enable_phrase_list

bool

default:"False"

When True, the phrases supplied in phrase_list are registered as recognition hints to improve accuracy for domain-specific terms. Defaults to False.

phrase_list

Optional[List[str]]

List of words or phrases (strings) to use as recognition hints when enable_phrase_list is True. Defaults to None.

aclose

def aclose(self) -> 'None'

Release any resources held by the provider.

emit

def emit(self, event: 'T', *args: 'Any') -> 'None'

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

required

The event to emit.

off

def off(self, event: 'T', callback: 'Callable[..., Any]') -> 'None'

Remove a previously registered handler for an event. If the handler is not registered for the event, the call is a no-op.

event

required

The event the handler was registered for.

callback

Callable[..., Any]

required

The handler to remove.

on

def on(self, event: 'T', callback: 'Callable[..., Any] | None' = None) -> 'Callable[..., Any]'

Register a handler for an event. Can be used directly by passing a callback, or as a decorator when callback is omitted.

event

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

def on_stt_transcript(self, callback: 'Callable[[STTResponse], Awaitable[None]]') -> 'None'

callback

Callable[[STTResponse], Awaitable[None]]

required

An async callable that receives each STTResponse.

process_audio

def process_audio(self, audio_frames: 'bytes', language: 'Optional[str]' = None, **kwargs: 'Any') -> 'None'

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

def stream_transcribe(self, audio_stream: 'AsyncIterator[bytes]', **kwargs: 'Any') -> 'AsyncIterator[STTResponse]'

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.

AzureOpenAISTT

Azure OpenAI Whisper STT plugin. Transcribes audio via an Azure-hosted Whisper deployment, supporting optional streaming mode, ISO-639-1 language hints, and multiple output formats (JSON, VTT, SRT, plain text).

Constructor

AzureOpenAISTT(*, api_key: 'Optional[str]' = None, azure_endpoint: 'Optional[str]' = None, deployment: 'AzureOpenAISTTModel | str | None' = None, api_version: 'str' = '2025-03-01-preview', model: 'str' = '', language: 'str' = 'en', stream: 'bool' = False, input_sample_rate: 'int' = 48000, output_sample_rate: 'int' = 24000, prompt: 'Optional[str]' = None, temperature: 'Optional[float]' = None, response_format: 'str' = 'json', turn_detection: 'str' = 'server_vad', **kwargs: 'Any') -> 'None'

api_key

Optional[str]

Azure OpenAI API key. Falls back to AZURE_API_KEY then AZURE_OPENAI_API_KEY environment variables when omitted.

azure_endpoint

Optional[str]

Full Azure OpenAI resource endpoint URL, e.g. "https://<resource>.openai.azure.com/". Falls back to the AZURE_OPENAI_ENDPOINT environment variable when omitted.

deployment

AzureOpenAISTTModel | str | None

Name of the Azure OpenAI deployment for the Whisper model. This is the custom name you chose when deploying the model in Azure portal or AI Foundry (not necessarily the same as the model name). Falls back to the AZURE_OPENAI_STT_DEPLOYMENT environment variable. Accepts any AzureOpenAISTTModel enum value or a raw string. Defaults to None.

api_version

str

default:"2025-03-01-preview"

Azure OpenAI REST API version string. Defaults to "2025-03-01-preview". Use "2024-10-21" for the GA stable audio transcription release.

model

str

default:""

Underlying model name passed in the request body, e.g. "whisper-1". When a deployment name is already set, this field is typically left empty. Defaults to "".

language

str

default:"en"

ISO-639-1 language code of the spoken audio, e.g. "en", "fr", "de". Supplying the correct language improves transcription accuracy and reduces latency. Defaults to "en".

stream

bool

default:"False"

When True, receive transcription results as a streaming response. When False (default), the full transcript is returned in a single response.

input_sample_rate

int

default:"48000"

Sample rate (Hz) of the incoming audio, typically 48000. Defaults to 48000.

output_sample_rate

int

default:"24000"

Sample rate (Hz) used when forwarding audio to the Azure Whisper endpoint. Audio is resampled from input_sample_rate to this value before transmission. Defaults to 24000.

prompt

Optional[str]

Optional text to guide the model’s transcription style or to continue context from a previous audio segment. Should be in the same language as the audio. Defaults to None.

temperature

Optional[float]

Sampling temperature in [0.0, 1.0] controlling transcription randomness. 0 makes sampling deterministic; the model auto-increases temperature if needed. Defaults to None (provider default of 0).

response_format

str

default:"json"

Format of the transcription response. One of: * "json" (default): {"text": "..."} * "verbose_json": full object with text, language, duration, and segments * "text": plain string * "srt": SubRip subtitle format * "vtt": WebVTT subtitle format

turn_detection

str

default:"server_vad"

Turn-detection strategy for streaming mode. One of "server_vad" (default, server-side voice activity detection) or "none" (no automatic turn detection).

aclose

def aclose(self) -> 'None'

Release any resources held by the provider.

emit

def emit(self, event: 'T', *args: 'Any') -> 'None'

event

required

The event to emit.

off

def off(self, event: 'T', callback: 'Callable[..., Any]') -> 'None'

Remove a previously registered handler for an event. If the handler is not registered for the event, the call is a no-op.

event

required

The event the handler was registered for.

callback

Callable[..., Any]

required

The handler to remove.

on

def on(self, event: 'T', callback: 'Callable[..., Any] | None' = None) -> 'Callable[..., Any]'

Register a handler for an event. Can be used directly by passing a callback, or as a decorator when callback is omitted.

event

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

def on_stt_transcript(self, callback: 'Callable[[STTResponse], Awaitable[None]]') -> 'None'

callback

Callable[[STTResponse], Awaitable[None]]

required

An async callable that receives each STTResponse.

process_audio

def process_audio(self, audio_frames: 'bytes', language: 'Optional[str]' = None, **kwargs: 'Any') -> 'None'

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

def stream_transcribe(self, audio_stream: 'AsyncIterator[bytes]', **kwargs: 'Any') -> 'AsyncIterator[STTResponse]'

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.

AzureOpenAISTTModel

AzureOpenAISTTModel = typing.Literal['gpt-4o-transcribe', 'gpt-4o-mini-transcribe', 'gpt-4o-transcribe-diarize', 'whisper']

Python SDK

Core

Speech-to-text

LLM

Text-to-speech

Realtime models

Avatars

Turn detection

Voice activity detection

Noise cancellation

Usage guide

AzureSTT

Constructor

aclose

emit

off

on

on_stt_transcript

process_audio

stream_transcribe

AzureOpenAISTT

Constructor

aclose

emit

off

on

on_stt_transcript

process_audio

stream_transcribe

AzureOpenAISTTModel

Usage guide

​AzureSTT

​Constructor

​aclose

​emit

​off

​on

​on_stt_transcript

​process_audio

​stream_transcribe

​AzureOpenAISTT

​Constructor

​aclose

​emit

​off

​on

​on_stt_transcript

​process_audio

​stream_transcribe

​AzureOpenAISTTModel

AzureSTT

Constructor

aclose

emit

off

on

on_stt_transcript

process_audio

stream_transcribe

AzureOpenAISTT

Constructor

aclose

emit

off

on

on_stt_transcript

process_audio

stream_transcribe

AzureOpenAISTTModel