analyzing-video

视频分析器

以自适应速率提取帧、创建蒙太奇网格、检测场景变化，并调度并行子 Agent 进行视觉和音频分析。

注意事项

• 社交媒体下载的视频（Instagram、TikTok）会将 MJPEG 缩略图嵌入为视频流 0。脚本会自动检测真实的 H.264/H.265 视频流，并跳过 attached_pic 流。
• macOS 的 grep 不支持 -P（Perl 正则表达式）。所有脚本都使用 sed 和基本的 grep 以确保兼容性。
• FFmpeg 会将输出文件名中的 . 视为图像序列模式。关键帧提取使用 -update 1 来写入单张图片。
• 纵向视频（高度 > 宽度）使用 3x5 网格布局，而非 4x4，以便更清晰地查看每个单元格。
• 场景检测阈值为 0.3。对于静态内容（演示文稿、文档），调低到 0.1。对于快速动作（游戏、体育），调高到 0.4。
• 调度分析 Agent 之前，务必确认提取已生成输出。

前置条件

需要 ffmpeg、ffprobe、python3、bc。如需转录：需要 whisper CLI。

brew install ffmpeg && pip install openai-whisper

转录模式

模式	触发条件	行为
auto	默认	运行 Whisper
user-provided	用户提供转录文件或文本	使用提供的转录内容
skip	“仅视觉分析”、“跳过音频”、“不转录”	不处理音频

自定义

检测用户请求中的以下覆盖设置：

覆盖设置	用户表述	效果
自定义 FPS	“5fps”、“每秒 3 帧”、“每 2 秒 1 帧”	覆盖基于分档的 fps 速率
时间范围	“从 0:10 到 0:30”、“前 15 秒”、“最后一分钟”	仅分析指定片段
两者	“以 5fps 分析 0:10-0:30”	对指定片段使用自定义 fps

将用户表述转换为脚本参数：

• “5fps” / “每秒 5 帧” → fps_override=5
• “每 3 秒 1 帧” → fps_override=0.333
• “每 10 秒 1 帧” → fps_override=0.1
• “从 0:10 到 0:30” → start_time=10 end_time=30
• “前 15 秒” → start_time=0 end_time=15
• “最后 30 秒” → 计算：start_time=duration-30

将覆盖设置传递给脚本：

bash ${CLAUDE_SKILL_DIR}/scripts/video-info.sh "<video_path>" [fps_override] [start_time] [end_time]
bash ${CLAUDE_SKILL_DIR}/scripts/extract-frames.sh "<video_path>" "<work_dir>/frames" <fps> <max> <stream> <grid> [start_time] [end_time]

设置自定义 fps 后，分档会变为 custom，并启用 1000 帧的安全上限。

工作流

复制此清单并跟踪进度：

- [ ] Step 1: Get video info (tier, stream, orientation)
- [ ] Step 2: Extract frames + grids + scene key frames
- [ ] Step 3: Verify extraction output (frames exist, grids exist)
- [ ] Step 4: Dispatch parallel analysis agents
- [ ] Step 5: Synthesize results into analysis document
- [ ] Step 6: Clean up temp directory

第 1 步：获取视频信息

bash ${CLAUDE_SKILL_DIR}/scripts/video-info.sh "$ARGUMENTS"

返回包含以下内容的 JSON：video_stream_index、tier、fps_rate、max_frames、orientation、grid_layout、has_audio、work_dir、whisper_model。

分档	时长	帧率	Whisper 模型
短	<1 分钟	每秒 2 帧	medium
中	1-3 分钟	每秒 1 帧	medium
长	3-10 分钟	每 10 秒 1 帧	base
超长	10 分钟以上	每 20 秒 1 帧（最多 60 帧）	base

第 2 步：提取帧（和音频）

bash ${CLAUDE_SKILL_DIR}/scripts/extract-frames.sh "$ARGUMENTS" "<work_dir>/frames" <fps_rate> <max_frames> <stream_index> <grid_layout>

用于转录（仅限 auto 模式）：

bash ${CLAUDE_SKILL_DIR}/scripts/extract-audio.sh "$ARGUMENTS" "<work_dir>/audio" <whisper_model>

适用时并行调度两项任务。

第 3 步：验证提取结果

调度 Agent 之前，验证输出：

• 检查 <work_dir>/frames/grid_*.jpg 是否存在（至少 1 个网格）
• 检查 <work_dir>/frames/metadata.json 中的帧数和网格数
• 如果检测到场景变化，检查 <work_dir>/frames/key_frames/ 中是否有图像
• 如果提取失败，报告错误并停止

第 4 步：并行子 Agent 分析

并行调度：

• 网格 Agent（每 2-3 个网格 1 个）：读取蒙太奇网格图像，描述各时间范围内的视觉内容
• 关键帧 Agent（检测到场景变化时）：读取高分辨率 key_frames/ 图像，详细分析场景变化
• 音频 Agent（模式为 skip 时跳过）：读取转录内容和音频元数据

第 5 步：综合并输出

将所有 Agent 的结果合并到源视频旁边的 <video_name>_analysis.md：

# Video Analysis: [filename]

## Overview
| Property | Value |
|----------|-------|
| Duration | HH:MM:SS |
| Resolution | WxH |
| Orientation | portrait/landscape |
| Analysis Tier | short/medium/long/extended |
| Frames Analyzed | N |
| Scene Changes | N |
| Transcription | auto/user-provided/skipped |

## Executive Summary
[2-3 paragraph summary]

## Timeline
| Time | Visual | Audio/Speech |
|------|--------|-------------|
| 00:00 | [description] | [what is said/heard] |

## Detailed Scene Analysis
### Scene 1: [Title] (00:00 - 00:15)
**Visual**: [description]
**Audio**: [what is heard]
**Context**: [significance]

## Conclusions
[Overall analysis]

第 6 步：清理

rm -rf "<work_dir>"

脚本

脚本	用途	参数
scripts/video-info.sh	元数据、流检测、分级	<video_path>
scripts/extract-frames.sh	帧、网格、场景检测、关键帧	<video_path> <out_dir> <fps> [max] [stream] [grid]
scripts/extract-audio.sh	音频、静音检测、转录	<video_path> <out_dir> [model]

参考资料

• references/ffmpeg-commands.md — FFmpeg 易踩问题和不明显的命令
• references/transcription-guide.md — Whisper 模型选择与故障排除
• references/analysis-strategies.md — 子 Agent 调度模式与输出模板