当此技能被激活时,始终以 :mag: 表情符号开始您的首次回复。
视频分析器
视频分析是一种从视频文件中提取结构化信息的实践——包括元数据、关键帧、场景边界、调色板、运动数据和音频特征。一个构建良好的视频分析管道将 FFmpeg(用于帧提取和信号处理)与 AI 视觉模型(用于对视觉内容的语义理解)相结合。此技能涵盖了从原始视频文件到可操作数据的完整工作流:使用 ffprobe 进行元数据检查,FFmpeg 滤镜图用于帧提取和场景检测,音频分析用于静音和音量检测,以及 AI 视觉用于设计系统提取和内容理解。
视频分析的两大支柱是 FFmpeg(媒体处理领域的瑞士军刀)和 AI 视觉模型(用于理解每帧的内容)。FFmpeg 处理机械性工作——将视频分割为帧、通过像素差异阈值检测场景变化、提取音频波形。AI 视觉处理语义性工作——识别 UI 组件、读取文本、提取颜色值以及理解布局模式。
何时使用此技能
当用户出现以下情况时触发此技能:
- 希望从视频中按固定间隔或场景边界提取帧
- 需要分析视频元数据(分辨率、时长、编码器、比特率)
- 询问场景检测或场景变化时间戳
- 希望从视频内容中提取调色板或设计系统
- 需要分析音频轨道(静音检测、音量电平、波形)
- 询问视频中的运动分析或动画时间线
- 希望使用 AI 视觉逐帧理解视频内容
- 需要从视频文件生成缩略图或预览条
在以下情况下不要触发此技能:
- 从头创建或编辑视频——请使用 remotion-video 或 video-creator
- 编写视频脚本或故事板——请使用 video-scriptwriting
- 直播视频流或实时视频处理
- 为了分发进行视频编码/转码(这是渲染任务,而非分析)
关键原则
-
先提取再分析——始终将帧提取(FFmpeg)与语义分析(AI 视觉)分开。试图一步完成两者会导致脆弱的管道。先将帧提取到磁盘,然后再分析它们。
-
在 ffmpeg 之前使用 ffprobe——在处理任何视频之前,使用 ffprobe 检查其属性。对未知格式盲目运行 FFmpeg 命令会导致静默失败和损坏的输出。
-
场景检测优于固定间隔——在分析视频内容时,在场景边界处而不是固定时间间隔处提取帧。场景变化帧可以用更少的帧捕获视频的视觉多样性(相比每秒提取一帧)。
-
各处使用 JSON 输出——使用 ffprobe 的 JSON 输出格式,并将分析结果结构化为 JSON。这使管道可组合且结果可被机器读取。
-
注意磁盘空间——视频帧提取可能生成数千个大图像文件。在提取前始终估算输出大小,使用合适的图像格式(JPEG 用于分析,PNG 用于像素精确工作),并在分析后清理临时帧。
核心概念
FFmpeg 管道架构
FFmpeg 通过解复用、解码、滤镜、编码和复用的管道处理视频。对于分析,我们主要使用解码和滤镜阶段:
输入文件 -> 解复用器 -> 解码器 -> 滤镜图 -> 输出(帧/数据)
用于分析的关键滤镜概念:
select滤镜:基于表达式选择要输出的帧showinfo滤镜:打印帧元数据(时间戳、图像类型等)scene检测:连续帧之间的像素级差异分数fps滤镜:降低帧率以按固定间隔提取
场景检测
场景检测通过使用像素差异比较连续帧来工作。FFmpeg 的 scene 滤镜产生从 0.0(完全相同)到 1.0(完全不同)的分数。0.3-0.4 的阈值可捕获主要场景变化,同时忽略相机运动和光照变化。
| 阈值 | 行为 |
|---|---|
| 0.1-0.2 | 非常敏感——捕获pan/zoom、光照变化 |
| 0.3-0.4 | 平衡——捕获剪切、过渡、重大变化 |
| 0.5-0.7 | 保守——仅硬剪切和剧烈场景变化 |
| 0.8-1.0 | 过于激进——遗漏大多数场景变化 |
AI 视觉分析工作流
使用 AI 视觉从视频中提取结构化数据的工作流:
- 探测——使用 ffprobe 获取视频元数据(时长、分辨率、fps)
- 提取——使用 FFmpeg 在场景边界处拉取关键帧
- 读取——使用 Read 工具加载每帧图像(支持图像)
- 分析——对于每帧,识别颜色、排版、布局、组件
- 聚合——在帧间查找一致的图案
- 输出——生成结构化的设计系统或内容分析
常见任务
1. 安装并验证 FFmpeg
检查 FFmpeg 是否可用并检查其版本和功能。
# 检查 FFmpeg 安装
ffmpeg -version
# 检查 ffprobe 安装
ffprobe -version
# 在 macOS 上安装
brew install ffmpeg
# 在 Ubuntu/Debian 上安装
sudo apt-get update && sudo apt-get install -y ffmpeg
# 验证支持的格式
ffmpeg -formats 2>/dev/null | head -20
# 验证支持的编码器
ffmpeg -codecs 2>/dev/null | grep -i h264
2. 在场景边界处提取关键帧
仅提取发生显著视觉变化处的帧。这是采样视频内容最有效的方式。
# 在场景变化处提取帧(阈值 0.3)
mkdir -p scenes
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)',showinfo" \
-vsync vfr \
scenes/scene_%04d.png \
2>&1 | grep showinfo
# 提取并将时间戳记录到文件
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)',showinfo" \
-vsync vfr \
scenes/scene_%04d.png \
2>&1 | grep "pts_time" > scenes/timestamps.txt
# 将场景帧提取为 JPEG(文件更小,适合分析)
mkdir -p scenes
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)'" \
-vsync vfr \
-q:v 2 \
scenes/scene_%04d.jpg
3. 按固定间隔提取帧
当无论内容变化如何都需要均匀间隔的样本时。
# 每秒提取一帧
mkdir -p frames
ffmpeg -i input.mp4 -vf "fps=1" frames/frame_%04d.png
# 每 5 秒提取一帧
mkdir -p frames
ffmpeg -i input.mp4 -vf "fps=1/5" frames/frame_%04d.png
# 仅提取 I 帧(编码器的关键帧)
mkdir -p keyframes
ffmpeg -i input.mp4 \
-vf "select='eq(pict_type,I)'" \
-vsync vfr \
keyframes/kf_%04d.png
# 在特定时间戳提取单帧
ffmpeg -i input.mp4 -ss 00:01:30 -frames:v 1 thumbnail.png
# 仅提取第一帧
ffmpeg -i input.mp4 -frames:v 1 first_frame.png
4. 使用 ffprobe 分析视频元数据
在处理前检查视频属性。始终使用 JSON 输出以获得机器可读的结果。
# 完整元数据为 JSON(流和格式)
ffprobe -v quiet \
-print_format json \
-show_format \
-show_streams \
input.mp4
# 仅获取时长
ffprobe -v error \
-show_entries format=duration \
-of default=noprint_wrappers=1:nokey=1 \
input.mp4
# 获取分辨率
ffprobe -v error \
-select_streams v:0 \
-show_entries stream=width,height \
-of csv=s=x:p=0 \
input.mp4
# 获取帧率
ffprobe -v error \
-select_streams v:0 \
-show_entries stream=r_frame_rate \
-of default=noprint_wrappers=1:nokey=1 \
input.mp4
# 获取编码器信息
ffprobe -v error \
-select_streams v:0 \
-show_entries stream=codec_name,codec_long_name,profile \
-of json \
input.mp4
# 计算总帧数
ffprobe -v error \
-count_frames \
-select_streams v:0 \
-show_entries stream=nb_read_frames \
-of default=noprint_wrappers=1:nokey=1 \
input.mp4
5. 检测场景并列出时间戳
获取场景变化时间戳列表,无需提取帧。
# 列出场景变化时间戳
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)',showinfo" \
-f null - \
2>&1 | grep pts_time
# 为每帧提取场景分数(用于分析)
ffmpeg -i input.mp4 \
-vf "select='gte(scene,0)',metadata=print" \
-f null - \
2>&1 | grep "lavfi.scene_score"
# 统计场景变化次数
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)',showinfo" \
-f null - \
2>&1 | grep -c "pts_time"
6. 提取音频波形并检测静音
分析音频轨道中的静音间隙、音量电平和视觉波形。
# 检测静音时段(用于查找章节分隔)
ffmpeg -i input.mp4 \
-af silencedetect=noise=-30dB:d=0.5 \
-f null - \
2>&1 | grep silence
# 生成音频波形图像
ffmpeg -i input.mp4 \
-filter_complex "showwavespic=s=1920x200:colors=blue" \
-frames:v 1 \
waveform.png
# 分析音量电平
ffmpeg -i input.mp4 \
-af volumedetect \
-f null - \
2>&1 | grep volume
# 提取音频频谱可视化
ffmpeg -i input.mp4 \
-filter_complex "showspectrumpic=s=1920x512:color=intensity" \
-frames:v 1 \
spectrum.png
7. AI 视觉分析工作流
提取帧,然后使用 Claude 的视觉能力分析它们,从视频内容中提取结构化信息。
# 步骤 1:探测视频
ffprobe -v quiet -print_format json -show_format -show_streams input.mp4
# 步骤 2:提取场景帧
mkdir -p analysis_frames
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)'" \
-vsync vfr \
-q:v 2 \
analysis_frames/frame_%04d.jpg
提取帧后,使用 Read 工具加载每个图像。Read 工具支持图像文件(PNG、JPG 等)并会以视觉方式呈现它们。对于每帧,分析:
- 颜色:提取主导十六进制颜色值、背景颜色、强调色
- 排版:识别字体大小、粗细、行高、标题层级
- 布局:检测网格模式、弹性布局、间距节奏、边距
- 组件:识别按钮、卡片、页眉、导航、表单
- 动画状态:注意过渡、悬停状态、加载指示器
跨所有帧聚合发现结果以构建一致的设计系统。
8. 从视频提取设计系统
一个从产品演示或 UI 导览视频中提取设计系统的完整工作流。
# 步骤 1:获取视频信息
ffprobe -v quiet -print_format json -show_format input.mp4
# 步骤 2:提取场景帧(捕获每个独特屏幕)
mkdir -p design_frames
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.4)'" \
-vsync vfr \
-q:v 1 \
design_frames/screen_%04d.png
# 步骤 3:也按固定间隔提取以增加覆盖
ffmpeg -i input.mp4 \
-vf "fps=1/3" \
-q:v 1 \
design_frames/interval_%04d.png
帧提取后,使用 AI 视觉分析每帧并编译:
{
"colors": {
"primary": "#2563EB",
"secondary": "#7C3AED",
"background": "#FFFFFF",
"surface": "#F3F4F6",
"text": "#111827",
"textSecondary": "#6B7280"
},
"typography": {
"headingFont": "Inter",
"bodyFont": "Inter",
"scale": ["12px", "14px", "16px", "20px", "24px", "32px", "48px"]
},
"spacing": {
"unit": "8px",
"scale": ["4px", "8px", "12px", "16px", "24px", "32px", "48px", "64px"]
},
"components": ["button", "card", "navbar", "sidebar", "input", "modal"]
}
反模式/常见错误
| 错误 | 为什么错 | 应该怎么做 |
|---|---|---|
| 从视频中提取每一帧 | 生成数千个文件,浪费磁盘和分析时间 | 使用场景检测或固定间隔(1 fps 或更少) |
| 在处理前跳过 ffprobe | 未知编码器或损坏文件导致 FFmpeg 静默失败 | 始终先探测以验证格式和属性 |
| 对批量帧提取使用 PNG | PNG 文件比 JPEG 大 5-10 倍,且对分析几乎无质量提升 | 使用 JPEG(-q:v 2)进行分析;仅对像素精确工作使用 PNG |
| 将场景阈值设置得太低(0.1) | 捕获相机运动、光照变化——产生太多帧 | 从 0.3-0.4 开始,根据结果调整 |
在使用 select 过滤器时忽略 -vsync vfr | 产生重复帧以填充时间线中的间隙 | 在使用 select 过滤器时始终使用 -vsync vfr |
| 分析帧时不带时间戳 | 无法将分析结果关联回视频时间线 | 使用 showinfo 过滤器捕获每帧的 pts_time |
| 对数百帧运行 AI 视觉 | 超出上下文限制并浪费 token | 每次分析限制在 10-20 个代表性帧 |
| 硬编码 FFmpeg 路径 | 在不同操作系统和安装方法间造成问题 | 直接使用 ffmpeg 和 ffprobe,依赖 PATH |
注意事项
-
-vsync vfr与 select 过滤器配合使用是必需的——没有-vsync vfr,FFmpeg 会通过重复帧来填充选定帧之间的“缺失”帧,以保持恒定帧率。这意味着提取 5 个场景变化帧可能产生 500 个输出文件,其中大部分是重复的。始终将select过滤器与-vsync vfr配对使用。 -
场景检测阈值因内容而异——0.3 的阈值对叙事视频中的剪切效果良好,但动画内容或屏幕录制可能需要 0.4-0.5,因为渐进的过渡会产生更低的场景分数。始终在提取后检查帧计数并调整阈值。
-
ffprobe 帧计数很慢——对 ffprobe 使用
-count_frames会解码整个视频以准确计数帧。对于长视频,这可能需要几分钟。请改用来自流元数据的nb_frames(准确性稍低但即时)或从时长和帧率估算。 -
音频静音检测参数需要调整——默认的
-30dB噪音阈值对于大多数内容来说可以接受,但嘈杂的环境音频或低音量录音可能需要更灵敏的设置,例如-50dB。调整基于预期用例:对于旁白视频,较高的阈值(-20dB)可仅捕获明显的停顿;对于环境录音,较低的阈值(-40dB)可检测微妙变化。 -
时间戳格式一致性——FFmpeg 时间戳可以多种格式出现(
pts_time: 90.5、pts_time: 0:01:30.500、或作为帧号)。在脚本之间解析时,使用-f csv以获得一致的输出格式,或使用-show_entries packet=pts_time以获得原始时间戳。 -
图像读取和 AI 视觉格式——部分 Read 工具实现可能更倾向于特定图像格式或颜色空间。对于 AI 视觉分析,坚持使用 sRGB JPEG(质量 85-95),因为这是最广泛支持的格式。避免使用 CMYK 图像或具有 alpha 通道的 PNG,因为它们在视觉分析模型中可能无法正确呈现。