# `vllm_mlx.audio.stt`

Speech-to-Text (STT) engine using mlx-audio.

[View the complete module source at #L1-L160](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L1-L160).

## API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

::: vllm_mlx.audio.stt
    options:
      members:
        - logger
        - DEFAULT_WHISPER_MODEL
        - DEFAULT_PARAKEET_MODEL
        - TranscriptionResult
        - STTEngine
        - transcribe_audio
      filters: []
      show_if_no_docstring: true

## Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

<details class="api-contract" id="contract-vllm_mlx.audio.stt.TranscriptionResult" markdown="1">
<summary><code>vllm_mlx.audio.stt.TranscriptionResult</code> · class</summary>

```python
vllm_mlx.audio.stt.TranscriptionResult(text: str, language: Optional[str] = None, duration: Optional[float] = None, segments: Optional[list] = None)
```

Result from audio transcription.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | `str` | `yes` | `none` | Required constructor field. |
| `language` | `Optional[str]` | `no` | `None` | Optional constructor field; defaults to `None`. |
| `duration` | `Optional[float]` | `no` | `None` | Optional constructor field; defaults to `None`. |
| `segments` | `Optional[list]` | `no` | `None` | Optional constructor field; defaults to `None`. |

**Returns**

- Constructs: `vllm_mlx.audio.stt.TranscriptionResult`

**Exceptions and behavior**

Class `TranscriptionResult` declares 0 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L23-L29](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L23-L29).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.stt.STTEngine" markdown="1">
<summary><code>vllm_mlx.audio.stt.STTEngine</code> · class</summary>

```python
vllm_mlx.audio.stt.STTEngine(model_name: str = DEFAULT_WHISPER_MODEL)
```

Speech-to-Text engine supporting Whisper and Parakeet models.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `no` | `DEFAULT_WHISPER_MODEL` | HuggingFace model name. Supported: - mlx-community/whisper-large-v3-mlx (multilingual) - mlx-community/whisper-large-v3-turbo (fast) - mlx-community/whisper-medium-mlx - mlx-community/whisper-small-mlx - mlx-community/parakeet-tdt-0.6b-v2 (English, fastest) - mlx-community/parakeet-tdt-0.6b-v3 |

**Returns**

- Constructs: `vllm_mlx.audio.stt.STTEngine`

**Exceptions and behavior**

Class `STTEngine` declares 4 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L32-L139](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L32-L139).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.stt.STTEngine.__init__" markdown="1">
<summary><code>vllm_mlx.audio.stt.STTEngine.__init__</code> · method</summary>

```python
vllm_mlx.audio.stt.STTEngine.__init__(model_name: str = DEFAULT_WHISPER_MODEL) -> not annotated
```

Initialize STT engine.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `no` | `DEFAULT_WHISPER_MODEL` | HuggingFace model name. Supported: - mlx-community/whisper-large-v3-mlx (multilingual) - mlx-community/whisper-large-v3-turbo (fast) - mlx-community/whisper-medium-mlx - mlx-community/whisper-small-mlx - mlx-community/parakeet-tdt-0.6b-v2 (English, fastest) - mlx-community/parakeet-tdt-0.6b-v3 |

**Returns**

- Type: `not annotated`

**Exceptions and behavior**

Method `STTEngine.__init__` updates `self.model_name`, `self.model`, `self._loaded`, `self._is_parakeet`; calls `model_name.lower`.
No direct `raise` statement appears in this definition.

