FFmpeg 音视频处理

Requirements

What you need:

• OS: Linux, macOS, Windows
• Python 3.9 or higher
• FFmpeg 7.1 or higher:
• Linux: Download a build matching your platform from here.
• macOS: Download the snapshot build from here or install via brew install ffmpeg.
• Windows: Download an FFmpeg binary from here. The git essentials build will suffice.

Put the ffmpeg executable in your $PATH, e.g. /usr/local/bin/ffmpeg.

If you want to calculate VMAF, your ffmpeg build should include libvmaf. You also need the VMAF model files, which we bundle with this package, or you can download them from the VMAF GitHub.

Using uv:

uvx ffmpeg-quality-metrics

Using pipx:

pipx install ffmpeg-quality-metrics

Or, using pip:

pip3 install --user ffmpeg-quality-metrics

Running with Docker

You can use the pre-built image from Docker Hub:

docker run -v "$(pwd):/videos" -it slhck/ffmpeg-quality-metrics

Alternatively, download this repository and run

docker build -t ffmpeg-quality-metrics .

You can then run the container, which basically calls the Python script. To help you with mounting the volumes (since your videos are not stored in the container), you can run a helper script:

./docker_run.sh <dist> <ref> [OPTIONS]

Check the output of ./docker_run.sh for more help.

For example, to run the tool with the bundled test videos and enable VMAF calculation:

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

Installation

To use the GUI features, you need to install the optional gui dependencies.

Using uvx (recommended, no installation needed), you can run it directly:

