FFmpeg 质量指标

使用 FFmpeg 计算各种视频质量指标。

目前支持 PSNR、SSIM、VMAF 和 VIF。它将输出：

每帧指标
每个平面（Y、U、V）或组件/子指标（对于 VIF、VMAF）的指标
全局统计数据（最小值/最大值/平均值/标准差）

作者：Werner Robitza werner.robitza@gmail.com

**注意：**之前的版本安装了一个 ffmpeg_quality_metrics 可执行文件。为了与其他工具保持一致，现在可执行文件名为 ffmpeg-quality-metrics。请确保删除旧的可执行文件（例如，运行 which ffmpeg_quality_metrics 并删除该文件）。

目录：

要求
安装
使用方法
示例
使用 Docker 运行
输出
- JSON 输出
- CSV 输出
API
贡献者
许可证

要求

你需要：

操作系统：Linux、macOS、Windows
Python 3.8 或更高版本
FFmpeg：
- **Linux：**从这里下载 git master 构建版本。安装说明以及如何将 FFmpeg 和 FFprobe 添加到 PATH 中可以在这里找到。
- **macOS：**从这里下载快照构建版本或通过 brew install ffmpeg 安装。
- **Windows：**从这里下载 FFmpeg 二进制文件。git essentials 构建版本就足够了。

将 ffmpeg 可执行文件放入你的 $PATH 中。

如果你想计算 VMAF，你的 ffmpeg 构建版本应包含 libvmaf 2.3.1 或更高版本。上述静态构建版本或 Homebrew ffmpeg v5.1 包中已包含此版本。

安装

使用 pip：

pip3 install ffmpeg-quality-metrics

或克隆此仓库，然后使用 python3 -m ffmpeg_quality_metrics 运行工具。

使用方法

最简单的情况是，如果你有一个失真（编码，可能缩放）版本和参考版本：

ffmpeg-quality-metrics distorted.mp4 reference.y4m

失真文件将自动缩放到参考文件的分辨率，并计算默认指标（PSNR、SSIM）。

请注意，如果你的失真文件与参考文件不同步，你可以使用 --dist-delay 选项将失真文件延迟一定秒数（正数或负数）。

[!注意] 此工具无法读取原始 YUV 文件。我们应该使用无损容器格式，如 Y4M 或 FFV1。如果你有原始 YUV 文件，可以使用 FFmpeg 将其转换为此工具可以读取的格式。根据需要调整选项。
ffmpeg -framerate 24 -video_size 1920x1080 -pix_fmt yuv420p -i input.yuv output.y4m

指标

此工具提供以下指标：

指标	描述	范围	组成部分/子指标	是否默认计算?
PSNR	峰值信噪比	分贝	`mse_avg`<br> `mse_y`<br> `mse_u`<br> `mse_v`<br> `psnr_avg`<br> `psnr_y`<br> `psnr_u`<br> `psnr_v`	✔️
SSIM	结构相似性	0-100（越高越好）	`ssim_y`<br> `ssim_u`<br> `ssim_v`<br> `ssim_avg`	✔️
VMAF	视频多方法评估融合	0-100（越高越好）	`vmaf`<br> `integer_adm2`<br> `integer_adm_scale0`<br> `integer_adm_scale1`<br> `integer_adm_scale2`<br> `integer_adm_scale3`<br> `integer_motion2`<br> `integer_motion`<br> `integer_vif_scale0`<br> `integer_vif_scale1`<br> `integer_vif_scale2`<br> `integer_vif_scale3`	否
VIF	视觉信息保真度	0-100（越高越好）	`scale_0`<br> `scale_1`<br> `scale_2`<br> `scale_3`	否

如表所示，每个指标可以计算多个子指标，它们都会在输出中显示。

如果你想计算额外的指标，可以使用--metrics选项启用它们：

ffmpeg-quality-metrics distorted.mp4 reference.avi --metrics psnr ssim vmaf

通过用空格分隔多个指标来指定（例如，在上面的例子中，psnr ssim vmaf）。

在这里，VMAF使用默认模型。你可以使用--vmaf-model选项指定不同的模型。VMAF还允许你计算更多额外特征作为子指标。你可以使用--vmaf-features选项启用这些特征。

扩展选项

你可以配置与缩放、速度等相关的额外选项。

查看ffmpeg-quality-metrics -h：

用法: ffmpeg-quality-metrics [-h] [-n] [-v] [-p] [-k] [--tmp-dir TMP_DIR]
                              [-m {vmaf,psnr,ssim,vif} [{vmaf,psnr,ssim,vif} ...]]
                              [-s {fast_bilinear,bilinear,bicubic,experimental,neighbor,area,bicublin,gauss,sinc,lanczos,spline}]
                              [-r FRAMERATE] [--dist-delay DIST_DELAY] [-t THREADS] [-of {json,csv}]
                              [--vmaf-model-path VMAF_MODEL_PATH]
                              [--vmaf-model-params VMAF_MODEL_PARAMS [VMAF_MODEL_PARAMS ...]]
                              [--vmaf-threads VMAF_THREADS] [--vmaf-subsample VMAF_SUBSAMPLE]
                              [--vmaf-features VMAF_FEATURES [VMAF_FEATURES ...]]
                              dist ref

