VQTools

This repository provides a lightweight command-line toolkit for running video quality metrics and related utilities. vqcheck offers an easy way to build and run several recent full-reference and no-reference models while providing a unified output format (JSON).

Installation

To install the included tools run the following on either Linux or macOS:

git clone https://github.com/benjaminherb/VQTools
cd VQTools
chmod +x ./install.sh
./install.sh

This installs the tools in ~/.local/share/vqtools. An ffmpeg/ffprobe installation with libvmaf support is required for VMAF modes.

VQCheck

Run a no-reference model on a single video:

vqcheck -m dover -d distorted.mp4

Run a full-reference model on a set of videos and save the results:

vqcheck -m lpips -d /path/to/distorted -r /path/to/references/ -o ./results/

Options:

• -d, --distorted (required) — Distorted video file or folder
• -r, --reference — Reference video file or folder (required for FR modes)
• -m, --mode — Which metric/mode to run (see table below).
• -o, --output — Optional: save output files (one *.method.json per video). If -o is passed without an argument, the output is written next to the distorted files.
• -q, --quiet — Reduce console output
• --rebuild - Delete and rebuild the selected model if applicable
• --tempdir - Specify temporary directory to use (eg for transcoding)

Notes:

• If --reference is a folder, the script uses the closest filename match.
• If psnr is calculated, the script also returns whether the file and reference are a perfect match (e.g., to check for lossless errors).
• When running a method for the first time, its code and required files are pulled and built.
• MaxVQA seems to have issues with ffmpeg 8 but works with ffmpeg 7.
• The script tries to use GPU backends where available (MPS/Vulkan/CUDA), but will fall back to CPU
• For full-reference metrics the distorted files are scaled to the reference size (if they are smaller)

Models

Model	Type	Methods	Repository	Notes
Check	FR	check		Metadata check to ensure metadata for distorted and reference match (resolution, framerate, framecount etc)
PSNR	FR	psnr		Faster way to just calculate PSNR
VMAF	FR	vmaf vmaf4k vmaf-full vmaf4k-full	VMAF	Always includes SSIM/MS-SSIM and PSNR; full variants additionally include the NEG (no-enhancement gain) variants (slower).
CVVDP	FR	cvvdp-fhd, cvvdp-4k	ColorVideoVDP	Paper
LPIPS	FR	lpips-alex, lpips-vgg	PerceptualSimilarity	Paper - frame-wise metric, uses AlexNet or VGG as backbone
PyIQA	FR/NR	musiq, brisque, niqe, dists, clipiqa, clipiqa+, fsim, nlpd	IQA-Pytorch	Musiq - BRISQUE - NIQE - DISTS - CLIP-IQA(+) - FSIM - NLPD - image quality metrics provided as mean and per-frame scores (sampled at 2 per second).
JPEG XL	FR	ssimulacra2, butteraugli	SSIMULACRA2 Butteraugli	Image metric (sampled at 2 per second), uses implementations included with JPEG XL
CVQA	FR/NR	cvqa-nr cvqa-nr-ms cvqa-fr cvqa-fr-ms	CompressedVQA	Paper
CVQA-HDR	FR/NR	cvqa-hdr-nr cvqa-hdr-fr	CompressedVQA-HDR	Paper - HDR-focused variant with different architectures
MDTVSFA	NR	mdtvsfa	MDTVSFA	Paper
FastVQA	NR	fastvqa fastervqa	FAST-VQA/FasterVQA	Paper
UVQ	NR	uvq, uvq1p5	UVQ	Paper - separate and combined scores for compression, distortion and content
Dover	NR	dover	DOVER	Paper - includes technical and aesthetic score
Q-Align	NR	qalign	Q-Align	Paper
MaxVQA	NR	maxvqa	ExplainableVQA	Paper - several scores for different quality factors
Cover	NR	cover	COVER	Paper — semantic, technical and aesthetic scores.

Other Tools

seq2mkv

Encode image sequences (png, jpeg, tiff) located in subfolders under a root directory into MKV files using ffmpeg. Options:

• root_dir (positional) — root directory containing folders with image sequences
• --fps — output framerate (default: 60)
• --scale — optional W:H scale (defaults to 3840:2160 when provided without value)
• --ffvhuff — use ffvhuff codec instead of H.265 (lossless)
• --pix-fmt — explicit pixel format to pass to ffmpeg
• --output-dir — output directory (default: <root_dir>/mkv)
• --dryrun — do not run ffmpeg; just show commands
• --overwrite — overwrite existing output files

Example:

seq2mkv /path/to/sequences --scale 3840:2160 --ffvhuff --output-dir ./mkv

transcode

Transcode all video files in a directory to a standardized MKV (lossless) using either ffvhuff (for playback) or h265 (for storage).

Options:

• -i/--input — input directory containing video files (required)
• -o/--output — output directory for converted files (required)
• --codec — one of ffvhuff or h265 (default: h265)
• --scale - scale videos to specified WIDTH and HEIGHT (e.g., --scale 1920 1080)
• --overwrite — overwrite existing files in the output directory
• --dryrun — show ffmpeg commands without executing them

Example:

transcode -i ./videos -o ./converted --codec ffvhuff

vca

Calculate spatial/temporal complexity features with VCA (Video Complexity Analyzer). Videos are decoded with ffmpeg and piped to VCA as Y4M. Results are stored in a *.vca.json file per video: mean values, per-frame features and detected shots.

Options:

• -i/--input — input video file or directory (required)
• -o/--output — output directory (required)
• --pix-fmt — pixel format passed to VCA (default: yuv420p, 8-bit for comparable values across sources)
• --block-size — DCT block size 8, 16 or 32 (default: 32)
• --threads — VCA threads per video (default: 0 = autodetect)
• --workers — number of parallel videos (default: 0 = serial)
• --overwrite — overwrite existing files
• --rebuild — delete and rebuild VCA

Example:

vca -i ./videos -o ./vca --workers 4

aggmet

Consolidate multiple metric JSON files into a single JSON report. The script scans a directory tree for *.method.json files and groups them by base video name.

Options:

• --metrics-dir, -m — directory containing individual metric JSON files (required)
• --output-file, -o — path to write consolidated JSON (required)
• --existing-json, -e — optional existing combined JSON to update/merge

Example:

aggmet -m ./metrics -o consolidated.json

metaex

Extract metadata from video files using ffprobe. The info is stored in a *.meta.json file.

Options

• --input_dir, -i - Input folder with media files
• --output_dir, -o - Output folder to write per-file metadata JSON
• --recursive, -r - Recurse into subdirectories

Example:

metaex -i ./pvs -o ./meta

License and attribution

See each linked repository for license and citation details — this project provides only integration code.