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