openclaw-thumbnail-forge

by gopendrasharma89-tech

Install this Skill

curl -fsSL -o openclaw-thumbnail-forge.zip https://skill.seembox.com/api/v1/skills/openclaw-thumbnail-forge/download && unzip openclaw-thumbnail-forge.zip

Download openclaw-thumbnail-forge.zip

SKILL.md About

---
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
bash scripts/check_deps.sh
```

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

```bash
pip install Pillow
```

## Workflows

### 1. Pick the best candidate frames from a video

```bash
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 <seconds>` — sampling interval (default 2.0)
- `--top <N>` — 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 <float>` — reject blurry frames (Laplacian variance floor)

### 2. Compose a finished thumbnail from a frame

```bash
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:

```bash
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

```bash
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

```bash
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

```bash
# 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`.

_meta.json Metadata

{
  "ownerId": "kn7fkwsa5knkdkkachj1p7rwr9843xts",
  "publishedAt": 1777704936117,
  "slug": "openclaw-thumbnail-forge",
  "version": "0.1.0"
}