workbuddy_skills/video-capture/SKILL.md

name, description, version, updated_at, deployment, agent_created

name	description	version	updated_at	deployment	agent_created
video-capture	视频解析独立工具：把一个视频落到本地，并按规范抽成「有信息量的关键帧 ＋ 时间线」。 两件事：① 取视频（本地文件 / 直链 URL / 平台页经浏览器下到本地）； ② 按规范抽帧 —— 双因素 ＋ 首尾 ＋ 补帧（画面 scene 0.3 ＋ 字幕区 crop 后 0.1 ＋ 低阈值 0.05 补漏 ＋ 首尾帧 ＋ 间隔 >5s 补中点；逐点 -ss；保持原分辨率）， 产 c_<四位序号>_<真实秒数>s.jpg ＋ frame_times.json。 触发场景：分析视频、把这个视频抽帧、拆一下这条视频的画面、提取关键帧、视频解析、 取视频、下载视频、视频拆解、字幕提取、画面反推、视频取画面。	1.0	2026-10-11	global	true

video-capture · 取视频 ＋ 抽帧（独立技能）

把「一个视频」变成「一批有信息量的关键帧 ＋ 时间线」，用于视频理解、分镜拆解、画面反推提示词、 字幕转录、竞品 demo 拆解、视觉参考。

一、什么时候用

• 用户说「分析 XXX 视频」「把这个视频抽帧」「拆一下这条视频的画面」「提取关键帧」「视频解析」。
• 竞品 demo 要拆画面、参考视频要取画面、教程视频要做图文梳理。

二、两步用法

第一步 · 取视频

1、本地文件（直接登记 ＋ 校验）：

python scripts/fetch_video.py --file D:/a.mp4 --out ./video

2、直链媒体 URL（.mp4/.mov/.webm/.m4v/.mkv）：

python scripts/fetch_video.py --url https://host/x.mp4 --out ./video

3、平台页视频（B站／抖音／YouTube 等）：先用浏览器工具把视频下到本地，再按第 1 条传 --file。 本技能自带的是「落地」这一步；平台页的解析走浏览器打开站点 → 解析 → 下载， 登录态与会员态由用户自己在浏览器里完成（会员登录属用户凭据，不代输）。

• 红线：只处理用户有权分析的素材；遇到登录墙就停下来问用户； ⛔ 不绕过登录／验证码／风控；⛔ 不调用任何付费接口。
• 平台解析接口常有速率限制（连发会 429／503）：按约 16 秒间隔分批，失败重试 ≤3 次。

第二步 · 抽帧（双因素 ＋ 首尾 ＋ 补帧）

python scripts/extract_frames.py --video ./video/a.mp4 --out ./frames

• 产出 frames/c_<四位序号>_<真实秒数>s.jpg ＋ frames/frame_times.json （记时长 / 分辨率 / 字幕裁剪区 / 三档阈值 / 帧表）。
• 可选参数：--crop "720:240:0:720" 指定字幕区；--max-gap 5 长间隔补帧阈值； --thresholds 0.3,0.1,0.05 三档阈值。
• 字幕区默认取底部 15%；横屏 1080p 可显式 --crop "1920:162:0:918"， 竖屏 720×960 用 --crop "720:240:0:720"。先抽一帧确认字幕实际位置再定 crop。
• 逐点 -ss 抽帧慢（700+ 帧约 7 分钟）⇒ 放后台任务里跑。
• ffmpeg 版本兼容：脚本已自带新旧写法兼容（优先 -fps_mode vfr，跑不出结果再退回 -vsync vfr） ⇒ ffmpeg 5.x / 9.x 都能直接跑。本机是 ffmpeg 9.0.1，可直接调脚本； （依据 2026-10-11 实测：旧写法只认 -vsync，而 9.0.1 已移除它 ⇒ 三路 scene 检测全失败、整支视频只出 3 帧， 当时执行会话只能另存一份「逐字同算法的本地副本」才跑通 ⇒ 两套口径。已修。）

🔴🔴 抽帧只走 scripts/extract_frames.py：这个脚本就是下面那套铁律的实现，也是唯一入口。

• 写自己的 ffmpeg 抽帧命令会把规范丢掉 —— 尤其 -vf "fps=1/N" 这类固定节奏抽样： 规范 §六 用三版实测否决过它（fps=1 浪费 56% 帧，且画面静止但字幕换句的帧全丢）。
• 保持原分辨率：scale=640:-1 这类缩图会让帧上的字幕读不清，后续 OCR / 视觉读取全废。
• 依据（2026-10-11 实测）：一次「取视频 ＋ 抽帧 ＋ 梳理」的任务没加载本技能， 自己写了 ffmpeg -vf "fps=1/N,scale=640:-1" 的脚本 ⇒ 22 个视频的关键帧按规范全部返工。

