# `examples.video_benchmark`

Video Benchmark Script for vllm-mlx Tests Vision-Language Models with video at different configurations (FPS, frame count, resolution) and measures performance metrics.

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

## 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.video_benchmark
    options:
      members:
        - logger
        - SAMPLE_VIDEOS
        - VideoBenchmarkResult
        - create_test_video
        - download_video
        - get_video_info
        - run_video_benchmark
        - run_benchmark
        - print_results
        - save_results
        - 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.video_benchmark.VideoBenchmarkResult" markdown="1">
<summary><code>examples.video_benchmark.VideoBenchmarkResult</code> · class</summary>

```python
examples.video_benchmark.VideoBenchmarkResult(config_name: str, fps: float, max_frames: int, frames_extracted: int, video_duration: float, time_seconds: float, prompt_tokens: int, completion_tokens: int, tokens_per_second: float, response_preview: str)
```

Result from a single video benchmark run.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `config_name` | `str` | `yes` | `none` | Required constructor field. |
| `fps` | `float` | `yes` | `none` | Required constructor field. |
| `max_frames` | `int` | `yes` | `none` | Required constructor field. |
| `frames_extracted` | `int` | `yes` | `none` | Required constructor field. |
| `video_duration` | `float` | `yes` | `none` | Required constructor field. |
| `time_seconds` | `float` | `yes` | `none` | Required constructor field. |
| `prompt_tokens` | `int` | `yes` | `none` | Required constructor field. |
| `completion_tokens` | `int` | `yes` | `none` | Required constructor field. |
| `tokens_per_second` | `float` | `yes` | `none` | Required constructor field. |
| `response_preview` | `str` | `yes` | `none` | Required constructor field. |

**Returns**

- Constructs: `examples.video_benchmark.VideoBenchmarkResult`

**Exceptions and behavior**

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

