Configure VP9 Color Space in FFmpeg with libvpx

This guide explains how to properly configure color description parameters—including color primaries, transfer characteristics, matrix coefficients, and color range—when encoding video using the libvpx or libvpx-vp9 encoder in FFmpeg. Correctly defining these parameters ensures that your WebM videos render with accurate, consistent colors across different web browsers, devices, and media players.

To configure color descriptions in FFmpeg for libvpx, you must pass specific metadata flags during the encoding process. Without these flags, players may guess the color space, leading to washed-out colors or shifted hues.

Key Color Parameter Flags

FFmpeg uses four primary arguments to define color properties. These flags work seamlessly with the libvpx-vp9 encoder:

  • -color_primaries: Defines the color gamut (the range of colors the video can display). Common values include bt709 (standard HD), bt2020 (UHD/HDR), and smpte170m (NTSC/SD).
  • -color_trc: Defines the transfer characteristics, which dictate the gamma curve. Common values include bt709 (standard HD), smpte2084 (HDR10/PQ), arib-std-b67 (HLG), and iec61966-2-1 (sRGB).
  • -colorspace: Defines the matrix coefficients used to convert RGB colors to YUV. Common values include bt709 (HD), bt2020nc (UHD non-constant luminance), and smpte170m (SD).
  • -color_range: Defines the luminance range. Use tv (or limited) for standard broadcast range (16-235 for 8-bit), or pc (or jpeg/full) for full range (0-255).

Command Examples

1. Standard HD Video (BT.709)

For standard high-definition web video, you should explicitly tag the file as BT.709. This is the most common configuration for SDR (Standard Dynamic Range) content.

ffmpeg -i input.mp4 -c:v libvpx-vp9 -pix_fmt yuv420p -colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv output.webm

2. High Dynamic Range Video (HDR10 / BT.2020)

If you are encoding HDR content with the VP9 profile 2 (10-bit), you must use BT.2020 color primaries and the PQ (SMPTE 2084) transfer function.

ffmpeg -i input_hdr.mp4 -c:v libvpx-vp9 -pix_fmt yuv420p10le -colorspace bt2020nc -color_primaries bt2020 -color_trc smpte2084 -color_range tv output_hdr.webm

Verifying the Metadata

After encoding, you can verify that the color description parameters were written correctly to the container using ffprobe:

ffprobe -of default=noprint_wrappers=1 -show_entries stream=color_space,color_primaries,color_transfer,color_range output.webm

This command will output the detected color space properties, confirming that your libvpx output is correctly configured for accurate playback.