video-analysis:视频分析工作流 是做什么的?
将视频转换为模型可读的格式:每帧的数值测量、带时间戳的连续图集、转录文本、声音时间线和频谱图图像,然后据此生成一份分析报告。这是分析工具之上的过程,而非工具本身(所有者的私有脚本未附带;学生分支遵循 TOOLS_SPEC)。该技能从不编辑、渲染或应用风格。
高于本文件其余部分的规则
- 输入为只读。 前后验证哈希值(
input.sha256=sha256_after);输出仅位于analysis/<video>/下。仅下载用户提供的 URL,并记录来源和文件名;该副本仅作为参考,绝不重新分发;平台的徽标、结尾卡和提示音应从统计数据中排除并列出。 - 首先声明覆盖范围。 每份报告都以覆盖块开头:完整 vs 采样、已解码/期望帧数、排除了什么、未运行什么。采样结果绝不能呈现为完整覆盖。采样运行不得引用剪切次数或节奏作为已测量的事实。
- 运行工具;切勿用手动 ffmpeg 采样。 如果工具缺失,声明
blocked: tool_missing并询问;手动回退仅允许作为明确标记的sampled查看,且不包含计数。 - 先阅读再书写: 查看每张图集和每张音频图像;放大 3-6 倍;根据帧决定每个
check编辑点;纠正错误的计数并说明原因。 - 本地、免费、私密。 不使用付费视频理解 API,不上传视频或其帧或音频,不在
private素材上使用远程歌曲识别,未经日期估算和事先批准(paid-generation-gate)。希伯来语音频强制使用he;切勿信任单次 ASR 结果中的名称、品牌和数字。 - 歌曲匹配不是许可证。 报告“识别为 X,未经确认同步许可”或“未识别”;切勿编造标题。AudioSet 风格的标签是猜测(“可能是一个 whoosh”);速度和调性为估计值,需审核半速/倍速。
- 一次只运行一个重型作业, 在
render_lock下进行;超过约 2 分钟的内容在后台运行,附带日志和预计完成时间;不承诺运行时间(所有者的批次:负载下每视频 9-23 分钟,取决于机器)。技能是流程而非权限:用户和项目限制优先于本文件。
此技能期望的工具接口(TOOLS_SPEC video-analysis;用 --help 验证)
python tools/analyze.py <video|URL|folder> --out analysis/<video> [--detail quick|standard|full]
[--asr auto|always|never] [--no-song-id] [--no-audio-ai] [--check]
python tools/frames.py <video> --at <t> --pad 0.25 --out analysis/<video> # 提取短时间窗口的每一帧
输出契约(references/output-contract.md):analysis/<video>/{measurements.json, frames.csv, sheets/ (index.json + images), transcript.json, audio.json} + breakdown.md。
流程
| # | 执行操作 | 产物 |
|---|---|---|
| 0 | 仅询问改变运行的内容:完整分析还是单一问题(剪切/转录/歌曲)?是否为机密素材(private)?分析报告使用哪种语言?如果是文件夹:先列出内容;绝不过写已有分析 | 范围声明 |
| 1 | 预检(analyze --check / doctor):记录操作系统、ffmpeg、检测到的 ASR 路由(CPU / Vulkan / CUDA / MLX;未检测到则为 none)、Vulkan 环境标志;无路由 = 仅针对转录声明 blocked | environment 块 |
| 2 | 在锁下后台运行。--detail:quick 用于语料库/长对话,standard 为默认,full 用于动态图形、极快剪辑或参考转移(references/thresholds.md)。多个视频:一次批量处理,然后每个视频分配一个智能体(仅操作其文件夹,输出 breakdown.md,设定截止时间,回复 <= 10 行) | 分析文件夹 |
| 3 | python scripts/validate_analysis.py analysis/<video> --stage produced | PASS 或出错的组件 |
| 4 | 阅读:所有图集、所有音频图像;仅针对不同设备缩放;解决 check 点;纠正计数(pacing.override + review.corrections);审核半速/倍速 | review 块 |
| 5 | python scripts/validate_analysis.py analysis/<video> --video <source>;退出码 0 是作为事实呈现数值的前提 | 验证报告 |
| 6 | 按用户语言编写 breakdown.md(遵循 references/reading-and-breakdown.md:先声明覆盖范围,7 个章节,不确定性最后) | breakdown.md |
| 7 | 报告:文件路径、5-10 行、纠正内容、无法确定的内容;提供下一步技能建议(reference-style-transfer、类型技能)而非直接执行 | 消息 |
门控
状态为 pass | fail | blocked | n/a,并附原因。超时、空样本或输入缺失为 blocked,绝非 pass。成功的工具调用为执行证据;已查看的图集为外观证据。
| 门控 | 条件 | 证据 | 如果为假 | 所有者 | 重新检查时机 |
|---|---|---|---|---|---|
| G1 机器配置 | 检测并记录 ASR 路由;Vulkan 路由记录 GGML_VK_DISABLE_COOPMAT(所有者的 AMD 驱动需要 =1;其他驱动未经测试) | 来自 doctor/--check 的 measurements.environment | 回退到 CPU 路由并说明;绝不要假设有 GPU | 本技能 + doctor | 新机器、驱动或模型 |
| G2 契约有效 | 所有五个组件均通过或为 n/a 并附原因 | validate_analysis.py 退出码 0(已提供 --video) | 修复或重新运行该组件;报告 INSUFFICIENT 并说明缺失部分 | validate_analysis.py | 任何重新运行或手动编辑 |
| G3 覆盖声明 | 报告以模式、已解码/期望帧、排除项、未运行列表、claims_not_allowed 开头 | breakdown.md 的第一个块 | 添加覆盖声明;将声称降级为“sampled” | 本技能 | 每份报告 |
| G4 剪切检测器回归 | 对检测器阈值的任何更改保持 F1 >= 已标记集的基线(所有者的历史值为 0.89 = P 0.87 / R 0.91,基于 20 个手动验证广告,339 个编辑点,私密数据,不可复现;已知盲点:动态文字和连续镜头片段) | cut_regression.py --pair ... --min-f1 0.89 退出码 0 且 >= 100 个真实点 | 还原阈值更改 | cut_regression.py | 每次检测器更改;绝不由人工判断 |
| G5 输入未被修改 | 源文件哈希值前后一致 | validate_analysis.py --video | 从原始文件恢复源文件,重新运行 | validate_analysis.py | 每次运行 |
| G6 先读后写 | 每个关键帧/概览图集和每个音频图像均已查看;每个 check 点已解决;计数已在帧上验证 | review 块完成(阶段已审查) | 返回查看它们 | 本技能 | 每次分析 |
| G7 隐私与权利 | private 输入:无远程歌曲识别、无云端 ASR、无帧上传;匹配 = 无许可证 | song_id.status、asr.route | 删除摘录日志,重新本地运行 | 本技能 | 每次运行 |
需注明范围的数字和限制
- 剪切检测器:仅限所有者的调整(G4);在帧上验证之前,自动剪切计数在大约 60% 的广告推广视频中是错误的;一个动态文字示例自动读取了 108 剪切/分钟,而从图集得出为 42。
- ASR(所有者的机器,E08,一次通过,朗读式语音):Vulkan 5.82 音频秒/墙秒,CPU CT2 int8 0.84,WER 17.7-19.4%:
references/volatile-facts.md(注明日期;有效期至 2026-12-31)。 - 声音分析仅在确实有音乐时运行:节拍/BPM/调性需要 >= 3 秒的音乐;有歌词的歌声需要通过无 VAD 的歌词通道(仅保留置信度高的片段,标记为“SUNG LYRICS”)。
参考资料(按需加载)
references/output-contract.md— 编写、移植或调试任何输出文件;阅读验证报告。references/thresholds.md— 调整或移植检测器、选择--detail、解释错误计数。references/reading-and-breakdown.md— 在阅读图集和编写分析报告之前。references/volatile-facts.md— 在引用任何速度、WER、价格、许可证或工具事实之前(注明日期的模块)。agent-content/references/asr-routes.md(标准 ASR 路由,归属其他模块)和hebrew-captions-asr(字幕级转录);reference-style-transfer技能使用此技能生成的文件夹。- 脚本:
scripts/validate_analysis.py(契约检查,--self-check)、scripts/cut_regression.py(F1 门控,--self-check);两者均以失败闭锁方式工作(退出码 0 / 1 / 2)。