ffmpeg-quality-metrics v3.2.1

位置参数:
  dist                                  输入文件，失真视频
  ref                                   输入文件，参考视频

选项:
  -h, --help                            显示此帮助信息并退出

常规选项:
  -n, --dry-run                         不运行命令，只显示将要执行的操作（默认：False）
  -v, --verbose                         显示详细输出（默认：False）
  -p, --progress                        显示进度条（默认：False）
  -k, --keep-tmp                        保留临时文件用于调试（默认：False）
  --tmp-dir TMP_DIR                     存储临时文件的目录（如果未指定将使用系统默认目录）（默认：None）

指标选项:
  -m {vmaf,psnr,ssim,vif} [{vmaf,psnr,ssim,vif} ...], --metrics {vmaf,psnr,ssim,vif} [{vmaf,psnr,ssim,vif} ...]
                                        要计算的指标。指定多个指标，如'--metrics ssim vmaf'（默认：['psnr', 'ssim']）

FFmpeg选项:
  -s {fast_bilinear,bilinear,bicubic,experimental,neighbor,area,bicublin,gauss,sinc,lanczos,spline}, --scaling-algorithm {fast_bilinear,bilinear,bicubic,experimental,neighbor,area,bicublin,gauss,sinc,lanczos,spline}
                                        FFmpeg的缩放算法（默认：bicubic）
  -r FRAMERATE, --framerate FRAMERATE   强制输入帧率（默认：None）
  --dist-delay DIST_DELAY               将失真视频相对于参考视频延迟指定的秒数（默认：0.0）
  -t THREADS, --threads THREADS         用于计算的线程数（默认：0）

输出选项:
  -of {json,csv}, --output-format {json,csv}
                                        指标的输出格式（默认：json）

VMAF选项: --vmaf-model-path VMAF_MODEL_PATH 使用特定的VMAF模型文件。如果未指定,将选择默认模型。您也可以指定以下内置模型之一:['vmaf_v0.6.1.json', 'vmaf_4k_v0.6.1.json', 'vmaf_v0.6.1neg.json'] (默认:/opt/homebrew/opt/libvmaf/share/libvmaf/model/vmaf_v0.6.1.json) --vmaf-model-params VMAF_MODEL_PARAMS [VMAF_MODEL_PARAMS ...] 传递给VMAF模型的参数列表,以key=value的形式指定。指定多个参数,例如'--vmaf-model-params enable_transform=true enable_conf_interval=true'(默认:无) --vmaf-threads VMAF_THREADS 设置libvmaf的n_threads选项的值。这决定了用于VMAF计算的线程数。设置为0表示自动。(默认:0) --vmaf-subsample VMAF_SUBSAMPLE 设置libvmaf的n_subsample选项的值。这是子采样间隔, 设置为1表示默认行为。(默认:1) --vmaf-features VMAF_FEATURES [VMAF_FEATURES ...] 要启用的特征列表。传入特征名称和任何可选参数。参见https://github.com/Netflix/vmaf/blob/master/resource/doc/features.md 了解可用特征列表。参数必须指定为'key=value'。多个参数必须用':'分隔。指定多个特征,例如 '--vmaf-features cambi:full_ref=true ciede'(默认:无)

VMAF特定设置

由于VMAF比其他指标更复杂,因此它有更多选项。

指定VMAF模型

使用--vmaf-model-path选项设置不同VMAF模型文件的路径。默认为vmaf_v0.6.1.json。

libvmaf 2.x版本仅支持基于JSON的模型文件。该程序内置支持以下模型:

vmaf_v0.6.1.json vmaf_4k_v0.6.1.json vmaf_v0.6.1neg.json

如果您有4K参考样本,请使用4k版本。neg版本的解释请参见此处。

您可以指定现有模型的绝对路径,例如:

/usr/local/opt/libvmaf/share/model/vmaf_v0.6.1neg.json

或将文件名传递给内置模型。因此,以下都可以:

对libvmaf 2.x使用下载的JSON模型

ffmpeg-quality-metrics dist.mkv ref.mkv -m vmaf --vmaf-model-path vmaf_v0.6.1neg.json

使用系统上模型的不同路径

ffmpeg-quality-metrics dist.mkv ref.mkv -m vmaf --vmaf-model-path /usr/local/opt/libvmaf/share/model/vmaf_v0.6.1neg.json

指定VMAF特征

