# mlx-video

`mlx-video` is a small video preprocessing library for MLX on Apple Silicon.

GitHub: <https://github.com/AmiraniLabs/mlx-video>

It focuses on the first mile of video ML:

- load video files into `mlx.core.array`
- sample frames at a target FPS
- resize clips for model input
- convert `uint8` frames to normalized `float32` tensors

## Install

```bash
pip install mlx-video
```

## Publishing

This package is configured for PyPI Trusted Publishing from the
`AmiraniLabs/mlx-video` GitHub repository using
`.github/workflows/publish.yml`.

## Quickstart

```python
import mlx_video as mv

frames = mv.load("video.mp4", fps=8)         # mx.array [T, H, W, C], uint8 RGB
frames = mv.resize(frames, (224, 224))       # spatial resize
frames = mv.normalize(frames)                # float32, ImageNet normalized
```

## API

### `load(path, fps=None, start_time=None, end_time=None, max_frames=None)`

Loads a video into a `mx.array` with shape `[T, H, W, C]` in RGB order.

### `resize(frames, size)`

Resizes each frame to `(height, width)`.

### `to_float(frames, scale=True)`

Casts frames to `float32`. By default values are scaled to `[0, 1]`.

### `normalize(frames, mean=..., std=...)`

Applies channel-wise normalization using ImageNet defaults. Integer inputs are
automatically converted to floating point and scaled before normalization.
