acvr 0.1.0

Accurate video reader for python.

Accurate video reader (acvr)

Video reader built around PyAV for frame-accurate seeking.

Inspired by code in rerun.io.

Supports:

• accurate, random-access retrieval of individual frames from videos encoded with modern codecs (H.264, H.265)
• works with variable-frame rate videos
• LRU
• Fast scrubbing mode

Installation

In a terminal window run:

pip install acvr

or

conda install acvr -c ncb

Usage

Open a video file and read frame 100:

from acvr import VideoReader
vr = VideoReader(video_file_name)
print(vr)  # prints video_file_name, number of frames, frame rate and frame size
frame = vr[100]
vr.close()

Or use a context manager which takes care of opening and closing the video:

with VideoReader(video_file_name) as vr:  # load the video
    frame = vr[100]

Read modes

from acvr import VideoReader

with VideoReader(video_file_name, build_index=True) as vr:
    accurate = vr.read_frame(index=100, mode="accurate")
    fast = vr.read_frame(index=100, mode="fast")
    scrub = vr.read_frame(t_s=1.0, mode="scrub", keyframe_mode="nearest")

Documentation

The latest documentation lives at https://janclemenslab.org/acvr.

To build the docs locally:

pip install acvr[docs]
mkdocs serve

Publishing

Build and upload the distribution to PyPI:

python -m build
python -m twine upload dist/*

Test videos

The test video generator script scripts/make_test_h264_videos.py requires ffmpeg to be available on your PATH. The script also needs OpenCV; install the dev extras to pull in a headless build:

pip install acvr[dev]

If you're using conda, you can install ffmpeg like this:

conda install -c conda-forge ffmpeg

Benchmark snapshot

On the bundled CFR/VFR test assets (M1-class laptop, PyAV 12.x):

Mode	CFR fast (ms/frame)	CFR accuracy	VFR fast (ms/frame)	VFR accuracy
Accurate	~89	exact	~88	matches PyAV reference
Scrub (keyframes)	~2	very approximate	~2	very approximate
Fast (PyAV)	~12	matches OpenCV	~12	matches OpenCV