[View source #L43-L62](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L43-L62).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.stt.STTEngine.load" markdown="1">
<summary><code>vllm_mlx.audio.stt.STTEngine.load</code> · method</summary>

```python
vllm_mlx.audio.stt.STTEngine.load() -> None
```

Load the STT model.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`
- Direct return expressions: `None`

**Exceptions and behavior**

Method `STTEngine.load` updates `self.model`, `self._loaded`; calls `load_model`, `logger.info`, `logger.error`, `ImportError`; can raise `ImportError`; returns `None`.
Directly raised exceptions: `ImportError`.

[View source #L64-L79](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L64-L79).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.stt.STTEngine.transcribe" markdown="1">
<summary><code>vllm_mlx.audio.stt.STTEngine.transcribe</code> · method</summary>

```python
vllm_mlx.audio.stt.STTEngine.transcribe(audio_path: Union[str, Path], language: Optional[str] = None, task: str = 'transcribe') -> TranscriptionResult
```

Transcribe audio file to text.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `audio_path` | `Union[str, Path]` | `yes` | `none` | Path to audio file (mp3, wav, m4a, etc.) |
| `language` | `Optional[str]` | `no` | `None` | Language code (e.g., "en", "es"). Auto-detected if None. |
| `task` | `str` | `no` | `'transcribe'` | "transcribe" or "translate" (translate to English) |

**Returns**

- Type: `TranscriptionResult`
- Direct return expressions: `TranscriptionResult(text=text.strip() if isinstance(text, str) else str(text), language=detected_lang, duration=duratio…`

**Exceptions and behavior**

Method `STTEngine.transcribe` calls `self.load`, `str`, `self.model.generate`, `getattr`; returns `TranscriptionResult(text=text.strip() if isinstance(text, str) else str(text), language=detected_lang, duration=duratio…`.
No direct `raise` statement appears in this definition.

[View source #L81-L133](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L81-L133).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.stt.STTEngine.unload" markdown="1">
<summary><code>vllm_mlx.audio.stt.STTEngine.unload</code> · method</summary>

```python
vllm_mlx.audio.stt.STTEngine.unload() -> None
```

Unload model to free memory.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `STTEngine.unload` updates `self.model`, `self._loaded`; calls `logger.info`.
No direct `raise` statement appears in this definition.

[View source #L135-L139](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L135-L139).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.stt.transcribe_audio" markdown="1">
<summary><code>vllm_mlx.audio.stt.transcribe_audio</code> · function</summary>

```python
vllm_mlx.audio.stt.transcribe_audio(audio_path: Union[str, Path], model_name: str = DEFAULT_WHISPER_MODEL, language: Optional[str] = None) -> TranscriptionResult
```

Convenience function to transcribe audio without managing engine.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `audio_path` | `Union[str, Path]` | `yes` | `none` | Path to audio file |
| `model_name` | `str` | `no` | `DEFAULT_WHISPER_MODEL` | Model to use |
| `language` | `Optional[str]` | `no` | `None` | Language code (optional) |

**Returns**

- Type: `TranscriptionResult`
- Direct return expressions: `engine.transcribe(audio_path, language=language)`

**Exceptions and behavior**

Function `transcribe_audio` calls `STTEngine`, `engine.load`, `engine.transcribe`; returns `engine.transcribe(audio_path, language=language)`.
No direct `raise` statement appears in this definition.

[View source #L142-L160](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L142-L160).

</details>

## Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

| Symbol | Kind | Signature and inputs | What it does | Source |
| --- | --- | --- | --- | --- |
| [`TranscriptionResult`](#contract-vllm_mlx.audio.stt.TranscriptionResult) | class | `TranscriptionResult(text: str, language: Optional[str] = None, duration: Optional[float] = None, segments: Optional[list] = None)` | Result from audio transcription. | [#L23-L29](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L23-L29) |
| [`STTEngine`](#contract-vllm_mlx.audio.stt.STTEngine) | class | `STTEngine(model_name: str = DEFAULT_WHISPER_MODEL)` | Speech-to-Text engine supporting Whisper and Parakeet models. | [#L32-L139](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L32-L139) |
| [`STTEngine.__init__`](#contract-vllm_mlx.audio.stt.STTEngine.__init__) | method | `STTEngine.__init__(model_name: str = DEFAULT_WHISPER_MODEL) -> not annotated` | Initialize STT engine. | [#L43-L62](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L43-L62) |
| [`STTEngine.load`](#contract-vllm_mlx.audio.stt.STTEngine.load) | method | `STTEngine.load() -> None` | Load the STT model. | [#L64-L79](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L64-L79) |
| [`STTEngine.transcribe`](#contract-vllm_mlx.audio.stt.STTEngine.transcribe) | method | `STTEngine.transcribe(audio_path: Union[str, Path], language: Optional[str] = None, task: str = 'transcribe') -> TranscriptionResult` | Transcribe audio file to text. | [#L81-L133](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L81-L133) |
| [`STTEngine.unload`](#contract-vllm_mlx.audio.stt.STTEngine.unload) | method | `STTEngine.unload() -> None` | Unload model to free memory. | [#L135-L139](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L135-L139) |
| [`transcribe_audio`](#contract-vllm_mlx.audio.stt.transcribe_audio) | function | `transcribe_audio(audio_path: Union[str, Path], model_name: str = DEFAULT_WHISPER_MODEL, language: Optional[str] = None) -> TranscriptionResult` | Convenience function to transcribe audio without managing engine. | [#L142-L160](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/stt.py#L142-L160) |