Preserve color and HDR metadata safely

Color errors can survive a successful encode. Do not infer transfer, primaries, matrix, range, chroma location, mastering display, or content-light metadata from resolution or filename.

Inspect first

ffprobe -v error -select_streams v:0 \
  -show_entries stream=pix_fmt,color_range,color_space,color_transfer,color_primaries,chroma_location,side_data_list \
  -of json input.mkv

If essential fields are absent or contradict the mastering information, stop and resolve the source facts. Assigning metadata does not convert pixels. Converting transfer functions, primaries, range, or chroma requires an intentional color pipeline and a filter that supports the source and target.

Encode without silently discarding the question

• Keep a record of the probed source fields.
• Choose an encoder, profile, bit depth, and pixel format capable of the target signal.
• Pass explicit color options only when they describe the actual encoded pixels.
• Handle HDR10 mastering/content-light metadata and dynamic HDR metadata as separate requirements.
• Avoid a casual -pix_fmt yuv420p on high-bit-depth or HDR input.

For known BT.709 limited-range SDR pixels, explicit video signaling may look like:

-color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range tv

Those flags are not a generic fix and must not be pasted onto unknown or HDR material.

Validate

Probe the output with the same command, compare it to the intended target, decode the full output for errors, and inspect it through a color-managed playback path. A metadata match alone does not prove the pixel conversion is correct.

Primary references

• FFmpeg scaler and color options
• ffprobe stream and side-data output
• Encode Wiki colorimetry reference