- Python 93.2%
- Shell 6.8%
| test | ||
| .gitignore | ||
| perfect_frames.py | ||
| README.md | ||
perfect-frames
Extract N evenly-spaced, well-focused frames from huge videos — designed for 8K equirectangular 360 footage (GBs per minute) where decoding the whole file to pick sharp frames is not an option.
How it works
- Probe —
ffprobefor duration/fps/resolution (no decoding). - Candidates — N timestamps evenly spaced across the duration.
- Score locally — around each candidate,
ffmpegdecodes a small window (default ±1.5 s) at low resolution through a rawvideo pipe; each sampled frame is scored with a focus metric (variance of Laplacian or Tenengrad). - Pick the sharpest per window, then reject frames that are blurry:
--min-score— absolute floor (calibrate per footage via a dry run)--min-relative— reject if below a fraction of the median winner score
- Export — precise re-seek, single frame at full resolution
(lossless PNG by default, or
--jpeg-quality).
Total work ≈ N × window_seconds of low-res decode + one seek per survivor.
Windows are scored in parallel (-j).
Setup
python3 -m venv .venv && .venv/bin/pip install numpy opencv-python-headless
# ffmpeg / ffprobe must be on PATH
Usage
# 12 sharp PNG frames from an 8K 360 video
.venv/bin/python perfect_frames.py video.mp4 -n 12 -o out/
# Calibrate first: score only, look at report.json scores, then set --min-score
.venv/bin/python perfect_frames.py big.mp4 -n 12 --dry-run
# Wider search, stricter relative sharpness, JPEG, 8 workers
.venv/bin/python perfect_frames.py big.mp4 -n 20 -w 6.0 --min-relative 0.7 \
--jpeg-quality 92 -j 8 -o out/
Key options
| Flag | Default | Meaning |
|---|---|---|
-n |
10 | Number of target frames |
-w/--window |
3.0 | Search window (s) centered on each candidate |
-f/--sample-fps |
5.0 | Scoring sample rate inside the window |
-s/--scale |
1280 | Scoring downscale width |
-m/--metric |
laplacian | laplacian (var) or tenengrad (grad energy) |
--pole-mask |
0.0 | Ignore fraction of top/bottom (360 pole distortion, e.g. 0.1) |
--min-score |
off | Absolute focus floor |
--min-relative |
0.5 | Floor vs. median winner score (0 = off) |
-j/--jobs |
4 | Parallel ffmpeg workers (scan and export) |
--snap-keyframes |
off | Move picks to the nearest keyframe so export decodes 1 frame (see below) |
--snap-tolerance |
0.2 | Max distance (s) to snap a pick to a keyframe |
--dedup-threshold |
8 | dHash Hamming distance under which a pick is "too similar" (0 = off) |
--no-backfill |
— | Drop duplicate windows instead of trying the window's next-best candidate |
--jpeg-quality |
PNG | 1–100 to export JPEG instead of PNG |
--dry-run |
— | Report only |
Every run writes report.json with per-window scores, winners, and reject
reasons — useful for tuning thresholds against your footage.
Removing "too similar" frames
Duplicates arise when the camera lingers on one view: neighboring windows score near-identical content and their winners are the same picture. The metric is a 64-bit difference hash (dHash) — each frame is downscaled to 8×9 grayscale and each adjacent pixel pair contributes one bit ("which is brighter"). dHash is invariant to brightness, gamma, and compression; comparing two frames is one xor + popcount. It's computed on the low-res scoring frames already in memory, so it costs microseconds per sample.
How to read dHash Hamming distances (measured on fixtures, see
test/metric_experiment.py):
| distance | meaning |
|---|---|
| 0–2 | identical or same view a few seconds apart in a static scene |
| 3–7 | same scene, slightly different |
| 8+ | clearly different content |
--dedup-threshold (default 8) works as a greedy filter in time order:
each window's pick survives only if it is ≥ threshold bits from every
already-kept frame. With backfill (default on), a window whose top pick
duplicates an earlier frame swaps to its own next-best-scoring candidate
(already decoded — free) as long as it clears the blur floor, so you still
get N distinct frames where the footage allows. --no-backfill just drops.
Every decision lands in report.json (best_dhash, dropped_similar_to,
similar_dist, backfilled).
Calibration tips:
- Static-camera walkthrough (photogrammetry): default 8 is right.
- Slow continuous camera motion where you want "early/mid/late stages" of a similar scene: raise to 12–14 or disable with 0.
- Two picks snapped to the same keyframe export byte-identical images and are always dropped (exact-timestamp collision), independent of hashes.
- Histogram metrics separate scenes just as well but ignore geometry — a different viewing angle of the same room looks like a duplicate, which is exactly the information you want in a 360 walkthrough. Pixel-distance metrics are too fragile (exposure drift). Feature/SSIM methods are heavier for no added benefit at this decision granularity.
Speeding up the export phase
An exact-timestamp export at 8K must fast-seek to the previous keyframe and decode forward to the target — with a 2 s GOP that's ~60 full 8K frames decoded per pick just to discard them. Two mitigations, combinable:
- Parallel exports — the export loop uses the same
-jthread pool as the scan, so N frames export concurrently. --snap-keyframes— after scoring, each pick is moved (in parallel, viaffprobe's packet index — no decode) to the nearest keyframe within--snap-toleranceseconds. Snapped exports use-noaccurate_seek, landing directly on the keyframe and decoding exactly one frame. Picks outside the tolerance fall back to exact export automatically, and every snap is recorded in the report (snapped_to_keyframe,snap_delta).
Trade-off: a snapped frame is up to snap_tolerance away from the frame that
was scored, and two picks near the same keyframe can snap to the same image
(they export as separate files). For long-GOP camera footage (GOP ≥ 1 s) this
turns the export phase from "decode dozens of 8K frames per pick" into
"one seek per pick".
Tuning notes for 360 footage
- Use
--pole-mask 0.1(or so) — equirectangular poles are stretched and can skew gradient scores. tenengradis slightly more robust to sensor noise;laplacianreacts harder to motion blur. Try both in a dry run.- Motion blur is a within-window problem: bigger
-wgives the picker more room to dodge a shaky moment; higher--sample-fpscatches short sharp instants at more decode cost. - The relative threshold assumes roughly comparable scenes; for footage with
wildly different content density (dark vs. detailed scenes), calibrate
--min-scoreper shoot instead.
Tests
test/ contains a synthetic clip (sharp → tmix-blurred → sharp) used to
verify the pipeline rejects blur via --min-score. Regenerate with the
commands in test/make_fixtures.sh.