视频声画侦察 xinhailaopo/video-watch-plus

video-watch-plus

让你的 AI 真的能看视频、听声音 —— 并且会给「这段转写可不可信」一个明确判定。

这是什么

一个技能包（skill）。把它交给你的 AI（任何能读文件、能跑命令、能看图的智能体），你的 AI 就多了三种本来没有的能力：

| 你可以这样问它 | 它会这样回答你 |
| 「这条视频讲了什么？」 | 先把全片扫一遍，挑出关键帧看图，给你一份带时间点的描述 |
| 「第 3 分 20 秒，画面上那行小字写的什么？」 | 从原始分辨率裁下那一小块、放大，看清楚了再读给你 |
| 「视频里的人说了什么？有没有人在说话？」 | 先用声学量一量「像不像人声」，再用 ASR 转文字，并且告诉你这次转写可不可信 |

它不是新的视频模型，也不会帮你下载视频。
它是一套「流程 + 工具」：所有不用动脑子的活都交给 ffmpeg（免费），只在真正需要理解的地方才让模型看一眼。

30 秒看懂它的思路

想让 AI「看视频」，通常只有两种笨办法：

- 均匀抽几帧 —— 便宜，但快动作整段漏掉，而且它说不清自己漏了什么；
- 逐帧全喂进去 —— 不漏，但 token（模型计费的计量单位）爆炸，而绝大多数帧是重复信息。

这个技能换了个思路：

让 ffmpeg 把整条视频从头到尾数一遍（这一步完全不叫模型，所以不花 token），把「哪里变了」全找出来，然后只让模型看那些真正有信息量的帧。

多出来的就是这一步。一句话总结：

量测负责「什么时候」，眼睛负责「是什么」，耳朵负责「说了什么」。

快速开始

第 0 步：装环境

git clone https://github.com/xinhailaopo/video-watch-plus
cd video-watch-plus

Windows：一条命令装好 ffmpeg（完整构建）+ ImageMagick 7 + 配置文件 powershell -ExecutionPolicy Bypass -File scripts\setup-windows.ps1 -VwPy vendor\vw.py

自检 —— 这一步必须过
python vendor\vw.py doctor

doctor 的输出长这样（节选），最后一行出现「必需项就绪」就能用了：

python 3.13.14 [win32]
ffmpeg E:\...\ffmpeg.exe
magick ImageMagick 7.x magick 聚合入口 Pillow OK gif 子命令 numpy OK vwtools 专用脚本 faster-whisper OK asr 子命令

必需项就绪：probe / plan / sheet / grid / seq / read / report 可用

macOS / Linux 用 brew install ffmpeg imagemagick 或 apt install ffmpeg imagemagick，再把 vendor/vw.py 里的 ffmpeg 路径指过去就行。

faster-whisper 那一行显示「未装」不影响第 1 步（看图只靠 ffmpeg + ImageMagick）。
它要到第 2 步听声音时才需要，装上就行。

第 1 步：看一条视频

① 量测全片：切点、冻结、静音、运动曲线。这一步零 token
python vendor/vw.py probe 视频.mp4 --out work

② 算出「该看哪几帧」，并保证盲区有上界
python vendor/vw.py plan work/timeline.json --out work/shotlist.json

③ 把这些帧拼成图版（就是一张大图里排很多小格，也叫 contact sheet）
python vendor/vw.py sheet work/shotlist.json 视频.mp4 --out work

④ 把图版交给 AI 看（到这一步才花 token）画面上的小字不要在图版里读，要把它裁下来、放大：
python vendor/vw.py read --media 视频.mp4 --times "14,19" --region "40,600,640,80" --out work_read

--region 的格式是 x,y,w,h，单位是原始像素——上面那串就是「从 (40,600) 开始，切一块 640×80」，正好是一条贴底的字幕条。

