视频提取解析器
按下方流程直接用；不会开口就看〇的照抄句。
〇、不会开口？照抄这几句
- 「解析这段视频，给我一份结构化的总结报告」
- 「把这个课程视频转成文字稿，并标出时间轴」
- 「把这段视频做成一份可以反复看的 HTML 学习页」
- 「视频里讲了什么？帮我提炼要点和关键画面」
一、什么时候会被唤起
显式：你说「视频识别」「解析视频」「视频转文字」「视频学习页」等相关词，或直接说技能名。
隐式（多轮对话里这样也会被唤起，不用点名）：
- 你发来一个本地视频文件，说「帮我看看这个讲了什么」
- 你说「把这段录屏整理成笔记」
- 你问「这个教程视频的核心步骤是什么」
二、不归我管（先说清楚）
- 不解析直播流；视频链接（抖音优先，快手/B站/小红书等只要浏览器能正常播放）会先下载到本机再处理；需登录才能看的抓不到
- 不做视频剪辑、配音、去水印
- 不翻译外语视频（可先转写再单独翻译）
- 不保证 100% 准确率：准确率取决于识别模型档位，短句/清晰人声更准
- 不替代专业字幕组或剪辑软件
信任与隐私：整个管线 100% 跑在你本机——ffmpeg、识别模型、看图理解都是本地进程，视频和音频从不离开你的电脑，也不需要任何云账号或 API Key。唯一一次对外访问是首次下载识别模型（走国内 hf-mirror 镜像），之后完全离线可用。
三、四种调用方式（任选一种）
| 方式 | 适合 | 怎么调 |
|---|---|---|
| ① 聊天说一句话 | 绝大多数情况 | 直接把视频文件发我，并说明要哪种产出 |
| ② 命令行跑脚本 | 要精确复现 | python scripts/video_insight.py --help 看参数 |
③ --out PATH |
要存档 | 指定输出目录，另存三件套，不覆盖原视频 |
| ④ 环境自检 | 首次跑前 | python scripts/check_env.py 看缺什么依赖 |
| ⑤ 直接发抖音链接 | 手头只有链接 | 会先下载到本机再照常本地解析（配法见 references 手册） |
> 不想记参数？ 直接用大白话说需求即可（见 §〇 照抄句）——聊天就是向导，命令行只给需要精确复现的人用。
四、输入输出契约
输入：一个本地视频文件路径（mp4/mov/mkv/webm 等）；也可直接给抖音链接，会先下载到本机再解析。
输出（三选一或全要）：
- transcript.txt / transcript.srt / transcript.json：逐字文字稿，带时间戳
- timeline.md：时间轴 + 关键画面标注
- report.html：自包含可交互学习页（文字稿+画面缩略图，双击即看）
--json 时字段固定，同一视频两次跑结果一致（模型版本固定时）。
五、能力边界（量化）
| 能做 | 不做 |
|---|---|
| 本地视频 → 文字稿+时间轴 | 在线/流媒体视频 |
| 抽关键帧并由我看图理解画面 | 视频剪辑/去水印 |
| 产出 HTML 学习页（图文混排） | 外语字幕翻译 |
| 全程本地、零云、隐私不出本机 | 承诺 100% 准确率 |
六、标准工作流程
- 收视频：确认是本地文件，记录路径与格式
- 抽音轨：用 ffmpeg 抽音轨为 wav（imageio-ffmpeg 自带二进制，免安装）
- 抽帧：按时间间隔或场景变化抽关键帧（默认均匀抽稀，可
--max-frames限数） - 转写：本地 Whisper 模型把音轨转成带时间戳文字稿（tiny/small/medium 档可选）
- 读画面：把关键帧交给平台的看图能力，理解每一段在讲什么
- 综合：把「文字稿 + 画面理解」对齐，提炼结构化的要点
- 产出：按你要的三种格式之一或全部生成
- 自检：核对时间轴与画面是否对应，标注不确定处
（核心巧思：平台有「看图」能力但没有「看视频」能力，所以把视频拆成「音轨+关键帧」两步降维处理——这正是本技能能离线、零云跑通的关键。）
七、演示（含「试一试」）
试一试（5 分钟上手）：装好依赖后，直接把本地视频发我说「转成文字稿+时间轴」，我替你跑；或命令行 python scripts/video_insight.py 视频.mp4 --out ./out，几十秒后 ./out 里就有三件套。
真实产出长这样（节选）：
> 文字稿（transcript.srt，带时间戳）
> 00:00:12 主讲人打开报价表，画面显示投影面积计算列
> 00:00:45 强调「颗粒板 368、多层板 448」两种单价
> 00:01:30 演示用面积×系数快速估算总价
> 00:02:05 切到封边工艺对比页
> 00:03:10 给出最终报价区间并说明浮动因素
>
> 时间轴（timeline.md）
> [00:12] 报价表截图 → 讲了面积计算字段
> [00:45] 单价对比图 → 两种板材价格差异
> [01:30] 估算演示 → 给出速算公式
>
> HTML 学习页（report.html）：文字稿 + 对应画面缩略图，图文混排，离线双击即看。
另一种场景（会议录屏）：同样流程，产出「谁在哪一分钟讲了什么」的时间轴，方便会后回看与做纪要。
模型档位怎么选（实测参考：38 秒 / 清晰人声视频，CPU int8）：
| 档位 | 首次下载 | 转写耗时 | 准确率 | 适合 |
|---|---|---|---|---|
| tiny | ~75MB | ~9s | 一般（实测 CER≈16%） | 快速预览、超长视频 |
| small | ~240MB | ~30s | 良好（明显更准） | 日常首选（默认） |
| medium | ~770MB | ~90s | 更好（最准） | 专业 / 嘈杂环境 |
> 准确率随档位上升但更吃 CPU；--lang zh 锁定语言可再提一截。实测场景：单人清晰讲授很准；多人抢话 / 方言 / 强背景音乐明显下降（建议 --model medium 并回看原片核对）；5 分钟本地视频全程约 25 秒。格式支持 mp4/mov/mkv/webm/m4v/avi/flv/wmv/ts/mpeg 等 11 种。
端到端案例（抖音链接 → 可看的 HTML 学习页，3 步）：
① python scripts/douyin_fetch.py "v.douyin.com/xxx/" --out-dir ./dl → 得到 ./dl/<id>.mp4（CDP 免登录下载）；
② python scripts/video_insight.py ./dl/<id>.mp4 --out ./out --model small → 产出 transcript.srt / timeline.md / frames/；
③ 逐张看 frames/*.jpg 与 timeline.md 对齐，把结论填进 report.html → 得到可交互学习页。
最佳实践（少踩坑）
① 长视频先用 --model tiny 预览；② 重要结论回看原片核对；③ 想存档就 --out 指定目录（不覆盖原视频）；④ 中断了加 --resume 续跑，不白忙；⑤ 多人对话/嘈杂场景换 --model medium 提准确率；⑥ 链接抓不到就改用 DY_FETCH_CMD 配成熟下载器。
八、脚本与错误码
python scripts/check_env.py # 环境自检：缺什么依赖一目了然
python scripts/video_insight.py --help # 全部参数
python scripts/video_insight.py 视频.mp4 --out ./out # 默认产出三件套
python scripts/video_insight.py 视频.mp4 --no-transcribe # 只抽帧+读图，不转写
python scripts/video_insight.py 视频.mp4 --resume # 断点续跑：跳过已抽的音轨/帧，只补产出
python scripts/douyin_fetch.py "v.douyin.com/xxx/" --out-dir ./dl # 抖音链接 → 本地文件
链接下载：给视频链接时自动调 scripts/douyin_fetch.py 先下到本机再解析；后端为可插拔注册表（CDP 嗅探 / 自定义命令），CDP 默认开启、无需登录 Cookie，原理是「浏览器能播就能抓」——抖音之外平台只要网页能播也可尝试（已验证：抖音、B站）。支持批量：位置参数给多条链接，或 --links-file links.txt（每行一条，# 为注释），单条失败不打断整批并在末尾出汇总。边界：需登录/付费才能看的、直播流、纯 App 内无网页版的抓不到；平台改版可能使嗅探失效（报 E804，改 DY_FETCH_CMD 即可）。配法与排错见 references/06-完整实战手册.md。
| 错误码 | 现象 | 怎么改 |
|---|---|---|
| E701 | 找不到 ffmpeg | pip install imageio-ffmpeg；脚本会自动定位其自带二进制 |
| E702 | 模型下载失败/超时 | 检查网络；国内走镜像；或手动下载后放缓存目录；脚本已带自动重试 |
| E703 | 视频文件无法解码 | 确认格式受支持（mp4/mov/mkv/webm）；换播放器能开的源文件 |
| E704 | 中文路径导致处理失败 | 脚本已自动复制到临时英文路径；如仍失败，把视频放到纯英文目录 |
| E301 | 文件不可读/被占用/非文件 | 解除占用、确认传的是文件不是文件夹，换个位置再试 |
| E302 | 文件过小/可能损坏 | 实际只有几字节，重新下载或拷贝完整视频 |
| E303 | 抽音轨/抽帧超时 | 文件过大或已损坏；换更小文件，或调大 --ffmpeg-timeout |
| E304 | 语音转写超时 | 边转边看表，超时即中止；换 --model tiny 或先 --no-transcribe |
| E801/E802 | 链接下载：无浏览器 / 缺 websocket-client | 装 Edge 或 Chrome；pip install websocket-client |
| E803–E806 | CDP 嗅探未成 / 两个后端都不可用 | 关掉同名浏览器重试；或设 DY_FETCH_CMD；或先用手机下到本地 |
| E101 | 必填参数没给 | 至少传一个视频路径；--help 看参数 |
| E201 | 文件不存在 | 核对路径；Windows 路径含空格整体加英文双引号 |
（更多通用码见 scripts/skillkit.py 的 BASE_CODES）
九、稳定性设计
| 场景 | 处理方式 |
|---|---|
| 开工前预检 | 先验证文件存在、是文件、可读、非空（E301/E302），在调用 ffmpeg 前就把常见误用拦下，给普通人看得懂的提示 |
| 参数写错/漏填 | 直接给错误码 + 一行改法，不用重来 |
| 文件被占用/不存在 | 报 E201/E301，告诉你哪一步断的，不静默失败 |
| ffmpeg 超时保护 | 每次 ffmpeg 调用带 --ffmpeg-timeout（默认 600s）；卡死/损坏文件主动终止，不僵死 |
| 转写超时保护 | 边转写边看表：faster-whisper 逐段产出时检查耗时，超 --stage-timeout 立即中止并给出替代方案，不做无谓等待 |
| 模型下载自动重试 | 首次下载遇网络抖动（502/超时）自动重试 3 次，不卡死；失败才报错 |
| 无音轨精准诊断 | 先探测是否真有音轨：纯画面视频报「no_audio_stream」，编码不支持报「decode_failed」，不再笼统返回 False |
| 长视频 | 帧数自动抽稀，避免产出过大 |
| 断点续跑 | --resume：已有 audio.wav / frames 则跳过重新抽取，只补未完成产出，省时间不怕中断 |
| 中途被打断 | 顶层兜底只吐「人话 + 方向」，不吐裸堆栈；已算完的部分照样给你 |
| 同一视频重复跑 | 幂等，结果一致；只读输入，绝不改你的原文件 |
十、FAQ（按高频排序，一条答完）
- 问：视频会不会被上传？ 不会。全程本地处理，ffmpeg 与识别模型都在你机器上跑，视频和音频不出本机，也不需要任何云 API Key。
- 问：首次为什么慢？ 首次要下载识别模型（约 470MB，默认自动走国内镜像，比直连快；想强制直连才加
--no-mirror）；下载一次后永久缓存，之后纯本地、可离线，后续秒级。 - 问：准吗？怎么更准？ 清晰人声/短句很准，嘈杂、方言、快语速会降。提升：①
--model medium；② 用清晰少噪音轨；③ 语速放慢、别多人抢话；④--lang zh锁语言；⑤ 关键结论回看原片。 - 问：要装什么？
pip install imageio-ffmpeg faster-whisper ctranslate2（脚本check_env.py会逐项核对）。 - 问：处理失败了怎么查？ 看错误码：E701 缺 ffmpeg、E702 模型下载失败（已带自动重试）、E703 视频无法解码、E704 中文路径、E301 文件不可读、E302 文件损坏、E303 抽帧超时、E304 转写超时、E201 文件不存在——每条都写了「现象+怎么改」。
- 问：处理到一半断了 / 卡住了怎么办？ 脚本带超时保护（ffmpeg 与 whisper 都有看门狗），不会真卡死；若中断，重跑加
--resume会跳过已抽的音轨和帧、只补产出，不白忙。真卡死按 Ctrl+C 也能安全退出，已产出的部分文件保留。
实测记录（真实跑过，非理论）：抖音短链 → 18.6 MB mp4（含音轨，免登录）；B站 BVxxxx → 5.1 MB，DASH 音视频自动合流（AV1+AAC，2 分 54 秒）；本地解析 5 分 11 秒 / 1280×720 视频 → 抽帧 4.85s + 转写 17.55s = 23 秒出 136 段；批量 --links-file 两条链接 → 2/2 成功，单条失败不打断整批。
十一、反模式（别这么干）
- 别指望抓「需登录才能看」的内容——只抓浏览器能直接播放的公开视频。
- 别指望 100% 准确率，关键结论要回看原视频确认。
- 别拿输出当唯一依据，重要画面以原视频为准。
- 别在未装依赖时直接跑脚本——先
check_env.py自检。 - 别在超长视频上硬刚最高档模型——先用
--model tiny预览确认内容值得，再升档，省时间也省 CPU。
十二、目录结构 + 下一步
SKILL.md（主入口）｜ references/06-完整实战手册.md（长正文/安装/参数全表/链接配法）｜ scripts/：video_insight.py（主流程）、douyin_fetch.py（链接下载）、check_env.py（自检）、skillkit.py（健壮性基座）。下一步：① 直接发我视频或链接 ② 跑脚本精确复现 ③ 看 references/06 要深度细节。
