ffmpeg-video-analysis

关键指南

Windows 文件路径要求

强制要求：在 Windows 上始终对文件路径使用反斜杠

在 Windows 上使用 Edit 或 Write 工具时，必须在文件路径中使用反斜杠（\），而不是正斜杠（/）。

---

快速参考

任务	滤镜	命令模式
检测黑帧	blackdetect	-vf blackdetect=d=0.5:pic_th=0.98
检测冻结帧	freezedetect	-vf freezedetect=n=0.003:d=2
检测模糊	blurdetect	-vf blurdetect=low=5:high=15
自动裁剪	cropdetect	-vf cropdetect=24:16:0
场景变化	scdet	-vf scdet=threshold=10
质量指标	psnr、ssim	-lavfi "[0:v][1:v]psnr" -f null -
帧信息	showinfo	-vf showinfo

何时使用此技能

用于质量控制和自动化工作流：

• 自动化视频分析流水线
• 检测有问题的帧（黑帧、冻结帧、模糊帧）
• 找出最佳裁剪参数
• 衡量编码后的质量
• 检查广播合规性
• 基于内容做出编辑决策

---

FFmpeg 视频分析滤镜（2025）

全面介绍用于质量控制、自动化和专业工作流的视频分析滤镜。

检测滤镜

blackdetect - 检测黑帧

检测完全黑屏的视频片段，可用于查找广告间隔、场景边界或编码问题。

# Basic black detection
ffmpeg -i input.mp4 -vf "blackdetect=d=0.5:pic_th=0.98:pix_th=0.10" -f null -

# More sensitive detection (darker threshold)
ffmpeg -i input.mp4 -vf "blackdetect=d=0.1:pic_th=0.90" -f null -

# Save detection results to log
ffmpeg -i input.mp4 -vf "blackdetect=d=0.5" -f null - 2>&1 | grep blackdetect

# Detect and extract black segments
ffmpeg -i input.mp4 -vf "blackdetect=d=2.0" -f null - 2>&1 | \
  grep -oP 'black_start:\K[0-9.]+|black_end:\K[0-9.]+'

参数：

参数	描述	默认值	范围
d	最短持续时间（秒）	2.0	> 0
pic_th	画面黑色比例阈值	0.98	0-1
pix_th	像素黑色阈值	0.10	0-1

输出格式：

[blackdetect @ 0x...] black_start:10.5 black_end:12.3 black_duration:1.8

blackframe - 检测近乎黑屏的帧

与 blackdetect 类似，但会报告单帧及其黑度。

# Detect frames that are 98% black
ffmpeg -i input.mp4 -vf "blackframe=amount=98:threshold=32" -f null -

# Output includes frame number and percentage
ffmpeg -i input.mp4 -vf "blackframe=amount=90" -f null - 2>&1 | grep blackframe

参数：

参数	描述	默认值	范围
amount	百分比阈值	98	0-100
threshold	像素亮度阈值	32	0-255

freezedetect - 检测冻结帧

检测视频看起来冻结（重复帧）的片段。

# Basic freeze detection
ffmpeg -i input.mp4 -vf "freezedetect=n=0.003:d=2" -f null -

# More sensitive (detect shorter freezes)
ffmpeg -i input.mp4 -vf "freezedetect=n=0.001:d=0.5" -f null -

# Very strict (only perfectly identical frames)
ffmpeg -i input.mp4 -vf "freezedetect=n=0:d=1" -f null -

参数：

参数	描述	默认值	范围
n	噪声容差（帧差）	0.001	0-1
d	最短冻结时长	2.0	> 0

输出格式：

[freezedetect @ 0x...] freeze_start: 45.2
[freezedetect @ 0x...] freeze_duration: 3.5
[freezedetect @ 0x...] freeze_end: 48.7

blurdetect - 检测模糊帧

检测失焦或因运动而模糊的帧。

# Basic blur detection
ffmpeg -i input.mp4 -vf "blurdetect=low=5:high=15:radius=50" -f null -

# More sensitive detection
ffmpeg -i input.mp4 -vf "blurdetect=low=3:high=10" -f null -

# Output blur values per frame
ffmpeg -i input.mp4 -vf "blurdetect,metadata=print:file=blur.txt" -f null -

参数：

