videobeaux/docs/programs/utilities/thumbs.md

thumbs

Description

Generates thumbnails or contact sheets by sampling frames at chosen intervals for previews, galleries, or QC review.

Purpose

The thumbs program creates frame-based preview images from video sources.
It can generate:

• evenly spaced thumbnails,
• scene-change–based extractions,
• tiled contact sheets,
• annotated or timestamped frames for analysis,
  making it ideal for QC, archives, design references, and preview libraries.

How It Works

1. Frame Sampling
   Choose between:
   • fps sampling (uniform intervals), or
   • scene detection (generate thumbnails where major scene changes occur).
2. Scene Thresholding
   scene_threshold determines sensitivity to cuts, edits, or brightness shifts.
3. Layout & Tiling
   • tile controls grid layout (e.g., 5x5 contact sheets).
   • scale sets thumbnail size.
4. Labels & Timestamps
   • timestamps includes frame timestamps.
   • label adds custom text per thumbnail.
5. Styling Options
   Background color, margins, padding, and font selection allow branding/QC annotation.
6. Export Options
   • Output directory (outdir)
   • Output filename (outputfile)
   • Image format (JPEG/PNG)
   • JPEG quality control

Program Template

videobeaux -P thumbs \
  -i input.mp4 \
  -o output.mp4 \
  --fps VALUE \
  --scene VALUE \
  --scene_threshold VALUE \
  --tile VALUE \
  --scale VALUE \
  --timestamps VALUE \
  --label VALUE \
  --fontfile VALUE \
  --bg VALUE \
  --margin VALUE \
  --padding VALUE \
  --outdir VALUE \
  --outputfile VALUE \
  --image_format VALUE \
  --jpeg_quality VALUE

Arguments

• fps — Frames per second to sample for thumbnail extraction.
• scene — Enables scene-detection-based thumbnail generation (true/false).
• scene_threshold — Sensitivity for detecting scene cuts. Lower = more cuts detected.
• tile — Contact sheet layout (e.g., 4x4, 6x8).
• scale — Size of each thumbnail (percentage or pixel dimension).
• timestamps — Adds timestamps onto each thumbnail (true/false).
• label — Custom label text rendered onto each frame.
• fontfile — Path to a custom font file for labels.
• bg — Background color for contact sheets (CSS-style hex or color name).
• margin — Outer margin around thumbnails or the full sheet.
• padding — Spacing between individual thumbnails.
• outdir — Directory where generated images will be saved.
• outputfile — Base name for the contact sheet or exported images.
• image_format — Output format (jpg, png, etc.).
• jpeg_quality — JPEG quality (0–100).

Real World Example

videobeaux -P thumbs \
  -i myvideo.mp4 \
  -o thumbs_styled.mp4 \
  --fps 1 \
  --scene false \
  --scene_threshold 0.4 \
  --tile 5x5 \
  --scale 320 \
  --timestamps true \
  --label "Preview Sheet" \
  --fontfile /path/to/font.ttf \
  --bg "#000000" \
  --margin 20 \
  --padding 10 \
  --outdir thumbs_output \
  --outputfile contactsheet \
  --image_format jpg \
  --jpeg_quality 90

Technical Notes

• Scene detection uses FFmpeg’s select='gt(scene,threshold)' filter logic.
• High tile counts produce dense sheets but increase render time.
• scale affects memory usage when generating many thumbnails.
• Custom fonts must be accessible to ffmpeg’s drawtext filter.
• Using PNG avoids compression artifacts; JPEG is faster & smaller.

Recommended Usage

• QC review workflows to quickly scan for artifacts.
• Preview libraries for editors, designers, or curators.
• Thumbnail generation for apps, web galleries, or dataset creation.
• Scene-change visualization for film analysis.

Quality Tips

• For clean contact sheets, use PNG for lossless quality.
• For large batches, use JPEG (quality 80–90) for faster export.
• Adjust scene_threshold to balance between too many vs. too few scene hits.
• Use higher scale values for detailed thumbnails, smaller for overview sheets.