Configure FFmpeg Libtheora Color Space

This guide explains how to configure the color space options when encoding video using the libtheora encoder in FFmpeg. You will learn the specific command-line arguments and parameters required to define the color range, color primaries, transfer characteristics, and matrix coefficients to ensure accurate color reproduction in your Ogg Theora outputs.

Understanding Libtheora Color Constraints

The libtheora encoder primarily operates using the YUV color space, supporting the yuv420p, yuv422p, and yuv444p pixel formats. By default, Theora assumes standard-definition color properties (typically BT.601). To ensure media players render your video with the correct color profile (such as BT.709 for HD content), you must explicitly define the color metadata during the encoding process.

Command-Line Parameters for Color Space

FFmpeg uses four primary flags to configure color space metadata. These flags are passed to the output stream and inform the decoder how to interpret the color data:

• -colorspace: Specifies the matrix coefficients used to convert from RGB to YUV (e.g., bt709, bt470bg, smpte170m).
• -color_primaries: Defines the color primaries used (e.g., bt709, bt470bg, smpte170m).
• -color_trc: Sets the color transfer characteristics or gamma curve (e.g., bt709, linear, gamma22).
• -color_range: Determines the dynamic range of the color levels. Use tv (or mpeg) for limited range (16-235) and pc (or jpeg) for full range (0-255).

Step-by-Step Configuration Examples

1. Encoding with BT.709 (HD Standard)

To encode a video to Theora using the standard high-definition BT.709 color space with limited range, use the following command:

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

2. Encoding with BT.601 (SD Standard)

For standard-definition content, BT.601 (often represented as bt470bg or smpte170m) is the standard. Use this command:

ffmpeg -i input.mp4 -c:v libtheora -pix_fmt yuv420p -colorspace smpte170m -color_primaries smpte170m -color_trc smpte170m -color_range tv output.ogv

3. Forcing Full Color Range (PC Levels)

If your source video uses full-range color (0-255) and you want to preserve this range in the Theora output, set the -color_range flag to pc:

ffmpeg -i input.mp4 -c:v libtheora -pix_fmt yuv420p -colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range pc output.ogv

Verifying the Output Color Space

After encoding, you can verify that the color space metadata was correctly applied to the file using ffprobe:

ffprobe -show_streams output.ogv

Look for the color_range, color_space, color_transfer, and color_primaries lines in the output to confirm they match your specified configuration.