How it works · write-up
Frame-by-frame video comparison
xenon_tools/compare_video_frames.py compares decoded RGB frames from any two
FFmpeg-readable recordings with equal dimensions and cadence. It requires
FFmpeg, FFprobe, Pillow with WebP support, and NumPy. Run from the repository root:
python xenon_tools\compare_video_frames.py "E:\xenon_runs\highfps-compare-20261007\compare-600vbl\5-hd-old-highfps.mp4" "E:\xenon_runs\highfps-compare-20261007\compare-600vbl\6-hd-new-highfps.mp4" --output "E:\xenon_runs\highfps-compare-20261007\compare-600vbl\5-vs-6-difference"
The output directory must be new; recordings and existing reports are not
modified. Open index.html in a browser. The viewer has a timeline, numbered
frame selection, previous/next controls, playback, a difference chart, and
native-resolution viewing. Every frame has three panels: recording A, recording
B, and amplified absolute RGB difference. The viewer uses precomputed panels,
so it opens directly from disk and does not repeatedly recalculate pixel data.
The frames/ directory contains a lossless full-resolution WebP comparison for
every frame pair. metrics.csv and report.json contain all frame indices,
presentation timestamps, exact different-pixel counts, thresholded counts,
mean absolute RGB difference and maximum channel difference. comparison.mp4
contains labeled panels at the original rational cadence; it has no audio and
uses H.264, so the lossless frame images are authoritative for pixel inspection.
The default threshold is 8 channel levels, and difference gain is 8. Small H.264
compression differences can exist even when rendered content matches. Use
--threshold 0 to display every changed pixel. --gain 16 amplifies differences
more strongly. The chart and exported metrics use the same threshold as the panels.
Comparison uses matching clip-frame indices, with no hidden alignment correction
or frame duplication. --offset-frames 1 compares A frame 1 with B frame 2;
negative offsets skip initial A frames. Do not infer an offset solely from which
pair looks most similar: interpolation itself can change the apparent timing.
VBL sidecars are not used for trimmed MP4s without their own matching index.
Use --frames 120 for a short probe or --no-video to skip MP4 generation while
retaining every lossless frame and the viewer. --ffmpeg and --ffprobe accept
explicit executable paths. Frame numbering in the report starts at one.