Openclaw Thumbnail Forge

---

name: openclaw-thumbnail-forge description: Local thumbnail generator for videos. Picks the best candidate frames using brightness, sharpness, and scene-change scores, then composes professional thumbnails with text overlays, gradient bars, and watermarks. Exports at YouTube, Shorts, Instagram, X, and LinkedIn sizes. Pure ffmpeg + Pillow, no AI APIs, no remote calls. license: MIT metadata: {"openclaw":{"requires":{"bins":["ffmpeg","ffprobe","python3"]},"primaryEnv":null,"homepage":"https://clawhub.ai/gopendrasharma89-tech/openclaw-thumbnail-forge"}}

---

openclaw-thumbnail-forge

v0.1.0

A practical thumbnail generator for videos. Builds the kind of professional-looking thumbnails creators normally make in Photoshop or Canva, but as a local CLI workflow with no API keys, no online services, and no AI dependencies.

What this skill does

scripts/check_deps.sh — verify ffmpeg, ffprobe, python3 (and the Pillow Python package) are installed.

scripts/pick_frames.py — extract candidate frames from a video and rank them by a composite score combining sharpness (Laplacian variance), brightness, contrast, and ffmpeg scene-change scores. Outputs the top-N frames as PNG files plus a JSON report.

scripts/compose_thumbnail.py — turn one source frame into a finished thumbnail with bold title text, subtitle, gradient bar, optional logo overlay, and auto contrast boost. Supports custom fonts and color schemes.

scripts/export_sizes.py — re-export a finished thumbnail to all common platform sizes in one command (YouTube, Shorts, Instagram square, X/Twitter, LinkedIn).

scripts/make_variants.py — generate four A/B-testable variants of the same thumbnail (different color schemes, text placements, contrast levels) for split-testing.

What this skill does not do

To set expectations honestly:

It does not use AI subject detection or face recognition. Frame ranking is statistical, not semantic.

It does not download fonts, stock photos, or any remote asset. You provide your own font path or use the system default.

It does not perform OCR, transcription, or generative editing.

It does not write outside the directory you provide.

Required dependencies

bash scripts/check_deps.sh

Verifies ffmpeg, ffprobe, python3, and that PIL (Pillow) is importable. Pillow is the only Python dependency:

pip install Pillow

Workflows

1. Pick the best candidate frames from a video

python3 scripts/pick_frames.py input.mp4 ./frames/ \
  --top 10 --interval 2.0

Extracts a frame every 2 seconds, scores each one, and writes the top 10 as frames/frame_001.png through frames/frame_010.png plus a frames/report.json with per-frame scores.

Tunable flags:

--interval — sampling interval (default 2.0)

--top — how many top frames to keep (default 10)

--min-brightness <0-255> and --max-brightness <0-255> — reject frames that are too dark or blown out

--min-sharpness — reject blurry frames (Laplacian variance floor)

2. Compose a finished thumbnail from a frame

python3 scripts/compose_thumbnail.py frames/frame_003.png thumb.png \
  --title "10 ffmpeg Tricks I Wish I Knew Sooner" \
  --subtitle "A practical tour" \
  --color-scheme bold-yellow \
  --position bottom

Color schemes shipped: bold-yellow, clean-white, red-alert, cool-blue, tech-green. Each scheme defines title color, outline color, shadow, and gradient bar opacity.

Position options: top, bottom, center. The script auto-fits the title size to the available width and adds a readable gradient bar behind the text so the thumbnail reads at small sizes too.

Optional logo overlay:

python3 scripts/compose_thumbnail.py frames/frame_003.png thumb.png \
  --title "Your Title" \
  --logo logo.png --logo-corner top-right --logo-scale 0.12

3. Export to all platform sizes at once

python3 scripts/export_sizes.py thumb.png ./out/

Writes:

out/youtube_1280x720.png

out/shorts_1080x1920.png

out/instagram_1080x1080.png

out/x_1200x675.png

out/linkedin_1200x627.png

Each platform uses smart resize: source is fitted into the target with smart-cropped letterboxing so the title area stays visible.

4. Generate A/B variants

python3 scripts/make_variants.py frames/frame_003.png ./variants/ \
  --title "10 ffmpeg Tricks" \
  --subtitle "A practical tour"

Writes 4 variants:

variant_a_bold_yellow_bottom.png

variant_b_clean_white_top.png

variant_c_red_alert_center.png

variant_d_cool_blue_bottom.png

Same source frame, different color and layout choices, ideal for click-rate split testing.

Full pipeline example

# 1) Find the best candidate frames
python3 scripts/pick_frames.py my_video.mp4 ./frames/ --top 5 --interval 1.5
2) Compose a thumbnail from the highest-scored frame
python3 scripts/compose_thumbnail.py frames/frame_001.png thumb.png \
  --title "Your Title Here" --subtitle "Optional subtitle" \
  --color-scheme bold-yellow --position bottom
3) Export at every platform size
python3 scripts/export_sizes.py thumb.png ./out/
4) Optional: split-test variants
python3 scripts/make_variants.py frames/frame_001.png ./variants/ \
  --title "Your Title Here"

Safety properties

All Python helpers use subprocess.run with argument lists (never shell=True) and reject input/output paths containing shell metacharacters via a strict regex allowlist.

The skill never reads or writes outside the input/output paths the user provides.

No environment variables are read for credentials. No tokens, secrets, or API keys are required.

No remote calls of any kind. The skill only invokes locally installed ffmpeg and the Python Pillow library.

Known limitations

Frame scoring is heuristic, not AI-based. It is not aware of "is the subject's face visible" — it just maximises sharpness, healthy brightness, and scene-change importance.

Default font is the system default if --font is not provided. If no usable font is found, the script falls back to Pillow's bitmap font, which looks plain. Pass --font for nice typography.

compose_thumbnail.py does not do automatic background removal. If you want isolated subjects, do the subject-cutout step in a different tool first.

License

MIT. See LICENSE.