# `vllm_mlx.audio.tts`

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

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

## 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.tts
    options:
      members:
        - logger
        - DEFAULT_TTS_MODEL
        - KOKORO_VOICES
        - CHATTERBOX_VOICES
        - AudioOutput
        - TTSEngine
        - generate_speech
      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.tts.AudioOutput" markdown="1">
<summary><code>vllm_mlx.audio.tts.AudioOutput</code> · class</summary>

```python
vllm_mlx.audio.tts.AudioOutput(audio: np.ndarray, sample_rate: int, duration: float)
```

Output from TTS generation.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `audio` | `np.ndarray` | `yes` | `none` | Required constructor field. |
| `sample_rate` | `int` | `yes` | `none` | Required constructor field. |
| `duration` | `float` | `yes` | `none` | Required constructor field. |

**Returns**

- Constructs: `vllm_mlx.audio.tts.AudioOutput`

**Exceptions and behavior**

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

[View source #L44-L49](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L44-L49).

</details>

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

```python
vllm_mlx.audio.tts.TTSEngine(model_name: str = DEFAULT_TTS_MODEL)
```

Text-to-Speech engine supporting multiple model families.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `no` | `DEFAULT_TTS_MODEL` | HuggingFace model name. Supported families: - Kokoro: mlx-community/Kokoro-82M-bf16, Kokoro-82M-4bit - Chatterbox: mlx-community/chatterbox-turbo-fp16 - VibeVoice: mlx-community/VibeVoice-Realtime-0.5B-4bit - VoxCPM: mlx-community/VoxCPM1.5 |

**Returns**

- Constructs: `vllm_mlx.audio.tts.TTSEngine`

**Exceptions and behavior**

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

[View source #L52-L292](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L52-L292).

</details>

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

```python
vllm_mlx.audio.tts.TTSEngine.__init__(model_name: str = DEFAULT_TTS_MODEL) -> not annotated
```

Initialize TTS engine.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `no` | `DEFAULT_TTS_MODEL` | HuggingFace model name. Supported families: - Kokoro: mlx-community/Kokoro-82M-bf16, Kokoro-82M-4bit - Chatterbox: mlx-community/chatterbox-turbo-fp16 - VibeVoice: mlx-community/VibeVoice-Realtime-0.5B-4bit - VoxCPM: mlx-community/VoxCPM1.5 |

**Returns**

- Type: `not annotated`

**Exceptions and behavior**

Method `TTSEngine.__init__` updates `self.model_name`, `self.model`, `self._loaded`, `self._model_family`; calls `self._detect_family`.
No direct `raise` statement appears in this definition.

[View source #L63-L80](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L63-L80).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.tts.TTSEngine._detect_family" markdown="1">
<summary><code>vllm_mlx.audio.tts.TTSEngine._detect_family</code> · method</summary>

```python
vllm_mlx.audio.tts.TTSEngine._detect_family(model_name: str) -> str
```

Detect model family from name.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `'kokoro'`; `'chatterbox'`; `'vibevoice'`; `'voxcpm'`; `'csm'`; `'cosyvoice'`

**Exceptions and behavior**

Method `TTSEngine._detect_family` calls `model_name.lower`; has 6 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L82-L98](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L82-L98).

</details>

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

```python
vllm_mlx.audio.tts.TTSEngine.load() -> None
```

Load the TTS model.

**Parameters**

This callable has no explicit inputs.

**Returns**

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

**Exceptions and behavior**

Method `TTSEngine.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 #L100-L117](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L100-L117).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.tts.TTSEngine.generate" markdown="1">
<summary><code>vllm_mlx.audio.tts.TTSEngine.generate</code> · method</summary>

```python
vllm_mlx.audio.tts.TTSEngine.generate(text: str, voice: str = 'af_heart', speed: float = 1.0, lang_code: str = 'a') -> AudioOutput
```

Generate speech from text.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | `str` | `yes` | `none` | Text to synthesize |
| `voice` | `str` | `no` | `'af_heart'` | Voice ID (model-specific) |
| `speed` | `float` | `no` | `1.0` | Speech speed (0.5 to 2.0) |
| `lang_code` | `str` | `no` | `'a'` | Language code (a=English, e=Spanish, f=French, etc.) |

**Returns**

- Type: `AudioOutput`
- Direct return expressions: `AudioOutput(audio=full_audio, sample_rate=sample_rate, duration=duration)`

**Exceptions and behavior**

Method `TTSEngine.generate` calls `self.load`, `self.model.generate`, `hasattr`, `isinstance`; can raise `RuntimeError`; returns `AudioOutput(audio=full_audio, sample_rate=sample_rate, duration=duration)`.
Directly raised exceptions: `RuntimeError`.

[View source #L119-L185](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L119-L185).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.tts.TTSEngine.stream_generate" markdown="1">
<summary><code>vllm_mlx.audio.tts.TTSEngine.stream_generate</code> · method</summary>

```python
vllm_mlx.audio.tts.TTSEngine.stream_generate(text: str, voice: str = 'af_heart', speed: float = 1.0) -> Iterator[AudioOutput]
```

Stream speech generation chunk by chunk.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | `str` | `yes` | `none` | Text to synthesize |
| `voice` | `str` | `no` | `'af_heart'` | Voice ID |
| `speed` | `float` | `no` | `1.0` | Speech speed |

**Returns**

- Type: `Iterator[AudioOutput]`
- Yields values incrementally.

**Exceptions and behavior**

Method `TTSEngine.stream_generate` calls `self.load`, `self.model.generate`, `hasattr`, `np.array`; yields values incrementally.
No direct `raise` statement appears in this definition.

[View source #L187-L227](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L187-L227).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.tts.TTSEngine.save" markdown="1">
<summary><code>vllm_mlx.audio.tts.TTSEngine.save</code> · method</summary>

```python
vllm_mlx.audio.tts.TTSEngine.save(audio: AudioOutput, path: Union[str, Path], format: str = 'wav') -> None
```

Save audio to file.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `audio` | `AudioOutput` | `yes` | `none` | AudioOutput to save |
| `path` | `Union[str, Path]` | `yes` | `none` | Output file path |
| `format` | `str` | `no` | `'wav'` | Output format (wav, mp3) |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `TTSEngine.save` calls `save_audio`, `str`, `logger.info`, `(audio.audio * 32767).astype`.
No direct `raise` statement appears in this definition.

[View source #L229-L255](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L229-L255).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.tts.TTSEngine.to_bytes" markdown="1">
<summary><code>vllm_mlx.audio.tts.TTSEngine.to_bytes</code> · method</summary>

```python
vllm_mlx.audio.tts.TTSEngine.to_bytes(audio: AudioOutput, format: str = 'wav') -> bytes
```

Convert audio to bytes.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `audio` | `AudioOutput` | `yes` | `none` | AudioOutput to convert |
| `format` | `str` | `no` | `'wav'` | Output format (wav, mp3) |

**Returns**

- Type: `bytes`
- Direct return expressions: `buffer.getvalue()`

**Exceptions and behavior**

Method `TTSEngine.to_bytes` calls `io.BytesIO`, `(audio.audio * 32767).astype`, `wav.write`, `buffer.getvalue`; returns `buffer.getvalue()`.
No direct `raise` statement appears in this definition.

[View source #L257-L277](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L257-L277).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.tts.TTSEngine.get_voices" markdown="1">
<summary><code>vllm_mlx.audio.tts.TTSEngine.get_voices</code> · method</summary>

```python
vllm_mlx.audio.tts.TTSEngine.get_voices() -> list
```

Get available voices for current model.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `list`
- Direct return expressions: `KOKORO_VOICES`; `CHATTERBOX_VOICES`; `['default']`

**Exceptions and behavior**

Method `TTSEngine.get_voices` has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L279-L286](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L279-L286).

</details>

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

```python
vllm_mlx.audio.tts.TTSEngine.unload() -> None
```

Unload model to free memory.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

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

[View source #L288-L292](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L288-L292).

</details>

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

```python
vllm_mlx.audio.tts.generate_speech(text: str, model_name: str = DEFAULT_TTS_MODEL, voice: str = 'af_heart', speed: float = 1.0) -> AudioOutput
```

Convenience function to generate speech without managing engine.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | `str` | `yes` | `none` | Text to synthesize |
| `model_name` | `str` | `no` | `DEFAULT_TTS_MODEL` | Model to use |
| `voice` | `str` | `no` | `'af_heart'` | Voice ID |
| `speed` | `float` | `no` | `1.0` | Speech speed |

**Returns**

- Type: `AudioOutput`
- Direct return expressions: `engine.generate(text, voice=voice, speed=speed)`

**Exceptions and behavior**

Function `generate_speech` calls `TTSEngine`, `engine.load`, `engine.generate`; returns `engine.generate(text, voice=voice, speed=speed)`.
No direct `raise` statement appears in this definition.

[View source #L295-L315](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L295-L315).

</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 |
| --- | --- | --- | --- | --- |
| [`AudioOutput`](#contract-vllm_mlx.audio.tts.AudioOutput) | class | `AudioOutput(audio: np.ndarray, sample_rate: int, duration: float)` | Output from TTS generation. | [#L44-L49](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L44-L49) |
| [`TTSEngine`](#contract-vllm_mlx.audio.tts.TTSEngine) | class | `TTSEngine(model_name: str = DEFAULT_TTS_MODEL)` | Text-to-Speech engine supporting multiple model families. | [#L52-L292](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L52-L292) |
| [`TTSEngine.__init__`](#contract-vllm_mlx.audio.tts.TTSEngine.__init__) | method | `TTSEngine.__init__(model_name: str = DEFAULT_TTS_MODEL) -> not annotated` | Initialize TTS engine. | [#L63-L80](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L63-L80) |
| [`TTSEngine._detect_family`](#contract-vllm_mlx.audio.tts.TTSEngine._detect_family) | method | `TTSEngine._detect_family(model_name: str) -> str` | Detect model family from name. | [#L82-L98](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L82-L98) |
| [`TTSEngine.load`](#contract-vllm_mlx.audio.tts.TTSEngine.load) | method | `TTSEngine.load() -> None` | Load the TTS model. | [#L100-L117](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L100-L117) |
| [`TTSEngine.generate`](#contract-vllm_mlx.audio.tts.TTSEngine.generate) | method | `TTSEngine.generate(text: str, voice: str = 'af_heart', speed: float = 1.0, lang_code: str = 'a') -> AudioOutput` | Generate speech from text. | [#L119-L185](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L119-L185) |
| [`TTSEngine.stream_generate`](#contract-vllm_mlx.audio.tts.TTSEngine.stream_generate) | method | `TTSEngine.stream_generate(text: str, voice: str = 'af_heart', speed: float = 1.0) -> Iterator[AudioOutput]` | Stream speech generation chunk by chunk. | [#L187-L227](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L187-L227) |
| [`TTSEngine.save`](#contract-vllm_mlx.audio.tts.TTSEngine.save) | method | `TTSEngine.save(audio: AudioOutput, path: Union[str, Path], format: str = 'wav') -> None` | Save audio to file. | [#L229-L255](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L229-L255) |
| [`TTSEngine.to_bytes`](#contract-vllm_mlx.audio.tts.TTSEngine.to_bytes) | method | `TTSEngine.to_bytes(audio: AudioOutput, format: str = 'wav') -> bytes` | Convert audio to bytes. | [#L257-L277](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L257-L277) |
| [`TTSEngine.get_voices`](#contract-vllm_mlx.audio.tts.TTSEngine.get_voices) | method | `TTSEngine.get_voices() -> list` | Get available voices for current model. | [#L279-L286](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L279-L286) |
| [`TTSEngine.unload`](#contract-vllm_mlx.audio.tts.TTSEngine.unload) | method | `TTSEngine.unload() -> None` | Unload model to free memory. | [#L288-L292](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L288-L292) |
| [`generate_speech`](#contract-vllm_mlx.audio.tts.generate_speech) | function | `generate_speech(text: str, model_name: str = DEFAULT_TTS_MODEL, voice: str = 'af_heart', speed: float = 1.0) -> AudioOutput` | Convenience function to generate speech without managing engine. | [#L295-L315](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/tts.py#L295-L315) |