[View source #L80-L91](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L80-L91).

</details>

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

```python
examples.video_benchmark.create_test_video(duration: float = 5.0, fps: float = 30.0, width: int = 640, height: int = 480) -> str
```

Create a synthetic test video with colored frames and text.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `duration` | `float` | `no` | `5.0` | Video duration in seconds |
| `fps` | `float` | `no` | `30.0` | Frames per second |
| `width` | `int` | `no` | `640` | Video width |
| `height` | `int` | `no` | `480` | Video height |

**Returns**

- Type: `str`
- Direct return expressions: `temp_file.name`

**Exceptions and behavior**

Function `create_test_video` calls `tempfile.NamedTemporaryFile`, `temp_file.close`, `cv2.VideoWriter_fourcc`, `cv2.VideoWriter`; returns `temp_file.name`.
No direct `raise` statement appears in this definition.

[View source #L94-L175](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L94-L175).

</details>

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

```python
examples.video_benchmark.download_video(url: str, timeout: int = 120) -> str
```

Download video from URL.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `url` | `str` | `yes` | `none` | Required positional or keyword input. |
| `timeout` | `int` | `no` | `120` | Optional positional or keyword input; defaults to `120`. |

**Returns**

- Type: `str`
- Direct return expressions: `temp_file.name`

**Exceptions and behavior**

Function `download_video` calls `logger.info`, `requests.get`, `response.raise_for_status`, `tempfile.NamedTemporaryFile`; returns `temp_file.name`.
No direct `raise` statement appears in this definition.

[View source #L178-L198](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L178-L198).

</details>

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

```python
examples.video_benchmark.get_video_info(video_path: str) -> dict
```

Get information about a video file.

**Parameters**

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

**Returns**

- Type: `dict`
- Direct return expressions: `{'error': 'Cannot open video'}`; `info`

**Exceptions and behavior**

Function `get_video_info` calls `cv2.VideoCapture`, `cap.isOpened`, `int`, `cap.get`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L201-L217](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L201-L217).

</details>

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

```python
examples.video_benchmark.run_video_benchmark(model, video_path: str, fps: float, max_frames: int, config_name: str, warmup: bool = False) -> VideoBenchmarkResult
```

Run a single video benchmark configuration.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model` | `not annotated` | `yes` | `none` | Required positional or keyword input. |
| `video_path` | `str` | `yes` | `none` | Required positional or keyword input. |
| `fps` | `float` | `yes` | `none` | Required positional or keyword input. |
| `max_frames` | `int` | `yes` | `none` | Required positional or keyword input. |
| `config_name` | `str` | `yes` | `none` | Required positional or keyword input. |
| `warmup` | `bool` | `no` | `False` | Optional positional or keyword input; defaults to `False`. |

**Returns**

- Type: `VideoBenchmarkResult`
- Direct return expressions: `VideoBenchmarkResult(config_name=config_name, fps=fps, max_frames=max_frames, frames_extracted=frames_extracted, video_…`

**Exceptions and behavior**

Function `run_video_benchmark` calls `get_video_info`, `print`, `time.perf_counter`, `model.generate`; returns `VideoBenchmarkResult(config_name=config_name, fps=fps, max_frames=max_frames, frames_extracted=frames_extracted, video_…`.
No direct `raise` statement appears in this definition.

[View source #L220-L271](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L220-L271).

</details>

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

```python
examples.video_benchmark.run_benchmark(model_name: str, video_path: str = None, video_url: str = None, video_duration: float = 10.0, warmup_runs: int = 1, quick: bool = False) -> list[VideoBenchmarkResult]
```

Run full video benchmark across multiple configurations.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `yes` | `none` | VLM model to use |
| `video_path` | `str` | `no` | `None` | Local video file path |
| `video_url` | `str` | `no` | `None` | URL to download video from |
| `video_duration` | `float` | `no` | `10.0` | Duration for synthetic video |
| `warmup_runs` | `int` | `no` | `1` | Number of warmup runs |
| `quick` | `bool` | `no` | `False` | Run quick benchmark with fewer configs |

**Returns**

- Type: `list[VideoBenchmarkResult]`
- Direct return expressions: `results`

**Exceptions and behavior**

Function `run_benchmark` calls `print`, `time.time`, `MLXVisionLanguageModel`, `model.load`; returns `results`.
No direct `raise` statement appears in this definition.

[View source #L274-L374](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L274-L374).

</details>

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

```python
examples.video_benchmark.print_results(results: list[VideoBenchmarkResult]) -> not annotated
```

Print benchmark results in a nice table.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `results` | `list[VideoBenchmarkResult]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

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

**Exceptions and behavior**

Function `print_results` calls `print`, `sorted`, `table_data.append`, `tabulate`; returns `None`.
No direct `raise` statement appears in this definition.

[View source #L377-L445](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L377-L445).

</details>

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

```python
examples.video_benchmark.save_results(results: list[VideoBenchmarkResult], output_path: str, model_name: str) -> not annotated
```

Save benchmark results to JSON file.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `results` | `list[VideoBenchmarkResult]` | `yes` | `none` | Required positional or keyword input. |
| `output_path` | `str` | `yes` | `none` | Required positional or keyword input. |
| `model_name` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `not annotated`

**Exceptions and behavior**

Function `save_results` calls `time.strftime`, `open`, `json.dump`, `print`.
No direct `raise` statement appears in this definition.

[View source #L448-L474](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L448-L474).

</details>

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

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

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

**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`, `run_benchmark`.
No direct `raise` statement appears in this definition.

[View source #L477-L559](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L477-L559).

</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 |
| --- | --- | --- | --- | --- |
| [`VideoBenchmarkResult`](#contract-examples.video_benchmark.VideoBenchmarkResult) | class | `VideoBenchmarkResult(config_name: str, fps: float, max_frames: int, frames_extracted: int, video_duration: float, time_seconds: float, prompt_tokens: int, completion_tokens: int, tokens_per_second: float, response_preview: str)` | Result from a single video benchmark run. | [#L80-L91](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L80-L91) |
| [`create_test_video`](#contract-examples.video_benchmark.create_test_video) | function | `create_test_video(duration: float = 5.0, fps: float = 30.0, width: int = 640, height: int = 480) -> str` | Create a synthetic test video with colored frames and text. | [#L94-L175](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L94-L175) |
| [`download_video`](#contract-examples.video_benchmark.download_video) | function | `download_video(url: str, timeout: int = 120) -> str` | Download video from URL. | [#L178-L198](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L178-L198) |
| [`get_video_info`](#contract-examples.video_benchmark.get_video_info) | function | `get_video_info(video_path: str) -> dict` | Get information about a video file. | [#L201-L217](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L201-L217) |
| [`run_video_benchmark`](#contract-examples.video_benchmark.run_video_benchmark) | function | `run_video_benchmark(model, video_path: str, fps: float, max_frames: int, config_name: str, warmup: bool = False) -> VideoBenchmarkResult` | Run a single video benchmark configuration. | [#L220-L271](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L220-L271) |
| [`run_benchmark`](#contract-examples.video_benchmark.run_benchmark) | function | `run_benchmark(model_name: str, video_path: str = None, video_url: str = None, video_duration: float = 10.0, warmup_runs: int = 1, quick: bool = False) -> list[VideoBenchmarkResult]` | Run full video benchmark across multiple configurations. | [#L274-L374](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L274-L374) |
| [`print_results`](#contract-examples.video_benchmark.print_results) | function | `print_results(results: list[VideoBenchmarkResult]) -> not annotated` | Print benchmark results in a nice table. | [#L377-L445](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L377-L445) |
| [`save_results`](#contract-examples.video_benchmark.save_results) | function | `save_results(results: list[VideoBenchmarkResult], output_path: str, model_name: str) -> not annotated` | Save benchmark results to JSON file. | [#L448-L474](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L448-L474) |
| [`main`](#contract-examples.video_benchmark.main) | function | `main() -> not annotated` | Function `main` calls `argparse.ArgumentParser`, `parser.add_argument`, `parser.parse_args`, `run_benchmark`. | [#L477-L559](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/examples/video_benchmark.py#L477-L559) |