ffmpeg-analyse-video

FFmpeg 视频分析

使用 ffmpeg 从视频文件中提取帧。将帧读取工作委派给子 Agent，以保留主上下文窗口。根据子 Agent 仅包含文本的报告，综合生成带时间戳的结构化摘要。

架构：上下文高效的子 Agent 流水线

问题：将数十张图片读入主对话上下文会占用大部分上下文窗口，留给综合分析和后续交流的空间所剩无几。

解决方案：分为 3 个阶段的流水线：

Main Agent                          Sub-Agents (disposable context)
──────────                          ──────────────────────────────
1. ffprobe metadata        ───►
2. ffmpeg frame extraction ───►
3. Split frames into batches ──►   4. Read images (vision)
                                      Write text descriptions
                                      to batch_N_analysis.md
5. Read text files only    ◄───    (context discarded)
6. Synthesise final output

图片只会出现在子 Agent 的上下文中。主 Agent 只读取轻量级文本文件。这样可减少约 90% 的上下文占用。

1. 前置条件

which ffmpeg && which ffprobe

如果缺少其中任一项，请显示对应平台的安装说明并停止：

• macOS：brew install ffmpeg
• Ubuntu/Debian：sudo apt install ffmpeg
• Windows：choco install ffmpeg 或 winget install ffmpeg

2. 设置临时目录

# macOS/Linux
TMPDIR="/tmp/video-analysis-$(date +%s)"
mkdir -p "$TMPDIR"

# Windows (PowerShell)
# $TMPDIR = "$env:TEMP\video-analysis-$(Get-Date -UFormat %s)"
# New-Item -ItemType Directory -Path $TMPDIR

3. 提取视频元数据

ffprobe -v quiet -print_format json -show_format -show_streams "VIDEO_PATH"

提取并报告：时长、分辨率（宽 x 高）、fps、编解码器、文件大小，以及是否包含音频。

如果未找到视频流，请报告“仅音频文件”并停止。 如果文件大小超过 2GB，请提醒用户，并建议使用 -ss START -to END 分析指定时间范围。

4. 提取帧

根据时长选择策略：

时长	策略	命令
0-60s	每 2s 提取 1 帧	ffmpeg -hide_banner -y -i INPUT -vf "fps=1/2,scale='min(1280,iw)':-2" -q:v 5 DIR/frame_%04d.jpg
1-10min	场景检测（阈值 0.3）	ffmpeg -hide_banner -y -i INPUT -vf "select='gt(scene,0.3)',scale='min(1280,iw)':-2" -vsync vfr -q:v 5 DIR/scene_%04d.jpg
10-30min	提取关键帧	ffmpeg -hide_banner -y -skip_frame nokey -i INPUT -vf "scale='min(1280,iw)':-2" -vsync vfr -q:v 5 DIR/key_%04d.jpg
30min+	缩略图滤镜	ffmpeg -hide_banner -y -i INPUT -vf "thumbnail=SEGMENT_FRAMES,scale='min(1280,iw)':-2" -vsync vfr -q:v 5 DIR/thumb_%04d.jpg

对于缩略图滤镜，计算 SEGMENT_FRAMES = total_frames / 60，将输出帧数限制在约 60 帧。

回退方案：

• 场景检测未生成任何帧 → 重试，改为每 5s 提取 1 帧
• 提取帧数超过 100 → 均匀抽取 80 帧
• 帧提取失败 → 尝试下一种更简单的策略（场景检测 → 间隔提取，关键帧 → 间隔提取）

时间范围分析： 用户指定范围时，在 -i 之前添加 -ss START -to END。 更高细节模式： 如果用户提出要求，将 fps 提高一倍，并将场景阈值降至 0.2。

提取完成后，列出所有帧文件，并根据序号和提取速率计算每帧的时间戳。

5. 将帧分析委派给子 Agent

这是节省上下文的关键步骤。 不要在主对话中读取帧图片。请将帧分成多个批次，并将每个批次委派给一个子 Agent。

5a. 准备批次清单

将提取的帧文件列表拆分为多个批次，每批 8-10 帧。为每个批次记录：

• 批次编号（1、2、3，……）
• 帧文件路径（绝对路径）
• 帧时间戳（根据序号计算）
• 输出文件路径：TMPDIR/batch_N_analysis.md

5b. 启动子 Agent

为每个批次启动一个子 Agent，并使用以下提示词。如果工具支持并行运行，请并行启动所有批次——它们彼此完全独立。

子 Agent 提示词模板

逐字使用此提示词，并替换其中的占位符：

You are analysing frames extracted from a video file.

