vidstats

Extract per-frame colour and luminosity metrics from video using ffprobe's signalstats filter. Output goes to Parquet, CSV, IPC/Feather, or NDJSON.

Designed for research pipelines that need a fast, dependency-light way to turn a video into a tabular time series — for example, non-contact cardiac monitoring in animals via colour/motion video analysis.

Installation

pixi (recommended — pulls in ffmpeg automatically):

pixi global install vidstats

uv (global install):

uv tool install vidstats

conda:

conda install -c conda-forge vidstats

pip (requires ffmpeg on PATH separately):

pip install vidstats

Usage

# Extract all metrics → Parquet
vidstats input.mp4 output.parquet

# Extract only luminance and saturation averages → CSV
vidstats input.mp4 output.csv --metrics YAVG,SATAVG

# Include both frame number and timestamp in seconds
vidstats input.mp4 output.parquet --timestamps both

# Override FPS when stream metadata is missing or wrong
vidstats input.mp4 output.parquet --timestamps both --fps 30

# Apply a crop region (X Y W H) before extraction
vidstats input.mp4 output.parquet --crop "10 20 180 180"

# Force format regardless of extension
vidstats input.mp4 output.dat --format csv

# Disable hardware acceleration
vidstats input.mp4 output.parquet --no-hwaccel

# List all available metric names and their output column names
vidstats --list-metrics

Python API

vidstats can also be used directly from Python. The simplest path is the extract() convenience function:

import vidstats

df = vidstats.extract("input.mp4")

df is a Polars DataFrame with the same schema as the CLI output. Optional arguments mirror the CLI:

df = vidstats.extract(
    "input.mp4",
    metrics=["YAVG", "SATAVG", "HUEMED"],  # default: all metrics
    crop=(10, 20, 180, 180),               # (x, y, w, h) in pixels
    include_time=True,                     # adds time_s column
    fps=25.0,                              # override FPS for time_s
    hwaccel="cuda",                        # hardware decode acceleration
)

Write the result with any Polars method:

df.write_parquet("output.parquet")
df.write_csv("output.csv")

Supported output formats

Available metrics

All 25 signalstats metrics are extracted by default. Run vidstats --list-metrics for the full table of ffprobe names, output column names, and descriptions. They cover:

• Luminance: YMIN, YLOW, YAVG, YHIGH, YMAX
• Cb chrominance (U): same set of five
• Cr chrominance (V): same set of five
• Saturation: SATMIN, SATLOW, SATAVG, SATHIGH, SATMAX
• Hue: HUEMED, HUEAVG
• Quality flags: TOUT, VREP, BRNG

The --metrics flag accepts ffprobe names (e.g. YAVG,SATAVG). Output columns use descriptive snake_case names (e.g. luminance_mean, saturation_mean) — see --list-metrics for the full mapping.

Output schema

time_s is computed as frame / fps. FPS is read from stream metadata automatically; use --fps to override it or supply it when metadata is absent.

Hardware acceleration

vidstats auto-detects CUDA and passes -hwaccel cuda to ffprobe if available. This accelerates the decode stage only — signalstats itself always runs on CPU. For small (e.g. 200×200) videos the gain is negligible, but the detection is there for larger inputs. Suppress with --no-hwaccel.

No special CUDA packages or drivers are required beyond what you already have. vidstats uses ffprobe's built-in NVDEC hardware decoding, which talks directly to the NVIDIA driver on your system — there is no cudatoolkit, no pytorch-cuda, and no GPU-specific installation step.

License

MIT