不知道 --region 该填哪四个数？ 别猜：先不写 --region 跑一遍（默认整帧），或者看一眼 ③ 出来的图版，判断你要读的字大概在画面哪一带，再回来圈。

⚠️ --times 里的时刻不能超过视频时长

超了 ffmpeg 就抽不到帧，而这一步的报错会指向 ImageMagick （unable to open image ...: No such file or directory），看起来完全不像时间戳的问题。
碰到这个报错，先回头核对 --times 有没有超出素材时长。

上面示例里的 14,19 和 40,600,640,80 都是按本文后面那条 20.19 秒、720×720 的短片写的。
换成你自己的素材时，两个都要改：时刻落在时长内，区域落在画面内。

⚠️ 两个一定会踩的坑

坑 1：--out 的含义不统一，而且写反了不一定报错。
probe 的 --out 要的是目录，plan 的 --out 要的是文件名。两个方向的表现完全不同：

- plan --out <某个目录> → 直接报 PermissionError: [Errno 13] Permission denied （POSIX 上会报 IsADirectoryError）；
- probe --out <某个文件名> → 如果这个名字还不存在，它一声不响地建一个同名目录，把 timeline.json 写进那个目录里（work\a.json\timeline.json）；只有当这个名字已经是文件时，才会报 FileExistsError: [WinError 183]。
也就是说 probe 这一侧不报错 ≠ 你写对了。跑完回头看一眼：--out 指的东西是目录还是文件。

坑 2：read 会把 manifest.json 整个覆盖掉。
sheet 和 read 都往 --out 目录里写同一个 manifest.json，后跑的盖掉先跑的。
而 manifest.json 就是那张「第几行第几列 = 第几秒」的位置映射清单 —— 被盖掉，这一批图版的时间就对不上了（重新跑一遍 sheet 能补回来，它不花 token，但会白跑一趟）。
所以给 read 单独一个输出目录（上面写的是 work_read），或者先把 manifest.json 备份出来。

第 2 步：听它的声音

pip install faster-whisper "av<19" numpy

先量一量「像不像人声」——纯数学，不花 token （--json 要求 work/ 目录已存在，它由第 1 步的 probe 建出来）
python scripts\audio_probe.py 视频.mp4 --json work/audio_probe.json

再转文字，同时检验这次转写到底可不可信
python scripts\asr_hallucination_check.py 视频.mp4 --model small --lang zh

⚠️ av<19 不能省

faster-whisper 1.2.1 会调用 av.open(..., metadata_errors=...)，而 PyAV 19 已经把这个参数删了 —— 装最新的 av，第一次转写就会 TypeError。

国内环境再加两个环境变量：HF_ENDPOINT=https://hf-mirror.com 和 HF_HUB_DISABLE_XET=1（不设后者，huggingface_hub 会走 Xet 传输，域名不通会报 401）。
setup-windows.ps1 已经把这两个写好了。

第 3 步：让你的 AI 用上它

上面那些命令不是让你手敲的，是给你 AI 跑的。把视频文件放到本地，再把路径告诉它就行：

「用 video-watch-plus 看一下 work/demo.mp4：讲了什么？有没有人说话？画面上有没有字幕？」

（⚠️ 视频得先在本地。这整套工具不会去下载视频，见下面的「常见问题」。）

SKILL.md 就是写给 agent 的操作手册，里面规定了：必须先量测再采样、读字必须裁切放大、音频必须先过声学那一关、三路冲突时谁说了算。
你只管提问 —— 该先量测、该裁切放大、该先过声学，这些顺序它自己会守住。

一次真实运行长什么样

素材：B 站一条 20 秒短片（BV1n3aw6xESG，720×720，27fps，545 帧）。以下是真实运行的终端输出——为了排版，长列表做了省略，数字一个都没改。下面这两组数字都能自己复现对账：帧数与切点记在 references/with-browser-skill.md（第 27 行）， ASR 那三处同音错字的对账记在 references/verification.md 第三节。

