openclaw-thumbnail-forge

v0.3.0

一个实用的视频缩略图生成工具。无需 API 密钥、不依赖在线服务、不使用 AI，通过本地 CLI 工作流即可生成创作者通常在 Photoshop 或 Canva 中制作的专业级缩略图。

该技能的功能

• scripts/check_deps.sh — 检查 ffmpeg、ffprobe、python3 是否安装，并确认 Python 的 Pillow 包可导入。
• scripts/pick_frames.py — 从视频中提取候选帧，根据清晰度、亮度、对比度以及 ffmpeg 场景变化得分进行综合评分排序。输出前 N 个最佳帧为 PNG 文件，并生成一份 JSON 报告。
• scripts/compose_thumbnail.py — 将一张原始帧转换为完成的缩略图，包含粗体标题文字、副标题、渐变条、可选的 logo 叠加和自动对比度增强。支持自定义字体与配色方案。
• scripts/export_sizes.py — 一键将完成的缩略图导出为所有常见平台尺寸（YouTube、Shorts、Instagram 正方形、X/Twitter、LinkedIn）。
• scripts/make_variants.py — 生成同一缩略图的四个 A/B 测试可用版本（不同配色、文字位置、对比度水平），用于点击率测试。v0.3.0 新增功能：添加 --auto-pick 参数后，会立即用 score_thumbnail.py 对四个版本进行评分，将得分最高的版本复制到 <output_dir>/winner.png，并生成包含完整排名的 winner.json。一命令，一次决策。
• scripts/score_thumbnail.py（v0.2.0 新增）—— 对一个或多个已完成的缩略图进行六项客观视觉指标评分，并选出最可能引发点击的版本。为每个缩略图提供 0–100 的点击可能性分数，并说明是哪些指标驱动了结果。

该技能不做的事

为避免误解，请注意以下限制：

• 不使用 AI 主体检测或人脸识别。帧选择与点击可能性评分基于统计方法，而非语义理解。
• 不下载字体、素材图片或其他远程资源。您需自行提供字体路径，或使用系统默认字体。
• 不执行 OCR、语音转录或生成式编辑。
• 不写入您指定目录以外的位置。
• 点击可能性评分器是一个确定性启发式算法，非真实机器学习点击率模型。它遵循广泛认可的缩略图设计原则（冲击力、焦点突出、色彩强调、文字带、亮度、边缘密度）。请将其视为辅助判断工具，而非保证。

所需依赖

bash scripts/check_deps.sh

验证 ffmpeg、ffprobe、python3 是否已安装，并确认 PIL（Pillow）可被导入。Pillow 是唯一的 Python 依赖：

pip install Pillow

使用流程

1. 从视频中挑选最佳候选帧

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

每 2 秒提取一帧，对每帧进行评分，保留得分最高的 10 帧，保存为 frames/frame_001.png 至 frames/frame_010.png，并生成 frames/report.json 包含各帧评分详情。

可调参数：

• --interval <秒数> — 采样间隔（默认 2.0）
• --top <N> — 保留的最高分帧数（默认 10）
• --min-brightness <0-255> / --max-brightness <0-255> — 排除过暗或过曝的帧
• --min-sharpness <浮点数> — 排除模糊的帧
• --relax-on-empty（v0.2.0 新增）— 若无任何帧通过筛选条件（如视频过短、整体过暗、单一静态画面），则自动重试一次，使用极宽松阈值，确保至少获得一个候选帧

对于时长小于 2 * interval 的视频，脚本现在会自动降级为均匀采样 3 个帧，而非返回空结果。

2. 从帧生成最终缩略图

python3 scripts/compose_thumbnail.py frames/frame_003.png thumb.png \
  --title "10 ffmpeg 技巧我早知道就好了" \
  --subtitle "一次实用之旅" \
  --color-scheme bold-yellow \
  --position bottom

内置配色方案：bold-yellow（醒目黄）、clean-white（纯净白）、red-alert（红色警报）、cool-blue（冷蓝）、tech-green（科技绿）。每种方案定义标题颜色、描边色、阴影及渐变条透明度。

位置选项：top（顶部）、bottom（底部）、center（居中）。脚本会自动适配标题大小以适应可用宽度，并在文字后添加可读性良好的渐变条，确保缩略图在小尺寸下仍清晰可读。

可选 logo 叠加：

python3 scripts/compose_thumbnail.py frames/frame_003.png thumb.png \
  --title "你的标题" \
  --logo logo.png --logo-corner top-right --logo-scale 0.12

v0.2.0 版本改进：若输入 --title ""，脚本将拒绝处理并提示错误（不再静默生成无文字缩略图）；若输入图像损坏或无法读取，也会打印清晰错误信息，而非抛出 Python 调用栈。

3. 一次性导出至所有平台尺寸

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

生成以下文件：

• out/youtube_1280x720.png
• out/shorts_1080x1920.png
• out/instagram_1080x1080.png
• out/x_1200x675.png
• out/linkedin_1200x627.png

4. 生成 A/B 测试版本

python3 scripts/make_variants.py frames/frame_003.png ./variants/ \
  --title "10 ffmpeg 技巧" \
  --subtitle "一次实用之旅"

