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 并删除该文件）。

目录：

• 要求
• 安装
• 使用方法
  • 指标
  • 扩展选项
  • VMAF 特定设置
• 示例
• 使用 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

指标

此工具提供以下指标：

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

如果你想计算额外的指标，可以使用--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文档。

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

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

VMAF特征参数

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

参数以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"])

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

贡献者

Orkun Koçyiğit 💻

Hamas Shafiq 💻

Chris Griffith 💻

Ignacio Peletier 💻

Nav 🐛

许可证

ffmpeg-quality-metrics，版权所有 (c) 2019-2024 Werner Robitza

特此免费授予任何获得本软件及相关文档文件（"软件"）副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件副本的权利，以及允许向其提供本软件的人这样做，但须符合以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或主要部分中。

本软件按"原样"提供，不提供任何形式的明示或暗示保证，包括但不限于对适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为还是其他方面，均由软件或软件的使用或其他交易引起、源于或与之相关。

对于VMAF模型，请参阅ffmpeg_quality_metrics/vmaf_models/LICENSE。