# `examples.benchmark_audio`

Audio benchmarks for vllm-mlx.

[View the complete module source at #L1-L332](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L1-L332).

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

::: examples.benchmark_audio
    options:
      members:
        - STT_MODELS
        - TTS_MODELS
        - TEST_TEXTS
        - generate_test_audio
        - benchmark_tts
        - get_audio_duration
        - benchmark_stt
        - check_whisper_backend
        - run_tts_benchmarks
        - run_stt_benchmarks
        - main
      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-examples.benchmark_audio.generate_test_audio" markdown="1">
<summary><code>examples.benchmark_audio.generate_test_audio</code> · function</summary>

```python
examples.benchmark_audio.generate_test_audio(duration_seconds: float = 5.0) -> str
```

Generate a simple test audio file using TTS.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `duration_seconds` | `float` | `no` | `5.0` | Optional positional or keyword input; defaults to `5.0`. |

**Returns**

- Type: `str`
- Direct return expressions: `path`

**Exceptions and behavior**

Function `generate_test_audio` calls `np.linspace`, `int`, `np.sin`, `(audio * 32767).astype`; returns `path`.
No direct `raise` statement appears in this definition.

[View source #L36-L61](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L36-L61).

</details>

<details class="api-contract" id="contract-examples.benchmark_audio.benchmark_tts" markdown="1">
<summary><code>examples.benchmark_audio.benchmark_tts</code> · function</summary>

```python
examples.benchmark_audio.benchmark_tts(model_name: str, alias: str, texts: list[str], voice: str = 'af_heart') -> not annotated
```

Benchmark TTS model.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `yes` | `none` | Required positional or keyword input. |
| `alias` | `str` | `yes` | `none` | Required positional or keyword input. |
| `texts` | `list[str]` | `yes` | `none` | Required positional or keyword input. |
| `voice` | `str` | `no` | `'af_heart'` | Optional positional or keyword input; defaults to `'af_heart'`. |

**Returns**

- Type: `not annotated`
- Direct return expressions: `{'model': alias, 'load_time': load_time, 'avg_chars_per_sec': avg_chars_per_sec, 'avg_rtf': avg_rtf}`

**Exceptions and behavior**

Function `benchmark_tts` calls `print`, `time.time`, `TTSEngine`, `engine.load`; returns `{'model': alias, 'load_time': load_time, 'avg_chars_per_sec': avg_chars_per_sec, 'avg_rtf': avg_rtf}`.
No direct `raise` statement appears in this definition.

[View source #L64-L124](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L64-L124).

</details>

<details class="api-contract" id="contract-examples.benchmark_audio.get_audio_duration" markdown="1">
<summary><code>examples.benchmark_audio.get_audio_duration</code> · function</summary>

```python
examples.benchmark_audio.get_audio_duration(audio_path: str) -> float
```

Get audio duration in seconds.

**Parameters**

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

**Returns**

- Type: `float`
- Direct return expressions: `frames / float(rate)`; `float(result.stdout.strip())`; `0.0`

**Exceptions and behavior**

Function `get_audio_duration` calls `audio_path.endswith`, `contextlib.closing`, `wave.open`, `f.getnframes`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L127-L159](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L127-L159).

</details>

<details class="api-contract" id="contract-examples.benchmark_audio.benchmark_stt" markdown="1">
<summary><code>examples.benchmark_audio.benchmark_stt</code> · function</summary>

```python
examples.benchmark_audio.benchmark_stt(model_name: str, alias: str, audio_path: str) -> not annotated
```

Benchmark STT model.

**Parameters**

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

**Returns**

- Type: `not annotated`
- Direct return expressions: `{'model': alias, 'load_time': load_time, 'audio_duration': duration, 'trans_time': trans_time, 'rtf': rtf}`

**Exceptions and behavior**

Function `benchmark_stt` calls `print`, `get_audio_duration`, `time.time`, `STTEngine`; returns `{'model': alias, 'load_time': load_time, 'audio_duration': duration, 'trans_time': trans_time, 'rtf': rtf}`.
No direct `raise` statement appears in this definition.

[View source #L162-L212](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L162-L212).

</details>

<details class="api-contract" id="contract-examples.benchmark_audio.check_whisper_backend" markdown="1">
<summary><code>examples.benchmark_audio.check_whisper_backend</code> · function</summary>

```python
examples.benchmark_audio.check_whisper_backend() -> not annotated
```

Check whether the Whisper backend can be imported.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `not annotated`
- Direct return expressions: `(True, '')`; `(False, str(e))`

**Exceptions and behavior**

Function `check_whisper_backend` calls `str`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L215-L227](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L215-L227).

</details>

<details class="api-contract" id="contract-examples.benchmark_audio.run_tts_benchmarks" markdown="1">
<summary><code>examples.benchmark_audio.run_tts_benchmarks</code> · function</summary>

```python
examples.benchmark_audio.run_tts_benchmarks() -> not annotated
```

Run all TTS benchmarks.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `not annotated`
- Direct return expressions: `results`

**Exceptions and behavior**

Function `run_tts_benchmarks` calls `print`, `benchmark_tts`, `results.append`; returns `results`.
No direct `raise` statement appears in this definition.

[View source #L230-L257](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L230-L257).

</details>

<details class="api-contract" id="contract-examples.benchmark_audio.run_stt_benchmarks" markdown="1">
<summary><code>examples.benchmark_audio.run_stt_benchmarks</code> · function</summary>

```python
examples.benchmark_audio.run_stt_benchmarks(audio_path: str) -> not annotated
```

Run all STT benchmarks.

**Parameters**

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

**Returns**

- Type: `not annotated`
- Direct return expressions: `results`

**Exceptions and behavior**

Function `run_stt_benchmarks` calls `print`, `check_whisper_backend`, `alias.startswith`, `benchmark_stt`; returns `results`.
No direct `raise` statement appears in this definition.

[View source #L260-L295](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L260-L295).

</details>

<details class="api-contract" id="contract-examples.benchmark_audio.main" markdown="1">
<summary><code>examples.benchmark_audio.main</code> · function</summary>

```python
examples.benchmark_audio.main() -> not annotated
```

Function `main` calls `argparse.ArgumentParser`, `parser.add_argument`, `parser.parse_args`, `print`.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `not annotated`

**Exceptions and behavior**

Function `main` calls `argparse.ArgumentParser`, `parser.add_argument`, `parser.parse_args`, `print`.
No direct `raise` statement appears in this definition.

[View source #L298-L328](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L298-L328).

</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 |
| --- | --- | --- | --- | --- |
| [`generate_test_audio`](#contract-examples.benchmark_audio.generate_test_audio) | function | `generate_test_audio(duration_seconds: float = 5.0) -> str` | Generate a simple test audio file using TTS. | [#L36-L61](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L36-L61) |
| [`benchmark_tts`](#contract-examples.benchmark_audio.benchmark_tts) | function | `benchmark_tts(model_name: str, alias: str, texts: list[str], voice: str = 'af_heart') -> not annotated` | Benchmark TTS model. | [#L64-L124](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L64-L124) |
| [`get_audio_duration`](#contract-examples.benchmark_audio.get_audio_duration) | function | `get_audio_duration(audio_path: str) -> float` | Get audio duration in seconds. | [#L127-L159](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L127-L159) |
| [`benchmark_stt`](#contract-examples.benchmark_audio.benchmark_stt) | function | `benchmark_stt(model_name: str, alias: str, audio_path: str) -> not annotated` | Benchmark STT model. | [#L162-L212](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L162-L212) |
| [`check_whisper_backend`](#contract-examples.benchmark_audio.check_whisper_backend) | function | `check_whisper_backend() -> not annotated` | Check whether the Whisper backend can be imported. | [#L215-L227](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L215-L227) |
| [`run_tts_benchmarks`](#contract-examples.benchmark_audio.run_tts_benchmarks) | function | `run_tts_benchmarks() -> not annotated` | Run all TTS benchmarks. | [#L230-L257](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L230-L257) |
| [`run_stt_benchmarks`](#contract-examples.benchmark_audio.run_stt_benchmarks) | function | `run_stt_benchmarks(audio_path: str) -> not annotated` | Run all STT benchmarks. | [#L260-L295](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L260-L295) |
| [`main`](#contract-examples.benchmark_audio.main) | function | `main() -> not annotated` | Function `main` calls `argparse.ArgumentParser`, `parser.add_argument`, `parser.parse_args`, `print`. | [#L298-L328](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/benchmark_audio.py#L298-L328) |