VMAF包含几个指标,每个指标对应一个特征名称。默认情况下,只使用三个核心特征。使用--vmaf-features选项在核心特征之外启用额外特征。

下表显示了可用的特征:

指标	特征名称	VMAF中的核心特征?
PSNR	psnr
PSNR-HVS	psnr_hvs
CIEDE2000	ciede
CAMBI	cambi
VIF	vif	✔️
ADM	adm	✔️
Motion	motion	✔️
SSIM	float_ssim
MS-SSIM	float_ms_ssim

要了解更多关于这些特征的信息,请查看VMAF文档。

例如,要启用CAMBI特征,使用:

ffmpeg-quality-metrics dist.mkv ref.mkv -m vmaf --vmaf-features cambi

VMAF特征参数

某些特征还可以接受一些可选参数。下表显示了每个特征可用的参数:

功能	参数	默认值	描述
`adm`	`adm_csf_mode`	`0`	对比度敏感度函数
`adm`	`adm_enhn_gain_limit`	`100.0`	施加在adm上的增强增益，必须 >= 1.0，其中1.0表示增益完全禁用
`adm`	`adm_norm_view_dist`	`3.0`	标准化观看距离 = 观看距离 / 参考显示器的物理高度
`adm`	`adm_ref_display_height`	`1080`	参考显示器高度（像素）
`adm`	`debug`	`false`	调试模式：启用额外输出
`cambi`	`enc_bitdepth`		编码位深
`cambi`	`enc_height`		编码高度
`cambi`	`enc_width`		编码宽度
`cambi`	`eotf`	`bt1886`	确定用于计算可见性阈值的EOTF
`cambi`	`full_ref`	`false`	设为`true`以启用全参考CAMBI计算
`cambi`	`heatmaps_path`		设置目标文件夹，CAMBI热图将以`.gray`文件形式存储在此
`cambi`	`max_log_contrast`	`2`	10位下的最大对数亮度对比度（2^max_log_contrast）
`cambi`	`src_height`		源高度。仅在full_ref=true时使用
`cambi`	`src_width`		源宽度。仅在full_ref=true时使用
`cambi`	`topk`	`0.2`	空间池化计算的像素比例
`cambi`	`tvi_threshold`	`0.75`	亮度可见性阈值 ΔL < tvi_threshold*L_mean
`cambi`	`window_size`	`63`	计算CAMBI的窗口大小：63对应4k分辨率下约1度视角
`motion`	`debug`	`true`	启用额外调试输出
`motion`	`motion_force_zero`	`false`	强制运动分数为零。这是一个特定功能参数
`ms_ssim`	`clip_db`	`false`	裁剪dB分数
`ms_ssim`	`enable_db`	`false`	以dB形式输出MS-SSIM值
`ms_ssim`	`enable_lcs`	`false`	启用亮度、对比度和结构的中间输出
`ssim`	`clip_db`	`false`	裁剪dB分数
`ssim`	`enable_db`	`false`	以dB形式输出SSIM值
`ssim`	`enable_lcs`	`false`	启用亮度、对比度和结构的中间输出
`vif`	`debug`	`false`	调试模式：启用额外输出
`vif`	`vif_enhn_gain_limit`	`100.0`	施加在vif上的增强增益，必须 >= 1.0，其中1.0表示增益完全禁用
`vif`	`vif_kernelscale`	`1.0`	高斯核的缩放因子（2.0表示将标准差乘以2并相应地扩大核大小）

参数以key=value对的形式指定，用:分隔。例如，要启用全参考CAMBI计算，使用：

ffmpeg-quality-metrics dist.mkv ref.mkv -m vmaf --vmaf-features cambi:full_ref=true

要生成CAMBI热图，使用：

ffmpeg-quality-metrics dist.mkv ref.mkv -m vmaf --vmaf-features cambi:heatmaps_path=/tmp/cambi

示例

同时运行PSNR、SSIM、VMAF和VIF：

ffmpeg-quality-metrics dist.mkv ref.mkv \
    -m psnr ssim vmaf vif

运行VMAF及其所有特性：

ffmpeg-quality-metrics dist.mkv ref.mkv \
    -m vmaf \
    --vmaf-features ciede cambi psnr psnr_hvs motion adm vif

为CAMBI全参考计算启用特性选项：

ffmpeg-quality-metrics dist.mkv ref.mkv \
    -m vmaf \
    --vmaf-features cambi:full_ref=true

使用Docker运行

如果你不想处理依赖问题，可以用Docker构建镜像：

docker build -t ffmpeg-quality-metrics .

这需要几分钟时间，并会安装最新的ffmpeg静态构建版。

然后你可以运行容器，它基本上是调用Python脚本。为了帮助你挂载卷（因为你的视频不存储在容器中），你可以运行一个辅助脚本：

./docker_run.sh <dist> <ref> [选项]

