How to Set libx264 Color Description in FFmpeg

This article explains how to configure color description parameters—specifically color primaries, transfer characteristics, and matrix coefficients—when encoding video using the libx264 library in FFmpeg. Properly setting these parameters ensures accurate color reproduction across different playback devices and streaming platforms, preventing issues like washed-out colors.

When encoding video with libx264, you should explicitly define the color space metadata using three primary flags: -color_primaries, -color_trc (transfer characteristics), and -colorspace (matrix coefficients). You can also define the luma range using the -color_range flag.

Core Color Description Parameters

1. -color_primaries: Defines the color gamut (the coordinate system of the red, green, and blue primaries).
2. -color_trc: Defines the transfer characteristics (the opto-electronic transfer function/gamma curve).
3. -colorspace: Defines the matrix coefficients used to convert RGB to YUV.
4. -color_range: Defines whether the color levels are limited (broadcast/TV) or full (PC).

Configuration Examples

1. Standard HD Video (BT.709)

For standard 1080p high-definition video, you should set these parameters to BT.709. This is the most common configuration for web delivery:

ffmpeg -i input.mp4 -c:v libx264 -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range tv output.mp4

2. Ultra HD / 4K SDR Video (BT.2020 SDR)

For 4K Standard Dynamic Range video, use the BT.2020 color space flags:

ffmpeg -i input.mp4 -c:v libx264 -color_primaries bt2020 -color_trc bt2020-10 -colorspace bt2020nc -color_range tv output.mp4

3. Full Range RGB to Limited Range YUV

If you are converting screen recordings or animations that use full-range RGB, it is best practice to enforce limited-range YUV with the correct matrix for standard web players:

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

Common Parameter Values

Explicitly declaring these values writes the metadata directly into the H.264 bitstream VUI (Video Usability Information) parameters. This guarantees that media players (like VLC, QuickTime, and web browsers) interpret and render the colors exactly as intended.