参数	描述	默认值	范围
low	边缘低阈值	5	1-100
high	边缘高阈值	15	1-100
radius	搜索半径	50	1-100
block_pct	块百分比	80	0-100
block_width	块宽度	-	> 0
block_height	块高度	-	> 0
planes	要分析的平面	1	0-15

输出元数据：

• lavfi.blur - 模糊值（值越低表示越模糊）

scdet - 场景变化检测

根据相邻帧之间的差异检测场景变化。

# Basic scene detection
ffmpeg -i input.mp4 -vf "scdet=threshold=10:sc_pass=1" -f null -

# More sensitive (detect more scene changes)
ffmpeg -i input.mp4 -vf "scdet=threshold=5" -f null -

# Output scene changes with timestamps
ffmpeg -i input.mp4 -vf "scdet=t=10,metadata=print:file=scenes.txt" -f null -

# Combined with select filter to extract scene thumbnails
ffmpeg -i input.mp4 -vf "scdet=threshold=10,select='gt(scene,0.4)',showinfo" \
  -vsync vfr scene_%04d.jpg

参数：

参数	描述	默认值	范围
threshold / t	场景变化阈值	10.0	0-100
sc_pass	将场景分数传递到输出	0	0-1

输出元数据：

• lavfi.scd.score - 场景变化分数（0-1）
• lavfi.scd.mafd - 平均绝对帧差
• lavfi.scd.time - 场景变化的时间戳

cropdetect - 自动裁剪检测

自动检测最佳裁剪值，以去除黑边。

# Basic crop detection
ffmpeg -i input.mp4 -vf "cropdetect=24:16:0" -f null -

# More aggressive detection (lower threshold)
ffmpeg -i input.mp4 -vf "cropdetect=16:2:0" -f null -

# Detect and apply crop in one command
crop=$(ffmpeg -i input.mp4 -vf "cropdetect=24:16:0" -f null - 2>&1 | \
  grep -oP 'crop=\K[0-9:]+' | tail -1)
ffmpeg -i input.mp4 -vf "crop=$crop" output.mp4

# Detect letterbox dimensions
ffmpeg -i input.mp4 -vf "cropdetect=round=2:reset=0" -f null - 2>&1 | grep crop

参数：

参数	描述	默认值	范围
limit	黑色像素阈值	24	0-255
round	向最接近的倍数取整	16	>= 2
reset	重置计数器（帧）	0	>= 0
skip	跳过初始帧	0	>= 0

输出格式：

[cropdetect @ 0x...] x1:0 x2:1919 y1:140 y2:939 w:1920 h:800 x:0 y:140 crop=1920:800:0:140

idet - 隔行扫描检测

检测视频是否为隔行扫描，并识别场顺序。

# Basic interlace detection
ffmpeg -i input.mp4 -vf "idet" -frames:v 500 -f null -

# Output detection summary
ffmpeg -i input.mp4 -vf "idet" -f null - 2>&1 | grep -A5 "Repeated Fields"

输出包括：

• Single（逐行帧）
• Multi（隔行扫描——同一帧中的多个场）
• Repeated（重复场——下拉转换）
• 顶场优先（TFF）与底场优先（BFF）

---

质量指标

psnr - 峰值信噪比

比较两个视频并输出 PSNR 质量指标。

# Compare original vs encoded
ffmpeg -i original.mp4 -i encoded.mp4 \
  -lavfi "[0:v][1:v]psnr" -f null -

# Output PSNR per frame to file
ffmpeg -i original.mp4 -i encoded.mp4 \
  -lavfi "[0:v][1:v]psnr=stats_file=psnr.log" -f null -

# Get average PSNR only
ffmpeg -i original.mp4 -i encoded.mp4 \
  -lavfi "[0:v][1:v]psnr" -f null - 2>&1 | grep "average"

输出格式：

[Parsed_psnr_0 @ 0x...] PSNR y:45.123 u:48.456 v:49.789 average:46.234 min:35.123 max:inf

质量参考：

PSNR (dB)	质量
> 40	优秀（无法区分）
35-40	良好
30-35	一般
< 30	较差

ssim - 结构相似性指数

在质量比较中比 PSNR 更符合人眼感知。

# Compare original vs encoded
ffmpeg -i original.mp4 -i encoded.mp4 \
  -lavfi "[0:v][1:v]ssim" -f null -