查看./docker_run.sh的输出以获取更多帮助。

例如，要使用捆绑的测试视频并启用VMAF计算，运行：

./docker_run.sh test/dist-854x480.mkv test/ref-1280x720.mkv -m vmaf

输出

此工具支持JSON或CSV输出，包括飞机/组件/子指标的单独字段、全局统计数据以及帧号（n）。

JSON输出

JSON输出将为每个指标包含一个键，其值是每帧的值列表。每帧是一个包含每帧单独指标的字典。

例如，PSNR和SSIM输出平均值以及每个组件的指标。VMAF根据启用的功能输出不同的指标。

global键包含每个指标及其子指标的全局统计数据。

有关输出示例，请参阅example.json文件。

CSV输出

CSV输出采用整洁数据原则，每个特征使用一列，每帧（观察）使用一行。

示例：

n,adm2,motion2,ms_ssim,psnr,ssim,vif_scale0,vif_scale1,vif_scale2,vif_scale3,vmaf,mse_avg,mse_u,mse_v,mse_y,psnr_avg,psnr_u,psnr_v,psnr_y,ssim_avg,ssim_u,ssim_v,ssim_y,input_file_dist,input_file_ref
1,0.70704,0.0,0.89698,18.58731,0.92415,0.53962,0.71805,0.75205,0.77367,15.44212,536.71,234.48,475.43,900.22,20.83,24.43,21.36,18.59,0.945,0.96,0.942,0.934,test/dist-854x480.mkv,test/ref-1280x720.mkv
2,0.7064,0.35975,0.89806,18.60299,0.9247,0.54025,0.71961,0.75369,0.77607,15.85038,535.29,239.4,469.49,896.98,20.84,24.34,21.41,18.6,0.946,0.96,0.943,0.934,test/dist-854x480.mkv,test/ref-1280x720.mkv
3,0.70505,0.35975,0.89879,18.6131,0.92466,0.5391,0.71869,0.75344,0.77616,15.63546,535.04,245.8,464.43,894.89,20.85,24.22,21.46,18.61,0.945,0.959,0.943,0.934,test/dist-854x480.mkv,test/ref-1280x720.mkv

由于在同一CSV文件中没有整洁的方式来表示全局数据，您可以使用其他工具来聚合数据。

API

该程序提供了一个您可以自行使用的API：

from ffmpeg_quality_metrics import FfmpegQualityMetrics

ffqm = FfmpegQualityMetrics("path/to/reference-video.mp4", "path/to/distorted-video.mp4")

metrics = ffqm.calculate(["ssim", "psnr"])

# 检查可用的指标
print(metrics.keys())
# ['ssim', 'psnr']

# 获取第一帧的SSIM值
print(metrics["ssim"][0])
# {'n': 1, 'ssim_y': 0.934, 'ssim_u': 0.96, 'ssim_v': 0.942, 'ssim_avg': 0.945}

# 计算所有帧的ssim_y值的平均值
print(sum([frame["ssim_y"] for frame in metrics["ssim"]]) / len(metrics["ssim"]))

# 或者只获取全局统计数据
print(ffqm.get_global_stats()["ssim"]["ssim_y"]["average"])

有关更多用法，请阅读文档。

贡献者

<table> <tbody> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/OrkunKocyigit"><img src="https://avatars.githubusercontent.com/u/10797423?v=4?s=100" width="100px;" alt="Orkun Koçyiğit"/> Orkun Koçyiğit</a> <a href="https://github.com/slhck/ffmpeg-quality-metrics/commits?author=OrkunKocyigit" title="代码">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/CrypticSignal"><img src="https://avatars.githubusercontent.com/u/48166845?v=4?s=100" width="100px;" alt="Hamas Shafiq"/> Hamas Shafiq</a> <a href="https://github.com/slhck/ffmpeg-quality-metrics/commits?author=CrypticSignal" title="代码">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="http://codecalamity.com/"><img src="https://avatars.githubusercontent.com/u/3275435?v=4?s=100" width="100px;" alt="Chris Griffith"/> Chris Griffith</a> <a href="https://github.com/slhck/ffmpeg-quality-metrics/commits?author=cdgriffith" title="代码">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="http://codecalamity.com/"><img src="https://avatars.githubusercontent.com/u/17472224?v=4?s=100" width="100px;" alt="Ignacio Peletier"/> Ignacio Peletier</a> <a href="https://github.com/slhck/ffmpeg-quality-metrics/commits?author=Sorkanius" title="代码">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/nav9"><img src="https://avatars.githubusercontent.com/u/2093933?v=4?s=100" width="100px;" alt="Nav"/> Nav</a> <a href="https://github.com/slhck/ffmpeg-quality-metrics/issues?q=author%3Anav9" title="错误报告">🐛</a></td> </tr> </tbody> </table>