Metadata-Version: 2.4
Name: pupil-labs-video
Version: 1.0.11
Summary: A high-level wrapper of PyAV providing an easy to use interface to video data.
Project-URL: Homepage, https://pupil-labs.github.io/pl-video
Project-URL: Documentation, https://pupil-labs.github.io/pl-video
Project-URL: Repository, https://github.com/pupil-labs/pl-video
Project-URL: Issues, https://github.com/pupil-labs/pl-video/issues
Author-email: Pupil Labs GmbH <info@pupil-labs.com>
License: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.10
Requires-Dist: av
Requires-Dist: numpy
Requires-Dist: universal-pathlib
Provides-Extra: examples
Requires-Dist: opencv-python; extra == 'examples'
Requires-Dist: tqdm; extra == 'examples'
Description-Content-Type: text/markdown

# Pupil Labs Video

[![ci](https://github.com/pupil-labs/pl-video/actions/workflows/main.yml/badge.svg)](https://github.com/pupil-labs/pl-video/actions/workflows/main.yml)
[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://pupil-labs.github.io/pl-video/)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![pre-commit](https://img.shields.io/badge/pre_commit-black?logo=pre-commit&logoColor=FAB041)](https://github.com/pre-commit/pre-commit)
[![pypi version](https://img.shields.io/pypi/v/pupil-labs-video.svg)](https://pypi.org/project/pupil-labs-video/)
[![python version](https://img.shields.io/pypi/pyversions/pupil-labs-video)](https://pypi.org/project/pupil-labs-video/)

[![pl-video banner](https://raw.githubusercontent.com/pupil-labs/pl-video/refs/heads/main/docs/assets/banner.png)](https://pupil-labs.com/)

A high-level wrapper of [PyAV](https://github.com/PyAV-Org/PyAV) providing an easy to use interface to video data.

The goal of this library is to provide a simple interface while maintaining good computational performance. At current, only MP4 and MJPEG videos are officially compatible.

Features include:

- Performant reading of video files (optionally including audio) utilizing multi-threading.
- Ability to arbitrarily index frames by their index or timestamp.
- Ability to slice the video by frame index or time. Large slices will be loaded lazily to avoidexcessive RAM consumption.
- A frame buffer is maintained to cache frames close to the current decoding position, which avoids repetitive seeking when going back and forth between frames in the same neighborhood or iterating backwards.
- Avoids demuxing and seeking operations as much as possible.
- Reading multi-part video files (e.g. how they are generated by Neon or Pupil Invisible).

## Installation

```
pip install pupil-labs-video
```

or

```bash
pip install -e git+https://github.com/pupil-labs/pl-video.git
```

## Quick Start

You can open a video file and read frames like this:

```python
import pupil_labs.video as plv

with plv.Reader(video_path) as video:
    # Iterate through video frames
    for frame in video:
        # Convert video frame to BGR array
        img = frame.bgr

    # Index individual frames or slices
    first_frame = video[0]
    last_frame = video[-1]
    frames = video[10:20]

    # Index frames by time
    ts = video[10].time
    frame = video.by_container_timestamps[ts]
    frames = video.by_container_timestamps[ts : ts + 10]
```

You can write video files like this:

```python
import pupil_labs.video as plv

with (plv.Writer(out_path) as writer):
    for img in images:
        writer.write_image(img)
```
