---

name: "video-to-keyframes" description: "Extracts video frames, detects cuts/segments, selects candidate keyframes, and generates review HTML galleries. Invoke when users ask for keyframes/cuts/segmentation/storyboard screening."

视频转关键帧（video-to-keyframes）

把用户提供的视频转成“候选帧池 → 转场/分段 → 候选关键帧集 → 复筛画廊页”，并把产物落盘到当天文件夹，方便后续分镜与生成。

何时调用

• 用户提供视频并说：抽帧/拆帧/关键帧/候选关键帧/镜头拆分/转场点/分段/分镜初筛
• 用户希望按固定工作流落盘，需要可复现的目录与文件（frames.json、cuts.json、segments.json、gallery.html 等）

依赖

• Python 3.10+
• numpy
• opencv-python

输入

• 视频文件路径（必填）
• 当天文件夹路径（可选，默认用视频所在目录；推荐 YYYY-MM-DD）
• 抽帧间隔（建议：30s≈1fps；变化快≈2fps）

输出（固定规范）

在 <当天文件夹> 下生成：

• <当天文件夹>\_frames_<视频名>_<间隔>\：候选帧池目录
  • f_*.jpg：抽帧图片
  • frames.csv / frames.json / top_keep.json / meta.json
  • \_keyframe_candidates\：候选关键帧集目录
    • cuts.json：转场点
    • segments.json：分段与每段代表帧
    • segments_gallery.html：分段可视化（每段1张代表帧）
    • gallery.html：候选关键帧画廊（逐个复筛）
    • candidates.csv / candidates.json
    • selected.txt：人工/AI复筛后的最终候选ID（每行一个 cand_id）
    • prompt_pack.html：复筛+提示词协作页（夜间模式，一键复制）
• <当天文件夹>\<视频名>_拆分.txt：汇总（转场点、分段、每段代表帧文件名）

一键运行（推荐）

python .\skills\video-to-keyframes\resources\scripts\run_video_workflow.py "<视频路径>" --day-folder "<当天文件夹>" --every-seconds 0.5 --max-frames 600

注意：一键运行只负责产出文件，不等于完成复筛；必须打开 gallery.html 做人工/AI语义复筛，并把最终选择写入 selected.txt。

复筛要点（简版）

• 先看 segments_gallery.html：确认每段代表帧是否合理、分段是否过碎
• 再看 gallery.html：挑 6-12 张最“代表内容且可复现”的帧（不要只挑清晰但信息弱的帧）
• 将 cand_id 写入 selected.txt（每行一个三位数字或逗号分隔均可）