生成 4 个不同配色与布局的版本，适合点击率对比测试。

v0.3.0 新增功能：添加 --auto-pick 参数，可在生成版本的同时立即选出最优者：

python3 scripts/make_variants.py frames/frame_003.png ./variants/ \
  --title "10 ffmpeg 技巧" \
  --subtitle "一次实用之旅" \
  --auto-pick

此命令将生成 4 个版本，并将得分最高的版本复制为 ./variants/winner.png，同时生成 ./variants/winner.json 包含完整评分排名。原始的 variant_*.png 文件仍被保留，以便您手动选择其他版本。

5. 对完成的缩略图进行点击可能性评分（v0.2.0 新增）

python3 scripts/score_thumbnail.py variants/*.png

对每个缩略图进行六项客观视觉指标评分，并输出按得分排序的列表，其中胜出者会被高亮显示：

Skill: Openclaw Thumbnail Forge

版本：0.3.0

分块：2/2

评分指标说明

每个子得分均归一化至 [0, 100]，加权系数为 0.18 / 0.22 / 0.15 / 0.20 / 0.12 / 0.13。最终 click_score 范围为 [0, 100]。

当输入两个或更多缩略图时，脚本还会输出解释信息：在每对比较中，是哪个指标导致了得分差距，以及具体差距大小。

JSON 模式

python3 scripts/score_thumbnail.py variants/*.png --output ranking.json --json

完整流程示例

# 1) 找出最佳候选帧
python3 scripts/pick_frames.py my_video.mp4 ./frames/ --top 5 --interval 1.5

# 2) 从最佳帧生成四个变体
python3 scripts/make_variants.py frames/frame_001.png ./variants/ \
  --title "你的标题" --subtitle "可选副标题"

# 3) 对变体进行评分并选出点击率最高的方案
python3 scripts/score_thumbnail.py variants/*.png --output ranking.json

# 4) 将选定的变体导出为各平台所需尺寸
python3 scripts/export_sizes.py variants/variant_b_clean_white_top.png ./out/

退出码

安全特性

• 所有 Python 辅助脚本使用 subprocess.run 并以参数列表形式调用（从不使用 shell=True），并通过严格的正则表达式白名单拒绝包含 shell 元字符的输入/输出路径。
• 该工具不会读取或写入用户指定路径以外的任何位置。
• 不读取任何环境变量以获取凭证。无需令牌、密钥或 API 密钥。
• 不进行任何远程调用。仅调用本地安装的 ffmpeg 和 Python 的 Pillow 库。

已知限制

• 帧评分和缩略图点击可能性评分基于启发式规则，非 AI 模型。不了解“主体面部是否可见”等语义信息——仅优化客观图像质量信号及视觉层级代理指标。
• 若未提供 --font 参数，默认使用系统默认字体。若找不到可用字体，脚本将回退到 Pillow 的位图字体，外观较为朴素。建议使用 --font 以获得更佳排版效果。
• compose_thumbnail.py 不支持自动背景移除。如需主体独立，请先在其他工具中完成抠图操作。

v0.3.0 更新内容

• scripts/make_variants.py 现在支持 --auto-pick 选项。生成四个 A/B 变体后，自动运行 scripts/score_thumbnail.py 进行评分，并将得分最高的变体复制到 <output_dir>/winner.png，同时生成 <output_dir>/winner.json 包含完整排名与推理过程。移除了典型工作流中的手动第二步。
• 更稳健地解析评分器的嵌套 winner 块（winner.winner_file, winner.ranked[]），若未来评分器结构发生变化，会自动回退至原始的 results[] 数组。
• 未更改现有 CLI 参数；--auto-pick 仅为新增功能。四个变体文件名（variant_a_...png, variant_b_...png, variant_c_...png, variant_d_...png）保持不变。

v0.2.0 更新内容

新功能

• scripts/score_thumbnail.py —— 可确定性的本地点击可能性评分器。对一个或多个已完成的缩略图，基于六个视觉指标（punch、focal pop、color punch、text band、brightness、edge density）进行评分并排序。纯 Pillow + 标准库实现，无机器学习，无远程调用。

修复问题

• compose_thumbnail.py 和 make_variants.py 现在会对空 --title "" 输入抛出明确错误，而非静默生成无文字缩略图。
• compose_thumbnail.py 现在捕获 PIL.UnidentifiedImageError 异常（针对损坏或非图像输入），并输出简洁的一行错误信息，避免泄露 Python 堆栈跟踪。
• pick_frames.py 在 ffprobe 对非视频输入失败、视频时长为零或输入路径包含 shell 元字符时，正确返回退出码 2（而非 0）。使依赖退出码的流水线能正常工作。
• pick_frames.py 不再对极短片段（< 2 * interval）静默生成零帧。现在会回退为在时间上均匀采样 3 个帧。新增 --relax-on-empty 标志，当默认宽松阈值仍无法选出候选帧时，将尝试一次更宽松的重试。
• 移除了 probe_duration 中冗余的双重 ffprobe 调用。

无破坏性变更：现有 CLI 参数、输出文件名、评分公式和判定阈值均保持不变。v0.1.0 的脚本和流水线仍可继续使用。

许可证

MIT。详见 LICENSE。