Video Color Tags and Signaling

Color signaling describes how a playback or conversion stage should interpret the component values of a video picture.

What should a renderer do with 102, 93, 186? Those three stored sample codes do not provide a complete color instruction. Their range and matrix establish how to reconstruct the encoded components, while primaries and transfer characteristics establish their color and light meaning.

Color signaling carries those instructions alongside coded or decoded pictures. An inspector's “color space” line is often only one field of that description.

A report with several independent fields

Here is an illustrative ffprobe-style description of an 8-bit SDR video stream:

pix_fmt=yuv420p
color_range=tv
color_space=bt709
color_transfer=bt709
color_primaries=bt709
chroma_location=left
Field What this example describes
pix_fmt The sample format reported for the stream: planar 8-bit 4:2:0
color_range Limited-range component coding; tv is this tool's label
color_space The BT.709 matrix interpretation for YCbCr
color_transfer BT.709 transfer characteristics
color_primaries BT.709 RGB primaries
chroma_location The left chroma-location convention

The three bt709 entries answer different questions. One matrix label cannot stand in for all three properties. Likewise, a 10-bit pixel format does not itself select PQ or make a picture HDR.

ffprobe can request just these stream fields:

ffprobe -v error -select_streams v:0 -show_entries stream=pix_fmt,color_range,color_space,color_transfer,color_primaries,chroma_location -of default=noprint_wrappers=1 "movie.mkv"

This inspects the source description. It is not a measurement of every intermediate hardware surface or the app's final display output. Those stages can use other formats and carry their own interpreted frame properties.

Metadata must describe the samples it accompanies

In the YCbCr worked example, limited-range BT.709 codes (102, 93, 186) reconstruct approximately to encoded RGB (0.80045, 0.30075, 0.10276). If a stage applies another matrix, its recovered color changes even though the coded bytes are intact.

That gives two different correction cases:

  1. Correct samples, wrong description. Repairing the description allows the intended calculation to be applied to existing samples.
  2. Samples genuinely converted to another representation. The output needs that new representation's description. Restoring old labels would tell the next stage to interpret the converted numbers incorrectly.

For example, a proper limited-to-full conversion changes nominal luma black from code 16 to 0 at 8 bits. Only relabeling the original 16 as full range instead raises its interpreted black. A parameter-marking operation and a numerical conversion serve different purposes. FFmpeg's setparams is an example of frame-property marking; its documentation distinguishes this from changing the samples.

Where the instructions can appear

Codec bitstreams can carry color description in video usability information. Containers can also carry color information through their own mappings. A decoder resolves the available description into properties attached to the decoded frame; filters can preserve or change those properties along with their output.

If a field is unspecified, a processing stage may use a standard-defined inference or a context-based assumption. A report of unknown therefore means that the inspected description has not supplied a definite value there. It should prompt examination of the stream's format and provenance, rather than an automatic choice based only on its pixel dimensions.

If descriptions disagree, the useful evidence includes where each value was found: container metadata, coded-stream signaling, or a decoder's interpreted output. Different playback stacks may handle an incomplete or conflicting description differently. Inspecting only the merged summary can hide that disagreement.

Comparing original and converted playback

For an Emby picture that changes color during conversion, start with the source and delivered video's complete field sets. Record the actual conversion that occurred too: a change in pixel layout is not necessarily a change in primaries, and a tone-mapped HDR picture needs an output description consistent with its SDR result.

Several symptoms suggest focused comparisons. Raised black points make range especially relevant. Changed colored objects with stable neutrals suggest checking the matrix. Misaligned color edges suggest chroma location. Unexpected brightness behavior calls for checking transfer interpretation and any HDR conversion.

These comparisons turn “the colors look wrong” into a question about the samples, the operation that changed them, and the description used to display the result.

See Also

References