> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure

> Python API reference for the azure speech-to-text plugin.

<Card title="Usage guide" icon="book" href="/plugins/stt/azure" horizontal>
  Setup, environment variables, and Python/JavaScript/Go usage examples.
</Card>

## 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

```python theme={null}
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'
```

<ParamField path="speech_key" type="Optional[str]">
  Azure Speech resource subscription key.  Falls back to the `AZURE_SPEECH_KEY` environment variable when omitted.
</ParamField>

<ParamField path="speech_region" type="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.
</ParamField>

<ParamField path="language" type="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.
</ParamField>

<ParamField path="sample_rate" type="int" default="16000">
  PCM input sample rate in Hz sent to Azure. Defaults to `16000`.
</ParamField>

<ParamField path="enable_phrase_list" type="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`.
</ParamField>

<ParamField path="phrase_list" type="Optional[List[str]]">
  List of words or phrases (strings) to use as recognition hints when `enable_phrase_list` is `True`. Defaults to `None`.
</ParamField>

### aclose

```python theme={null}
def aclose(self) -> 'None'
```

Release any resources held by the provider.

### emit

```python theme={null}
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.

<ParamField path="event" type="T" required>
  The event to emit.
</ParamField>

### off

```python theme={null}
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.

<ParamField path="event" type="T" required>
  The event the handler was registered for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any]" required>
  The handler to remove.
</ParamField>

### on

```python theme={null}
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.

<ParamField path="event" type="T" required>
  The event to listen for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any] | None">
  The handler to invoke when the event is emitted. If `None`, a decorator is returned that registers the decorated function.
</ParamField>

<ResponseField name="returns" type="Callable[..., Any]">
  The registered callback when `callback` is provided, otherwise a decorator that registers and returns the function it wraps.
</ResponseField>

### on\_stt\_transcript

```python theme={null}
def on_stt_transcript(self, callback: 'Callable[[STTResponse], Awaitable[None]]') -> 'None'
```

Register the coroutine invoked when a transcription event is produced.

<ParamField path="callback" type="Callable[[STTResponse], Awaitable[None]]" required>
  An async callable that receives each `STTResponse`.
</ParamField>

### process\_audio

```python theme={null}
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.

<ParamField path="audio_frames" type="bytes" required>
  Raw audio bytes to transcribe.
</ParamField>

<ParamField path="language" type="Optional[str]">
  Optional language code to guide recognition.
</ParamField>

### stream\_transcribe

```python theme={null}
def stream_transcribe(self, audio_stream: 'AsyncIterator[bytes]', **kwargs: 'Any') -> 'AsyncIterator[STTResponse]'
```

Transcribe a continuous audio stream.

<ParamField path="audio_stream" type="AsyncIterator[bytes]" required>
  An async iterator yielding raw audio byte chunks.
</ParamField>

<ResponseField name="returns" type="AsyncIterator[STTResponse]">
  STTResponse: Transcription events produced as audio is consumed.
</ResponseField>

***

## 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

```python theme={null}
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'
```

<ParamField path="api_key" type="Optional[str]">
  Azure OpenAI API key. Falls back to `AZURE_API_KEY` then `AZURE_OPENAI_API_KEY` environment variables when omitted.
</ParamField>

<ParamField path="azure_endpoint" type="Optional[str]">
  Full Azure OpenAI resource endpoint URL, e.g. `"https://&lt;resource>.openai.azure.com/"`. Falls back to the `AZURE_OPENAI_ENDPOINT` environment variable when omitted.
</ParamField>

<ParamField path="deployment" type="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`.
</ParamField>

<ParamField path="api_version" type="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.
</ParamField>

<ParamField path="model" type="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 `""`.
</ParamField>

<ParamField path="language" type="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"`.
</ParamField>

<ParamField path="stream" type="bool" default="False">
  When `True`, receive transcription results as a streaming response. When `False` (default), the full transcript is returned in a single response.
</ParamField>

<ParamField path="input_sample_rate" type="int" default="48000">
  Sample rate (Hz) of the incoming audio, typically `48000`. Defaults to `48000`.
</ParamField>

<ParamField path="output_sample_rate" type="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`.
</ParamField>

<ParamField path="prompt" type="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`.
</ParamField>

<ParamField path="temperature" type="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`).
</ParamField>

<ParamField path="response_format" type="str" default="json">
  Format of the transcription response. One of: \* `"json"` (default): `&#123;"text": "..."&#125;` \* `"verbose_json"`: full object with `text`, `language`, `duration`, and `segments` \* `"text"`: plain string \* `"srt"`: SubRip subtitle format \* `"vtt"`: WebVTT subtitle format
</ParamField>

<ParamField path="turn_detection" type="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).
</ParamField>

### aclose

```python theme={null}
def aclose(self) -> 'None'
```

Release any resources held by the provider.

### emit

```python theme={null}
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.

<ParamField path="event" type="T" required>
  The event to emit.
</ParamField>

### off

```python theme={null}
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.

<ParamField path="event" type="T" required>
  The event the handler was registered for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any]" required>
  The handler to remove.
</ParamField>

### on

```python theme={null}
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.

<ParamField path="event" type="T" required>
  The event to listen for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any] | None">
  The handler to invoke when the event is emitted. If `None`, a decorator is returned that registers the decorated function.
</ParamField>

<ResponseField name="returns" type="Callable[..., Any]">
  The registered callback when `callback` is provided, otherwise a decorator that registers and returns the function it wraps.
</ResponseField>

### on\_stt\_transcript

```python theme={null}
def on_stt_transcript(self, callback: 'Callable[[STTResponse], Awaitable[None]]') -> 'None'
```

Register the coroutine invoked when a transcription event is produced.

<ParamField path="callback" type="Callable[[STTResponse], Awaitable[None]]" required>
  An async callable that receives each `STTResponse`.
</ParamField>

### process\_audio

```python theme={null}
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.

<ParamField path="audio_frames" type="bytes" required>
  Raw audio bytes to transcribe.
</ParamField>

<ParamField path="language" type="Optional[str]">
  Optional language code to guide recognition.
</ParamField>

### stream\_transcribe

```python theme={null}
def stream_transcribe(self, audio_stream: 'AsyncIterator[bytes]', **kwargs: 'Any') -> 'AsyncIterator[STTResponse]'
```

Transcribe a continuous audio stream.

<ParamField path="audio_stream" type="AsyncIterator[bytes]" required>
  An async iterator yielding raw audio byte chunks.
</ParamField>

<ResponseField name="returns" type="AsyncIterator[STTResponse]">
  STTResponse: Transcription events produced as audio is consumed.
</ResponseField>

***

## AzureOpenAISTTModel

```python theme={null}
AzureOpenAISTTModel = typing.Literal['gpt-4o-transcribe', 'gpt-4o-mini-transcribe', 'gpt-4o-transcribe-diarize', 'whisper']
```