视频分析

视频分析——所见与所言

您没有直接的视频或音频输入。您需要读取从视频中提取的图像以及音频的转录。以下所有步骤将视频转换为这两样东西，然后告诉您如何在不夸大其词的前提下阅读它们。

文件存放位置——所有者的硬性规则

所有提取的材料都存放在视频所在文件夹下的一个工作文件夹中： <视频文件夹>\<视频名称>.analysis\——绝不能放在暂存区、临时目录或项目中。 视频分析工作完成后，所有者会将其删除以回收磁盘空间。 切勿自行删除。 如果要求清理，请使用 trash 技能精确处理该文件夹（回收站，绝不能使用 rm）。您的书面分析（交付物）应放在项目所需的位置，而不是 .analysis 文件夹内，这样删除该文件夹不会丢失任何有价值的东西。

1. 工具（每台机器一次）

python ~/.claude/skills/video-analysis/scripts/setup_tools.py --check   # 验证
python ~/.claude/skills/video-analysis/scripts/setup_tools.py           # 安装缺失的组件

使用 pip --user 安装：imageio-ffmpeg（捆绑的 ffmpeg 二进制文件——无需系统 ffmpeg，无需管理员权限，无需 winget/choco）、Pillow、numpy、faster-whisper，并缓存 Whisper small 模型（唯一的网络访问；之后完全离线）。退出码 0 = 就绪。

自测（合成视频，9 项检查，--full 增加 Whisper 测试）： python ~/.claude/skills/video-analysis/scripts/selftest.py

2. 提取

python ~/.claude/skills/video-analysis/scripts/extract_video.py "<视频路径>" --language fr

对于超过几分钟的视频，请在后台运行：转录速度约为实时速度的 5 倍（15 分钟的视频约需 3 分钟）。选项：--interval 5（帧之间的秒数；快速移动画面使用 2，人物讲话使用 10-15），--model small（medium 效果更好，但慢 3 倍），--skip-frames，--skip-transcript，--at HH:MM:SS[.mmm]（可重复使用，在精确时刻拍摄全分辨率帧——在步骤 3d 中使用）。

在 <视频>.analysis\ 中生成：frames\（每隔 interval 一张）、sheets\（3x3 联系表，每张图像以黄色标记 mm:ss）、keyframes.txt + keysheets\（仅明显变化的帧——幻灯片/屏幕变化）、audio.wav、transcript.txt（[mm:ss] 文本）+ transcript.json、at\、manifest.json。重新运行会恢复并跳过已完成阶段；更改参数或不同视频将被拒绝（退出码 3），以免混淆输出。退出码 1 = 处理失败，退出码 2 = 输入错误。

3. 阅读——按此顺序

a. 首先阅读完整转录（transcript.txt）。在课程和演示中，关键内容（数字、规则、例外、真正的方法）通常在语音中，而非屏幕上。 b. 关键帧联系表（keysheets\），查看每个不同的幻灯片/屏幕一次。 c. 所有联系表（sheets\）——按顺序全部查看，以了解关键帧之间的动态（光标、绘图、图表更新）。 d. 语音指向处放大：当说话者说“这里”、“这根蜡烛”、“看…”时，使用 --at <时间戳> 以及与首次运行相同的选项重新运行（否则清单检查将拒绝并退出码 3），然后阅读该全分辨率帧。联系表每个单元格为 640 像素——对于图表标签或小文本来说太小。 e. 编写分析报告（步骤 4）。

4. 报告——区分三类内容

对于每个段落，引用时间戳并将每条陈述标注为以下之一：

• ON SCREEN——图像实际显示的内容（幻灯片文本、图表、注释、界面）。
• SAID——语音陈述的内容（引用或紧密改写，附 [mm:ss]）。
• INFERENCE——您作为分析师将两者关联的解读。切勿将其呈现为所见或所言。

始终包含：

• 书面内容与语音内容之间的差异（例如，幻灯片说一件事，而语音添加了真正重要的规则，或与之矛盾）；
• 仅显示一次的内容（单个演示示例是说明，而非证据）；
• 局限：帧每 N 秒采样一次，可能错过短暂事件；帧的时间戳是其索引 × 间隔，因此是近似值（±半个间隔，可变帧率录制误差更大）；关键帧去重可能隐藏小修改；Whisper 会拼错名称和术语（需对照图像检查）；无法可靠读取语调、情感、音乐、说话者身份或动态。

5. 后续工作

告知用户工作文件夹路径及其大小（提取结束时打印）。保留该文件夹，直到用户确认视频分析工作完成；然后使用 trash 技能将其移动至回收站。

已知陷阱（脚本已处理）

• faster_whisper 的 model.transcribe("<path>") 在最新的 PyAV 下会引发 TypeError: open() got an unexpected keyword argument 'metadata_errors'。脚本使用 ffmpeg 提取 16 kHz 单声道 PCM16 WAV，并传递 float32 数组。
• imageio-ffmpeg 自带 ffmpeg 但不带 ffprobe：持续时间和音频存在性从 ffmpeg 的自身横幅中读取。
• 通过 select='gt(scene,N)' + showinfo 进行的场景检测在 -loglevel error 下不输出任何内容；关键帧使用缩略图差值代替。