openclaw-thumbnail-forge

v0.3.0

一款实用的视频缩略图生成工具。它能构建出创作者通常在 Photoshop 或 Canva 中手动制作的专业级缩略图，但整个流程完全本地化、通过 CLI 执行，无需 API 密钥、不依赖任何在线服务，也无任何 AI 组件。

该技能的功能

• scripts/check_deps.sh — 验证 ffmpeg、ffprobe、python3（以及 Python 包 Pillow）是否已安装。
• scripts/pick_frames.py — 从视频中提取候选帧，并依据综合评分（融合清晰度、亮度、对比度及 ffmpeg 场景变化检测得分）对帧进行排序。输出 Top-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 对四个变体打分，将最高分变体复制至 /winner.png，并写入包含完整排名信息的 winner.json。一步完成，一键决策。
• scripts/score_thumbnail.py（v0.2.0 新增）— 对一个或多个成品缩略图，在六项客观视觉指标上进行评分，并选出最可能带来点击的版本。为每张缩略图输出一个数值化的点击可能性得分（0–100），并解释各项指标对该结果的贡献。

该技能不具备的功能

为明确预期，以下功能**不提供**：

• 不使用 AI 主体检测或人脸识别。帧排序与点击可能性评分均为统计型方法，非语义理解。
• 不下载字体、图库照片或任何远程资源。字体路径需用户自行提供，或使用系统默认字体。
• 不执行 OCR、语音转录或生成式编辑。
• 不会向用户指定目录之外的路径读写任何文件。
• 点击可能性评分器是一个确定性启发式算法，而非真实机器学习 CTR 模型。它建模了业界广泛引用的缩略图设计规则（冲击力、焦点突出、色彩冲击、文字带、亮度、边缘密度）。请将其输出视为辅助决策的“决胜参考”，而非绝对保证。

必要依赖项

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 — 保留的最高分帧数（默认 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 Tricks I Wish I Knew Sooner" 
  --subtitle "A practical tour" 
  --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 "Your Title" 
  --logo logo.png --logo-corner top-right --logo-scale 0.12

v0.2.0 起，脚本将拒绝空标题 --title ""（不再静默生成无文字缩略图），并在输入图像损坏或无法读取时打印清晰错误提示（而非泄露 Python traceback）。

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 Tricks" 
  --subtitle "A practical tour"

生成 4 种不同配色与文字位置的变体，适用于点击率分流测试。

v0.3.0 新增：--auto-pick 可在生成变体的同时立即选出最优者，一条命令完成：

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

该命令除生成 4 个变体外，还将最高分变体复制为 ./variants/winner.png，并写入含完整排名与分析的 ./variants/winner.json。原始四个 variant_*.png 文件保持不变，便于您人工复核并选择其他变体。

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

python3 scripts/score_thumbnail.py variants/*.png

对每张缩略图在六项客观指标上评分，并输出带高亮胜出者的排序列表：

每个子评分项均归一化至 [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 "Your Title Here" --subtitle "Optional 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 元字符的路径。
• 本技能仅读写用户显式指定的输入/输出路径，绝不越界。
• 不读取任何环境变量用于凭据认证。无需任何 token、密钥或 API key。
• 不发起任何形式的远程调用。仅调用本地安装的 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 进行评分，将最高分变体复制至 /winner.png，并写入含完整排名与推理过程的 /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 — 确定性本地点击可能性评分器。基于六项视觉指标（冲击力、焦点突出、色彩冲击、文字带、亮度、边缘密度）对一张或多张成品缩略图评分并排序。纯 Pillow + 标准库实现，无机器学习、无远程调用。

缺陷修复

• compose_thumbnail.py 与 make_variants.py 现在会对空 --title "" 报出清晰错误，而非静默生成无文字缩略图。
• compose_thumbnail.py 现在可捕获 PIL.UnidentifiedImageError（输入图像损坏或非图像格式），并打印简洁单行错误，而非泄露 Python traceback。
• 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。