FFmpeg libvpx-vp9 Logging and Debugging

When encoding video using the libvpx-vp9 library in FFmpeg, troubleshooting performance bottlenecks, quality degradation, or encoding failures requires access to detailed encoder metrics. This article provides a direct guide to the logging, verbosity, and debugging options available for libvpx-vp9 in FFmpeg, demonstrating how to extract encoder-specific diagnostic data during the compression process.

FFmpeg Verbosity Levels for libvpx-vp9

FFmpeg’s global -loglevel option controls the verbosity of the entire output, including the initialization parameters passed directly to the libvpx wrapper.

• Debug Level (-loglevel debug): This is the primary tool for inspecting encoder configuration. It prints the exact vpx_codec_enc_cfg_t structure passed to the VP9 library. You can verify whether your custom settings for threads, bitrate, deadline, and CPU-used are being correctly interpreted by the encoder.
• Trace Level (-loglevel trace): This level provides granular, packet-by-packet details. It shows frame-type decisions (such as Keyframes, Golden Frames, and Alt-Ref frames) as they are processed by the encoder pipeline.

Example command:

ffmpeg -loglevel debug -i input.mp4 -c:v libvpx-vp9 -b:v 2M output.webm

Quality and Metric Logging

To debug visual quality issues or rate-control behavior, you can force the libvpx-vp9 encoder to calculate and print quality metrics directly to the console.

PSNR Calculation

By enabling the PSNR (Peak Signal-to-Noise Ratio) setting, the encoder outputs frame-by-frame and global PSNR values upon completion.

• Command Option: -psnr (set to 1 or true)

ffmpeg -i input.mp4 -c:v libvpx-vp9 -b:v 2M -psnr 1 output.webm

Two-Pass Statistics Log

When performing two-pass encoding (-pass 1 and -pass 2), FFmpeg writes a statistics log file (defaulting to ffmpeg2pass-0.log). This file contains the frame-by-frame complexity data that the encoder uses to budget bits during the second pass. * To change the log prefix or location, use the -passlogfile option:

ffmpeg -i input.mp4 -c:v libvpx-vp9 -b:v 2M -pass 1 -passlogfile my_vp9_stats -f null /dev/null

Internal VP9 Debugging Parameters

The FFmpeg wrapper exposes several advanced private options for libvpx-vp9 that assist in debugging specific codec operations.

• -gop-stats-write-out <filename>: Writes Group of Pictures (GOP) statistics to a specified file. This is highly useful for debugging scene-cut detection and keyframe placement.
• -tune-content: While primarily a tuning option (e.g., default, screen, film), setting this improperly can lead to unexpected encoding behavior. Debugging with different content tunings helps isolate spatial/temporal compression issues.

Profiling Performance

If you are debugging slow encoding speeds or high CPU utilization, use FFmpeg’s global benchmark options to isolate system bottlenecks:

• -benchmark: Outputs CPU time, system time, and maximum virtual memory usage at the end of the encoding process.
• -benchmark_all: Provides real-time step-by-step performance metrics throughout the entire encode.

ffmpeg -benchmark -i input.mp4 -c:v libvpx-vp9 -b:v 2M output.webm