# Output SSIM per frame to file
ffmpeg -i original.mp4 -i encoded.mp4 \
  -lavfi "[0:v][1:v]ssim=stats_file=ssim.log" -f null -

输出格式：

[Parsed_ssim_0 @ 0x...] SSIM Y:0.987 (18.87) U:0.992 (20.97) V:0.993 (21.55) All:0.989 (19.59)

质量参考：

SSIM	质量
> 0.98	优秀
0.95-0.98	良好
0.90-0.95	一般
< 0.90	较差

vmafmotion - VMAF 运动评分

计算 VMAF 使用的运动活跃度评分。

# Calculate motion score
ffmpeg -i input.mp4 -vf "vmafmotion" -f null - 2>&1 | grep vmafmotion

# Get average motion
ffmpeg -i input.mp4 -vf "vmafmotion" -f null - 2>&1 | tail -1

signalstats - 视频信号统计

用于广播质量控制的全面信号分析。

# Full signal analysis
ffmpeg -i input.mp4 -vf "signalstats=stat=tout+vrep+brng" -f null -

# Output to file
ffmpeg -i input.mp4 -vf "signalstats,metadata=print:file=stats.txt" -f null -

# Check for broadcast-safe levels
ffmpeg -i input.mp4 -vf "signalstats=stat=brng,metadata=print" -f null - 2>&1 | \
  grep "lavfi.signalstats.BRNG"

可用统计项：

统计项	描述
tout	时间异常值
vrep	垂直线重复
brng	超出广播范围

输出元数据包括：

• YMIN、YMAX - 亮度范围
• YAVG - 平均亮度
• UMIN、UMAX、VMIN、VMAX - 色度范围
• SATMIN、SATMAX、SATAVG - 饱和度
• HUEAVG - 平均色相
• BRNG - 超出广播范围的像素数量

---

帧信息

showinfo - 显示帧信息

输出每帧的详细信息。

# Show all frame info
ffmpeg -i input.mp4 -vf "showinfo" -f null -

# Show specific frames only
ffmpeg -i input.mp4 -vf "select='eq(n,0)+eq(n,100)',showinfo" -f null -

# Parse specific information
ffmpeg -i input.mp4 -vf "showinfo" -f null - 2>&1 | grep "pts_time"

输出包括：

[Parsed_showinfo_0 @ 0x...] n:   0 pts:      0 pts_time:0       duration:   1001
 duration_time:0.0417083 fmt:yuv420p cl:left sar:1/1 s:1920x1080 i:P iskey:1
 type:I checksum:12345678 plane_checksum:[AAAAAAAA BBBBBBBB CCCCCCCC]

字段：

• n - 帧编号
• pts - 显示时间戳
• pts_time - 以秒为单位的 PTS
• duration - 帧时长
• fmt - 像素格式
• s - 尺寸（分辨率）
• i - 是否隔行扫描（P=逐行，T=顶场，B=底场）
• iskey - 是否为关键帧
• type - 帧类型（I/P/B）

siti - 空间与时间信息

符合 ITU-T P.910 标准的 SI/TI 计算。

# Calculate SI/TI
ffmpeg -i input.mp4 -vf "siti" -f null - 2>&1 | grep siti

# Output to file
ffmpeg -i input.mp4 -vf "siti=print_summary=1" -f null -

输出：

• SI - 空间信息（边缘/纹理复杂度）
• TI - 时间信息（运动活跃度）

---

自动化模式

用于围绕 FFmpeg 检测滤镜、质量指标和帧信息进行批量分析、生成结构化报告、阈值检查和 CI 式验证的 Shell 自动化示例，位于 references/automation-patterns.md。将临时分析命令转为可重复的流水线时，请加载该参考文件。

---

最佳实践

1. 使用适当的阈值 - 从默认值开始，根据内容进行调整
2. 抽样分析长视频 - 先使用 -t 分析片段
3. 组合滤镜 - 串联检测滤镜以进行全面分析
4. 解析输出 - 使用 grep/awk 提取相关数据
5. 批量处理 - 创建脚本以保持质量控制工作流一致
6. 记录结果 - 使用 metadata=print:file= 保存结果

本指南涵盖 2025 年的视频分析滤镜。有关编码质量，请参阅 ffmpeg-fundamentals-2025。有关硬件加速分析，请查看 ffmpeg-hardware-acceleration 中的 GPU 滤镜支持。