mirror of
https://github.com/vondas-network/videobeaux.git
synced 2026-01-29 02:01:14 +01:00
112 lines
4.1 KiB
Markdown
112 lines
4.1 KiB
Markdown
# 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.
|