```bash

Usage

In the simplest case, if you have a distorted (encoded, maybe scaled) version and the reference:

ffmpeg-quality-metrics distorted.mp4 reference.y4m

The distorted file will be automatically scaled to the resolution of the reference, and the default metrics (PSNR, SSIM) will be computed.

Note that if your distorted file is not in time sync with the reference, you can use the --dist-delay option to delay the distorted file by a certain amount of seconds (positive or negative).

[!NOTE] Raw YUV files cannot be read with this tool. We should all be using lossless containers like Y4M or FFV1. If you have a raw YUV file, you can use FFmpeg to convert it to a format that this tool can read. Adjust the options as needed.

> ffmpeg -framerate 24 -video_size 1920x1080 -pix_fmt yuv420p -i input.yuv output.y4m
> 

Examples

Run PSNR, SSIM, VMAF and VIF at the same time:

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

Run VMAF with all the features:

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

Enable feature options for CAMBI full-reference calculation:

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

Extended Options

You can configure additional options related to scaling, speed etc.

See ffmpeg-quality-metrics -h:

usage: ffmpeg-quality-metrics [-h] [-n] [-v] [-p] [-k] [--tmp-dir TMP_DIR]
                              [-m {vmaf,psnr,ssim,vif,msad} [{vmaf,psnr,ssim,vif,msad} ...]]
                              [-s {fast_bilinear,bilinear,bicubic,experimental,neighbor,area,bicublin,gauss,sinc,lanczos,spline}]
                              [-r FRAMERATE] [--dist-delay DIST_DELAY] [-t THREADS]
                              [--num-frames NUM_FRAMES] [--start-offset START_OFFSET]
                              [--ffmpeg-path FFMPEG_PATH]
                              [-o OUTPUT_FILE] [-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.4.2

positional arguments:
  dist                                  input file, distorted
  ref                                   input file, reference

options:
  -h, --help                            show this help message and exit

General options:
  -n, --dry-run                         Do not run commands, just show what would be done (default:
                                        False)
  -v, --verbose                         Show verbose output (default: False)
  -p, --progress                        Show a progress bar (default: False)
  -k, --keep-tmp                        Keep temporary files for debugging purposes (default: False)
  --tmp-dir TMP_DIR                     Directory to store temporary files in (will use system
                                        default if not specified) (default: None)

Metric options:
  -m {vmaf,psnr,ssim,vif,msad} [{vmaf,psnr,ssim,vif,msad} ...], --metrics {vmaf,psnr,ssim,vif,msad} [{vmaf,psnr,ssim,vif,msad} ...]
                                        Metrics to calculate. Specify multiple metrics like '--
                                        metrics ssim vmaf' (default: ['psnr', 'ssim'])

FFmpeg options:
  -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}
                                        Scaling algorithm for ffmpeg (default: bicubic)
  -r FRAMERATE, --framerate FRAMERATE   Force an input framerate (default: None)
  --dist-delay DIST_DELAY               Delay the distorted video against the reference by this many
                                        seconds (default: 0.0)
  -t THREADS, --threads THREADS         Number of threads to do the calculations (default: 0)
  --num-frames NUM_FRAMES               Number of frames to analyze from the input files (default: all
                                        frames)
  --start-offset START_OFFSET           Seek to this position before analyzing. Accepts timestamp (e.g.,
                                        '00:00:10' or '10.5') or frame number with 'f:' prefix (e.g.,
                                        'f:100'). Note: seeking may not be frame-accurate due to keyframe
                                        constraints. (default: None)
  --ffmpeg-path FFMPEG_PATH             Path to ffmpeg executable (default: ffmpeg)

Output options:
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                                        Output file for the metrics. If not specified, stdout will
                                        be used. (default: None)
  -of {json,csv}, --output-format {json,csv}
                                        Output format for the metrics (default: json)

VMAF options:
  --vmaf-model-path VMAF_MODEL_PATH     Use a specific VMAF model file. If none is chosen, picks a
                                        default model. You can also specify one of the following
                                        built-in models: ['vmaf_v0.6.1.json', 'vmaf_4k_v0.6.1.json',
                                        'vmaf_v0.6.1neg.json'] (default: /opt/homebrew/opt/libvmaf/s
                                        hare/libvmaf/model/vmaf_v0.6.1.json)
  --vmaf-model-params VMAF_MODEL_PARAMS [VMAF_MODEL_PARAMS ...]
                                        A list of params to pass to the VMAF model, specified as
                                        key=value. Specify multiple params like '--vmaf-model-params
                                        enable_transform=true enable_conf_interval=true' (default:
                                        None)
  --vmaf-threads VMAF_THREADS           Set the value of libvmaf's n_threads option. This determines
                                        the number of threads that are used for VMAF calculation.
                                        Set to 0 for auto. (default: 0)
  --vmaf-subsample VMAF_SUBSAMPLE       Set the value of libvmaf's n_subsample option. This is the
                                        subsampling interval, so set to 1 for default behavior.
                                        (default: 1)
  --vmaf-features VMAF_FEATURES [VMAF_FEATURES ...]
                                        A list of feature to enable. Pass the names of the features
                                        and any optional params. See https://github.com/Netflix/vmaf
                                        /blob/master/resource/doc/features.md for a list of
                                        available features. Params must be specified as 'key=value'.
                                        Multiple params must be separated by ':'. Specify multiple
                                        features like '--vmaf-features cambi:full_ref=true ciede'
                                        (default: None)

Seeking and Frame Selection

You can control which portion of the input videos to analyze using the --start-offset and --num-frames options.

To analyze only a specific number of frames (e.g., for faster processing or testing), use the --num-frames option:

ffmpeg-quality-metrics distorted.mp4 reference.y4m --num-frames 100

To skip the beginning of the video and start analysis at a specific position, use the --start-offset option. This accepts either a timestamp or a frame number:

```bash

VMAF-specific Settings

As VMAF is more complex than the other metrics, it has a few more options.

Specifying VMAF Model

Use the --vmaf-model-path option to set the path to a different VMAF model file. The default is vmaf_v0.6.1.json.

libvmaf version 2.x supports JSON-based model files only. This program has built-in support for the following models:

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

Use the 4k version if you have a 4K reference sample. The neg version is explained here.

You can either specify an absolute path to an existing model, e.g.:

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

Or pass the file name to the built-in model. So all of these work:

```bash

API

The program exposes an API that you can use yourself:

```python from ffmpeg_quality_metrics import FfmpegQualityMetrics

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

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