三、算法铁律

细则与实测案例以 references/视频抽帧与字幕规范.md 为准（本技能的权威源）。

1、画面变化：select='gt(scene,0.3)' —— 抓镜头切换 / 画面突变。 2、字幕变化：字幕区 crop 后 select='gt(scene,0.1)' —— 抓「画面静止但字幕换句」。 3、低阈值补漏：select='gt(scene,0.05)' —— 补 0.05~0.3 之间的中等缓变盲区（标准步骤，非可选补救）。 4、首尾帧：首帧 0s ＋ 尾帧 时长-0.3s（-ss 时长 会超界）。 5、长间隔强制补帧：排序合并去重后，任一段间隔 >5s 就在该段中点补 1 帧（物理上无盲区）。 6、逐点 -ss 抽帧：select='eq(t,xx)' 精确时间匹配浮点误差大、命中率极低，用它。

核心原则：只抽「有信息量的帧」—— 画面变化点 ＋ 字幕变化点 ＋ 首尾帧 ＋ 长间隔补帧； 帧数随内容变化，⛔ 不按固定节奏凑数。

四、产物与命名

🔴 落点约定：一个账号 / 一个系列 ＝ 一个专属文件夹，三类产物同放其中（2026-10-11 用户令）。 命名格式 <平台名>_<账号ID>_<内容方向> —— 三段都要有：平台用来分组（同平台的账号排在一起）、 账号 ID 用来认账号与复查、内容方向用来认这一批采的是什么。

例：B站_44479620_AI生成界面与设计、抖音_1234567_品牌设计

<平台名>_<账号ID>_<内容方向>/
├── 视频/                    ← 本体（BV 号.mp4）
├── 关键帧/<BV号>/           ← c_<序号>_<真实秒数>s.jpg ＋ frame_times.json
├── 梳理/                    ← 逐视频的教程与方法 / 提炼稿
└── 清单与索引-<日期>.md      ← 全量投稿清单 ＋ 入选索引

• 三类产物（视频本体 / 关键帧 / 提炼内容）一律进这同一个文件夹，⛔ 不散到工作区各处。

• 平台名写站点通称（B站、抖音、小红书、视频号、YouTube、TikTok）；账号 ID 用平台上的原始 ID（B 站＝UID）。

• 内容方向写成一句能认主题的话（例 AI生成界面与设计、短视频拍摄与剪辑），⛔ 不写「合集」「系列」这种认不出的词。

• 同一个账号的另一个内容方向 ⇒ 另建一个文件夹（名字里第三段不同），并列摆放。

• 抓另一个账号 ⇒ 同样另建（第二段换 ID；同平台时第一段不变）。

• 过程件（脚本、原始 JSON）放该文件夹下的 tmp-scrape/（或等价子目录），保留原始数据。

• 该文件夹落在哪，由调用方的项目约定决定（本项目＝ 执行会话/目标-<简称>-<短哈希>/ 之下）。

• 帧图：<out>/c_<四位序号>_<真实秒数>s.jpg（例 c_0001_0s.jpg、c_0002_3.534s.jpg）。 时间戳保留 scene 检测输出的原始浮点精度，便于按帧对应视频时刻。

• 帧表：<out>/frame_times.json —— frames[] 逐条含 index / time / file。

五、时间区间划分（每帧代表的时间段）

• 相邻帧中点划分（Voronoi）：帧 i 代表 [中点(i-1,i), 中点(i,i+1)]。
• 首帧从 0 起、尾帧到视频结束；用于分镜时间轴、字幕时间线、画面与台词对应。

六、字幕与转录

• 平台视频的字幕常是烧录在画面上的（非独立字幕轨）⇒ 从帧画面读（OCR／视觉读取）。
• 字幕区 scene 检测已保证每个换句时刻都有一帧（含画面静止时）。
• 转录产出 字幕稿_日期.md，格式＝时间线表（时间 ｜ 台词 ｜ 帧文件）。
• 若平台的字幕接口可用（返回非空），优先直接取轨；接口返回空属信源限制，如实注明后走画面读取。

七、边界

• ⛔ 不抓平台页内视频（本技能只做「落地 ＋ 抽帧」）；平台页请先用浏览器工具下到本地。
• ⛔ 不调付费接口。
• 只对用户有权分析的素材使用；版权归原作者。
• ffmpeg / ffprobe 需在本机 PATH 上（脚本除此之外只用 Python 标准库）。

八、归属

算法与铁律来自 aigc-idea-impression 技能的《视频抽帧与字幕规范》（2026-08-30 实测沉淀）， 本技能是它的独立打包。来源与改动记录见 ATTRIBUTION.md。