VIDEO: {filename}
DURATION: {duration}
BATCH: {batch_number} of {total_batches}

Read each frame image listed below using the Read tool (or equivalent file reading tool that supports images). For each frame, write a structured description.

FRAMES:
{for each frame in batch}
- {absolute_path_to_frame} (timestamp: {MM:SS})
{end for}

For each frame, describe:
1. SCENE: What is visible (layout, UI elements, environment)
2. CONTENT: Text, code, labels, menus, or dialogue visible on screen
3. ACTION: What is happening or has changed since the likely previous frame
4. DETAILS: Any notable specifics (error messages, URLs, file names, button states)

After describing all frames, add a BATCH SUMMARY section with:
- Content type (one of: Screencast, Presentation, Tutorial, Footage, Animation)
- Key events in this batch's time range
- Any text/prompts/commands the user typed (quote exactly)

Write the complete analysis to: {TMPDIR}/batch_{N}_analysis.md

Format the output file as:

# Batch {N} Analysis ({start_timestamp} - {end_timestamp})

## Frame-by-Frame

### Frame {sequence} ({timestamp})
- **Scene**: ...
- **Content**: ...
- **Action**: ...
- **Details**: ...

(repeat for each frame)

## Batch Summary
- **Content Type**: ...
- **Key Events**: ...
- **Quoted Text/Prompts**: ...

如何启动

使用工具提供的任何子 Agent、后台任务或独立 Agent 机制。要求很简单——每个子 Agent 都需要：

1. 读取图片文件（帧 JPEG）
2. 写入文本文件（批次分析 Markdown）

如果工具支持并行运行，请并行启动所有批次——它们彼此完全独立，没有共享状态。

如果工具不支持子 Agent 机制，则退而求其次，在主上下文中直接读取帧，但最多只处理 20 帧，并提醒用户注意上下文占用。

5c. 收集结果

所有子 Agent 完成后，读取文本分析文件。这些文件是轻量级 Markdown，不会将图像载入主上下文。

ls TMPDIR/batch_*_analysis.md

按顺序读取每个 batch_N_analysis.md 文件。这些文件仅包含文本描述，与读取原始图像相比，上下文开销极低。

6. 综合输出

仅使用批次分析文件中的文本，在主上下文中进行综合：

1. 将所有帧描述合并为一条按时间顺序排列的时间线
2. 将帧归类到自然片段中（相同场景、幻灯片或屏幕）
3. 检测所有批次中的主要内容类型
4. 找出 3-7 个关键时刻
5. 提取用户输入的所有引用文本、提示词或命令
6. 撰写一段 2-5 句的叙述性摘要

按以下格式输出：

# Video Analysis: [filename]

## Metadata
| Property | Value |
|----------|-------|
| Duration | M:SS |
| Resolution | WxH |
| FPS | N |
| Content Type | [detected] |
| Frames Analysed | N |

## Timeline
### [Segment Title] (M:SS - M:SS)
Description of what happens in this segment.

### [Segment Title] (M:SS - M:SS)
Description of what happens in this segment.

## Key Moments
1. **[M:SS] Title**: Description
2. **[M:SS] Title**: Description
3. **[M:SS] Title**: Description

## Summary
[2-5 sentence narrative paragraph summarising the entire video]

7. 清理

输出完成后，删除临时目录：

# macOS/Linux
rm -rf "$TMPDIR"

# Windows (PowerShell)
# Remove-Item -Recurse -Force $TMPDIR

如果用户要求保留帧，则跳过清理。

高级选项

• 时间范围：“分析 video.mp4 的 2:00 到 5:00” → 使用 -ss 120 -to 300
• 更高细节：“进行高细节分析” → 将帧率加倍，并将场景阈值降至 0.2
• 关注区域：“重点关注显示的代码” → 在子 Agent 提示词中优先提取文本/代码
• 缩略图拼接图：生成联系表，以便直观查看：

  ffmpeg -hide_banner -y -i INPUT -vf "select='not(mod(n,EVERY_N))',scale='min(320,iw)':-2,tile=5xROWS" -frames:v 1 DIR/sprite.jpg
  

错误处理

• 未找到 ffmpeg → 提供对应平台的安装说明，然后停止
• 没有视频流 → 报告仅包含音频，然后停止
• 场景检测未生成任何帧 → 回退到固定间隔
• 帧数过多（>100）→ 以 80 帧为目标进行抽样
• 文件过大（>2GB）→ 发出警告并建议指定时间范围
• 子 Agent 失败或超时 → 直接读取该批次的帧作为回退方案，并提醒上下文用量
• 子 Agent 读取帧失败 → 跳过该帧，并在批次分析文件中注明缺失