① probe —— 不花一分钱，先把结构摸清楚

素材 demo.mp4 720x720 27.0fps 20.19s 视频 h264 音频 aac 帧 545 实际帧率 27.00 内容判型 剪辑类（影视/演示/短视频）工具口径提示：切点密集，可作主信号；运动曲线作补充切点 4 个 冻结段 0 个 静音事件 0 个运动量 均值 4.409 p95 12.812 max 20.168 活跃秒占比 100% → work/timeline.json

② plan —— 算出该看哪几帧（节选，完整输出是 18 行抽样计划）

时长 20s 活跃段 1 个采样体制：高运动 运动均值 4.409 p95 12.812 事件处成组 3 帧 @0.12s（相邻帧号相差约 3 帧）——按帧号顺序读即得运动骨架 16 帧（间隔 1.26s，盲区上界 1.26s） + 事件 0 处 → 共 18 帧最终最大盲区 1.26s 2 张 3x3 图版 ≈ 692 token

16 + 0 = 18，多出来的 2 帧是 plan 自动补的开头 / 末尾各一帧，用来防止抽帧越界。
所以「共 N 帧」永远比「骨架 + 事件」多 2。

③ sheet —— 18 帧铺成 2 张 3×3 图版（节选）

sheet_01.png
sheet_02.png
第3行第3列 (#18) 帧543 → t= 20.10s 末尾 0.05s
→ work/manifest.json

manifest.json 是位置映射清单：图版上第几行第几列 = 视频的第几秒。
没有这张清单，看图版就是在猜时间。

④ asr —— 转写 + 可信度检验（节选，实验组那段完整贴在第 2 节）

== 对照组：默认（开启 VAD）== [ 0.00 → 2.48] Cloud的帐号又被封了 怎么办 [ 2.48 → 6.14] 有了 大飞鱼 现在假装自己是Cloud [ 6.14 → 8.94] 好的 我现在是Cloud [ 10.28 → 12.52] 太好了 还真成功了 [ 12.52 → 17.64] 酷怎么有股味啊 [ 17.64 → 20.14] 我靠 模仿的也太像了 → 6 段

== 判定 == 转写可信：有真实语音
- VAD 模式得到 6 段；强制模式 6 段中 6 段文本各不相同（unique 比 1.00）——幻觉不会产出这种多样性
- 模型自报 no_speech 概率均值仅 0.04（低，即认为有人说话）

⑤ 最后一步是「对账」：把转写拿去和画面上的烧录字幕（直接烙在画面里的字幕）比。

这 6 段里只有 2 段完全没错：一共 3 类错字，落在 4 段里。

| ASR 听成 | 画面字幕实际是 | 出现在几段里 |
| Cloud | claude | 3 段 |
| 大飞鱼 | 大肥鱼 | 1 段 |
| 酷怎么有股味啊 | 这用户怎么有股味儿啊 | 1 段（整句听错） |

（另外第 1 段里还有个 账号 → 帐号，属于常见异形字，没计进这三类。）

只要画面里能看到字，就以画面为准。 这条规则写在 SKILL.md 里 —— 上面这三种错，全靠它纠回来。
（顺便就能看出，为什么「只跑一个 ASR 就交付」是危险的：这一段听起来毫无破绽。）

它比「抽几帧给模型看」多做的三件事

1. 先量一量「像不像人声」，再让 ASR 说话

scripts/audio_probe.py 只用 numpy，从波形和频谱算出几个可复算的物理量，给出一个判型。
下表每个数字都是 verification/record-2026-09-30.md 里的实测值。
注意后面三列是「三段不同素材」，不是同一段素材的三种阈值：一段纯正弦单音、一段 48 秒纯 BGM 的 B 站视频、以及本文那条 20 秒有人声的短片。

| 判据 | 纯 BGM | 有人声 | 纯单音 | 它真正能区分什么 |
| 起始包络自相关峰（节拍感） | 0.857 | 0.165 | 0.001 | 有稳定节拍 ↔ 没有 |
| 逐秒响度波动 | 6.3 dB | 19.1 dB | 98.9 dB | 连续音乐床 ↔ 有起停的语音 |
| 单音集中度 | 低 | 低 | 0.576 | 把「纯音/提示音」单独分出来 |
| 85% 谱滚降 | 466 Hz | 1277 Hz | 445 Hz | 有没有高频瞬态 |
| 谱平坦度 | 0.0001 | 0.023 | 0.00003 | 有没有谐波结构（只能分「噪声 ↔ 非噪声」） |

注意最后一行：单看谱平坦度分不出音乐和纯音（两个都很低），真正把「纯音」摘出来的是单音集中度。判型是这几个量一起看的，不是任何一条单独说了算。

它不做识别，只做量测。而且它的输出只有四种判型：静音 / 近乎无声、纯音 / 提示音、音乐（含「疑似音乐」）、以及「未达判据」—— 没有「这是语音」这一档。所以「到底有没有人声」这句话，最终是 ASR 的 VAD 说的，不是它说的。

而它「说不出正确结论」的样子有两种，都必须承认。

样子一：诚实弃权（置信 low） —— 它明说「我判不出来，交给 ASR」：

判型 声学量测未见明确人声特征，也未达音乐判据（置信 low）
- 未达到音乐判据
- 单音集中度 0.202，谱平坦度 0.0226
- 此类音轨请交给 ASR，并以 VAD 结果为准

这一段出自本文开头那条 20 秒短片 —— 而 ASR 的 VAD 在同一段音轨上找到了 6 段清晰人声。
弃权不算失败，因为它把裁决权交出去了。

样子二：直接判错。 在一条确实有人声的 78 秒 AI 生成动画短片（BV1SXaG6TEvz）上，它给出的是这个：

响度 均值 -26.52 dBFS 峰值 -7.43 动态 66.31 dB 静音占比 3.1% 谱 质心 509.5 Hz 平坦度 0.01675 85%滚降 795.2 Hz 语音带占比 37.7% 节拍 208.3 BPM（自相关峰 0.2424） 响度波动 21.36 dB 音节率调制 0.7333 判型 纯音/提示音（非语音、非音乐）（置信 medium） ← 这一行是错的

同一条音轨上，ASR 的 VAD 给出了 18 段带时间戳的台词（大肥鱼挑战一天不吃白饭 / 又叫我大肥鱼 / 我真的不胖了 …）—— 这条音轨里确实有人在说话：把拒识门槛全拆掉之后，模型自报的 no_speech 均值只有 0.009。

看它自己的数字就知道为什么会错：响度波动 21.36 dB 和音节率调制 0.733 都强烈指向语音，但节拍自相关峰只有 0.242、单音集中度 0.282 —— 「配音 + 背景音乐」混在一起的音轨正好卡在阈值中间。

这条素材还顺带把第 2 节那句「判据一必须带 VAD 前提」变成了活的例子：强制模式下它退化成一长串 '这'（19 段）、'这这'（12 段）、'这这这'（5 段）， 56 段只落在 18 种文本上（unique 比 0.32）—— 于是判定是「转写可信，但存在分段差异，建议复核」。
要是判据一不带「VAD 无输出」这个前提，这条明显有人声的音轨就会被误判成幻觉。

所以请这样用它

audio_probe 的判型是「候选」，不是「结论」。
它给出负面判型（音乐 / 纯音 / 弃权）时，必须拿 ASR 的 VAD 去交叉印证 ——这也是它自己在每一条输出末尾反复写的那句「判定有无语音请与 ASR 的 VAD 结果交叉印证」。

它真正提供的价值是：当声学和 ASR 一致时，你多了一条不依赖语言模型的独立证据；不一致时，你至少知道「这条音轨不好判，别急着下结论」。

2. 抓 ASR 编台词

ASR 最阴的地方是：在没有语音的音轨上，它不会说「我没听到人声」，它会编一句出来。

scripts/asr_hallucination_check.py 的做法是同时跑两组：

- 对照组：正常开 VAD；
- 实验组：关掉 VAD、拆掉所有拒识门槛，强制它出字。

然后用两条判据判定（两条都带同一个前提：VAD 没有任何输出；满足任意一条就算幻觉）：

- 判据一：强制模式在互不重叠的时间窗里输出了完全相同的文本；
- 判据二：VAD 无任何输出，且模型自报 no_speech ≥ 0.4 —— VAD 是不依赖语言模型的检测器，它和模型自己的 no_speech 是两条独立证据，两条都指向"没人说话"时，文本读起来再通顺也不算数。

真实例（一段 40% 静音 + 纯 440Hz 的正弦音，根本没有人声）：

== 对照组：默认（开启 VAD）== → 0 段

== 实验组：关闭 VAD + 拆掉所有拒识门槛（强制出字）== [ 0.00 → 2.00] no_speech=0.573 logprob=-0.99 | '字幕by索兰娅' → 1 段

== 判定 == 判定为幻觉：音轨很可能没有人声
- VAD 模式无任何输出（该检测器不依赖语言模型）
- 强制模式仅产出 1 段，模型自报 no_speech 概率均值 0.57
- 强制模式内容：['字幕by索兰娅']（单段文本通顺不构成证据）

判据一抓的是另一种形态：同一句模板台词刷满全片。
在一段纯 BGM 的 B 站视频上，三个互不重叠的时间窗输出了完全相同的文本：

P1 [ 0.00 → 2.00] no_speech=0.440 '字幕by索兰娅'
P1 [30.00 → 48.00] no_speech=0.735 '字幕by索兰娅'
P2 [ 0.00 → 15.56] no_speech=0.508 '字幕by索兰娅'

模型自报的 no_speech 是 0.44–0.74 —— 它自己也不认为这里有人说话，却还是把同一句话写了三遍。

转写文本非空 ≠ 有语音。 通顺的台词也可能是填空填出来的。

3. 三路互校：谁说的话算数

| 哪一路 | 谁在算 | 它说了算的范围 |
| 量测 | vw.py probe（逐帧，零 token） | 时间：切点、冻结、静音、运动的先后顺序 |
| 画面文字 | 全分辨率裁切放大后亲眼看 | 文字内容：字幕、界面文案、文件路径 |
| 音轨 | audio_probe + asr | 说了什么，但必须先过声学那一关 |

对齐规则就四条：

1. 时间只信 manifest，不让「感觉上应该是先这样」决定先后；
2. 文字冲突时以画面为准（上面那张 3 类错字的表就是这么纠回来的）；
3. 音频判型冲突时不许只看一边：声学的判型是候选，ASR 的 VAD 是另一条独立证据。
两边一致 → 可以用；两边打架（比如上面那个 纯音/提示音 误判）→ 标明「不确定」，并且说明是哪一条证据在反对，不要单凭任何一边下结论，更不要把非空的转写文本直接当台词。
4. 三路都拿不到证据的区段，直接写「我没有可读信息」，不许用推断填空。

常见问题

它会自己下载视频吗？ 不会。你得先把视频文件弄到本地（yt-dlp、录屏、随便什么办法），再把这个文件交给它。

看一条视频要花多少 token？ 短的一条大约 700，长的封顶大约 1400（4 张图版）。具体数字 plan 会直接打印出来，不用你猜。这个花费不随视频长度增长，因为帧数上限是固定的。
（read 为了读字裁出来的面板是另算的，多裁一块就多一张图。）

read 那一步一定要带 --region。 不写区域时，它按 620×170 分块切整帧 ——本例（720×720）会切成 5 行 × 2 列共 10 块，一个时刻就是 10 张图（实测取 2 个时刻直接出了 20 张）；分辨率越高块数越多，1920×1080 上是 7 行 × 4 列 = 28 块。圈准了字幕条，一个时刻就只要 1 张。

那代价是什么？ 视频越长，两次采样之间的间隔就越大。按代码算，两小时的素材骨架仍是 16 帧，等于每 7.5 分钟才看一眼。plan 会把「最大盲区」（= 两次采样之间那段没人看过的时间）明确打出来， 别忽略那一行。（⚠️ 长素材本身还没实测过，见下面的「已知边界」。）

需要显卡吗？ 不需要。ffmpeg 和 numpy 都是 CPU 的活。ASR 用 --model small 在纯 CPU 上也够用。

中文识别准吗？ 能用，但同音错字很常见。有画面字幕的时候一定以画面为准 ——上面那条 20 秒的片子里，6 段转写里有 4 段带错字（3 类错字）。

它能不能帮我剪视频？ 不能。它只负责「看懂」，不负责剪。

我只有 Windows，为什么还要打补丁？ 见下面那节。

Windows 用户请看这里

上游工具在 Windows 上有两处会让 grid / sheet / read 直接失败的写法，本仓库用对照实验定位并修补了（详见 references/windows-setup.md）：

| 问题 | 实测 |
| ffmpeg 的 drawtext 吃不下盘符路径 | fontfile=C:/x.ttf ❌ · fontfile=C\:/x.ttf ❌ ← 上游写法 · fontfile='C\:/x.ttf' ✅ |
| ImageMagick 7 的 magick convert 入口 | 本构建下 convert 是唯一不被识别的子命令（被当成输入文件，报 no decode delegate for 'convert'）；montage、identify 都正常 |

补丁在 patches/vw-windows-fixes.patch，只改两个函数。

⚠️ 这两处是环境相关的，不是「所有 Windows 都会必现」。
ffmpeg 的版本和构建方式、ImageMagick 是 dll 版还是便携版、系统区域设置，都会影响是否触发。
请把 references/windows-setup.md 当作兼容性文档来读，而不是「已知必现 bug」——先在你自己的机器上跑一遍里面的自查命令，看属于哪一种，再决定打不打补丁。
补丁只在 os.name == "nt" 时改变行为，打了也不影响 macOS / Linux。

和 browser-skill 一起用

下面会反复出现「两条路」，先给个定义：

- 落盘路 —— 先把视频存成本地文件，再慢慢分析。就是本技能。
- 实时路 —— 直接在浏览器里看当前这个页面。这是 browser-skill 的活。

这个技能能给出「发生了什么」，但有一类东西它在结构上就拿不到：语境。
弹幕、标签、评论、相关推荐、登录态才能看到的内容 —— 这些只存在于实时浏览器里。

配合 @wxg-prc-cpg/browser-skill-dsh-plugin （底层是腾讯开源的 BrowserSkill）时，结论的完整度会有明显差别。一次实测：

- 落盘路（本技能）拿到：帧精确量测、烧录字幕全文、6 段带时间戳的转写，并纠正了 3 处同音错字；
- 实时路（browser-skill）补上了三件落盘路拿不到的事：
- 页面标签（搞笑 / AI / claude / deepseek娘，直接点明了画面里「蓝发→橙发」在指代什么）；
- 一条把笑点说破的弹幕（坏了，检测到国区用户了 —— 画面和音轨都只说了「角色消失」，没说是为什么）；
- 相关推荐，确认这是成套的梗系列。

落盘路回答「发生了什么」；实时路回答「这件事在什么语境里」。

什么时候该切到实时路：量测和转写都拿到了，结论里却出现「我不知道为什么」的时候。 分工表、8 步工作流、启用前提和五个实测坑，见 references/with-browser-skill.md。

建议：让智能体来装

这个技能的安装路径上有一堆只有踩过才知道的细节：PATH 究竟是谁的 PATH、 daemon 能不能从当前进程树分离、端口对不对、模型从哪个源下、av 的版本区间是多少……

所以推荐做法不是照着文档一处处试，而是把仓库直接交给你的 AI：

「按 SKILL.md 把环境装好，装完跑 vendor/vw.py doctor 和 scripts/build_testclip.py 验收，把踩到的坑补进 references/」

理由很简单：智能体能读源码验证而不是猜（本仓库那两处 Windows 缺陷，就是读 escape_filter_path() 的源码 + 写对照实验定位出来的）、能在失败的地方继续往下挖（「TCP 不通但 HTTP 通」这种矛盾，人很容易归因为「网络问题」就停手），并且能把过程固化成可复现的脚本（scripts/setup-windows.ps1 就是这么来的）。

只有一件事必须人来做：浏览器扩展的安装与授权。

已知边界（用之前请先读这一段）

能力上的边界

- 声学侦察不识别内容，而且会判错。 它只回答「像不像人声」，不回答「说了什么」，也不认曲名和说话人。
它有两种失效方式 —— 弃权（置信 low，安全）和判错（真的有人声却判成「纯音/提示音」，见第 1 节的样子二）。
所以它的判型一律当候选看，必须和 ASR 的 VAD 交叉印证。
- ASR 有同音错字。 有画面的时候一律以画面为准。
- 图版里的文字一律不采信。 必须裁切放大再读 —— 实测过两次「在图版里读出了画面上根本没有的字」。
道理是：视觉在分辨率不够的时候不会报「读不到」，它会渲染一个看起来合理的内容。
- 动作要看连续几帧的序列才读得出来（seq 子命令，--times "3.2,3.7,4.2" 取的就是挨着的几帧）。
它一次只能分辨 0.1–0.5 秒级的动作：取样隔得太远，快速动作会被「跳过去」，中间过程就看不到了。
- 「全片覆盖」和「看清每个字」物理上不可兼得。 一张图版上限 756×756（约 346 token），格子铺得越多、每格就越小，字也就越看不清 —— 想看全片就把字交给 read 裁切放大去读。
- 它不做剪辑。 要剪视频是另一类工具的事。
- 实时浏览器是另一条路，不是替代品。 它能拿到弹幕/标签/评论这些语境，但采样粗、而且拿不到音频。要精确取证，仍然得落盘。
- 声学层没有「这是语音」这个判型。 它只能给「静音 / 纯音 / 音乐 / 未达判据」四种结果，「到底有没有人声」最终由 ASR 的 VAD 说。本文那条 20 秒素材上，声学层给的正是「未达判据（置信 low）」。
- 长素材里，事件帧会被靠前的时间窗吃光。 事件预算是先到先得的：骨架占掉 18 个名额后，只剩 6 处事件名额（每处 3 帧）。实测（按代码造一条 2 小时的时间轴）： 6 处事件全部落在前 6 个 120 秒窗口，也就是前 12 分钟，后面近两小时一个事件帧都没有。
所以长素材请把 plan 打印的「最大盲区」当下限来读。

下面这些还没被验证过（本仓库自己的验收记录里明确写着「未覆盖」）

- 很长的素材：仓库自带的验收记录里，最长只测到 48 秒。
写这份 README 时另外补跑了一条 143 秒的素材，量测和采样都正常： 骨架 16 帧（间隔 8.95s，盲区上界 8.96s） + 事件 6 处 → 共 36 帧 / 4 张图版 ≈ 1384 token，封顶没变、盲区也没失控。但再长的（比如两小时直播）仍然没有实测数据。
不用猜：骨架间隔就是 时长 ÷ 16，plan 也会把「最大盲区」直接打出来。
- 跨平台：全部实测都在 Windows 上做。补丁只在 os.name == "nt" 时生效、不影响 macOS/Linux，但 macOS/Linux 上没跑过验收。
- GPU：device="cuda" 在本机因为缺 cublas64_12.dll 失败，所有 ASR 实测都跑在 CPU int8 上。
- OCR 通道：vw.py ocr 没测过（上游自己也把它定位成「哪里有字的索引」，不推荐用它读字）。

一个容易被误判成 bug 的行为

低对比度的画面切换不会被 scdet 当成硬切。实测：三段纯暗色拼起来的素材给出 切点 0 个，但工具会主动换口径，告诉你「本素材无硬切点：采样必须由运动曲线与骨架承担」。
这不是坏掉，是它换了另一条信号。

仓库结构

SKILL.md 技能本体（写给智能体的操作手册） README.md / README.en.md 本文件 LICENSE MIT（本项目部分） NOTICE 上游归属与衍生说明 patches/ vw-windows-fixes.patch 对上游 vw.py 的两处 Windows 修补 scripts/ audio_probe.py 声学侦察（新增） asr_hallucination_check.py ASR 幻觉证伪（新增） build_testclip.py 生成带已知真值的验收素材（新增） setup-windows.ps1 Windows 一键环境（新增） references/ windows-setup.md Windows 依赖坑的完整解法 video-watch-skill

让智能体「看」视频：抽帧、OCR、ASR、声学侦察，四路证据互校，输出带时间戳的结论。

这是什么

给智能体用的视频理解技能。丢给它一个视频文件或 URL，它返回一份结构化报告：关键帧、屏幕上的文字、语音转写、音频事件，全部带时间戳。

和「把视频丢给多模态大模型」的区别在于证据链：每一路证据都能追溯到具体的时间点和来源，四路互校之后才下结论。大模型看走眼的地方，OCR 和 ASR 能兜住。

快速开始 bash

安装依赖

pip install -r requirements.txt

抽帧 + OCR

python scripts/video_watch.py --input demo.mp4 --mode frames

全链路：抽帧 + OCR + ASR + 声学侦察

python scripts/video_watch.py --input demo.mp4 --mode full --output report.json

四路证据

| 通道 | 脚本 | 输出 | 适用场景 |
| 抽帧 | video_watch.py | 关键帧图片 + 时间戳 | 画面变化、演示操作 |
| OCR | ocr_frames.py | 屏幕文字 + 时间戳 | 字幕、代码、UI 文案 |
| ASR | asr_transcribe.py | 语音转写 + 时间戳 | 讲解、访谈、会议 |
| 声学侦察 | audio_probe.py | 音频事件 + 时间戳 | 无语音音轨、音效、环境音 |

目录结构

.
├── scripts/ 主流程脚本 │ ├── video_watch.py 抽帧 + 调度 │ ├── ocr_frames.py 帧 OCR │ ├── asr_transcribe.py 语音转写 │ └── audio_probe.py 声学侦察（新增） ├── references/ │ ├── verification.md 三路互校 playbook 与两类幻觉 │ └── with-browser-skill.md 和 browser-skill 配合：分工表与实测坑（新增） ├── verification/ │ └── record-*.md 带真值对照的实测记录 └── vendor/ 上游 MIT 代码（vw.py 已打补丁 + vwtools.py + 上游 LICENSE）

它和上游的关系

本技能是 CFITCorporation/video-watch-skill （MIT，Copyright © 2026 CFITSec）的衍生作品。vendor/ 下的 vw.py 是上游代码加上两处 Windows 修补，其余（scripts/、references/、patches/）都是新增。版权归属与衍生关系见 NOTICE。

新增的东西里，声学侦察是唯一一处「补上游缺口」的能力 ——上游整条链路只有 ASR，而 ASR 在无语音音轨上会幻觉。audio_probe.py 就是补这一层。

许可

本项目为 MIT。vendor/ 内包含上游代码（MIT，Copyright © 2026 CFITSec），详见 NOTICE。