Colour & HDR

How colour is read from a source, pinned across every worker, converted between HDR and SDR, and declared alongside proxies.

Colour is the property most vulnerable to distributed processing: an inconsistency can pass unnoticed until it is expensive to correct. This page describes the mechanisms that protect colour and the decisions that remain with the operator.

The distributed colour risk#

In a single-machine encode, colour is interpreted once. The encoder's interpretation, correct or not, applies to the whole file, so any error is at least consistent.

Distributing the encode removes that consistency. If one worker reads a source as one transfer function and another reads it differently — because of a different FFmpeg build, a different default, or absent metadata that must be inferred — the result is a file whose appearance changes partway through. Every frame is individually valid, but the file is unusable, and the fault resembles a grade error rather than a transcode error.

Source colour properties#

Before planning any work, the source's colour properties are read rather than assumed:

• Primaries — the colour gamut the values are expressed in.
• Transfer characteristics — the curve, including the PQ and HLG curves used for HDR.
• Matrix coefficients — how colour difference is encoded.
• Range — limited or full.
• Bit depth.
• HDR10 mastering display metadata, where the source carries it.

The colour signature#

Those properties are combined into a single fingerprint, and that fingerprint is pinned to the job. Every chunk carries it, and every worker encodes against the same interpretation rather than making its own.

At assembly the signatures are checked. Chunks whose colour signature does not match are refused, not blended into the output.

HDR and tone-mapping#

Converting between HDR and SDR is a filter chain built from what was actually read, not a fixed recipe. Both common HDR transfer functions are recognised — PQ, as used by HDR10, and HLG.

HDR-to-SDR conversion requires particular care. It is not a format change; it is a creative compression of a larger dynamic range into a smaller one, and any automatic tone-map applies one interpretation of how that compression should be performed.

Proxy colour declarations#

Every colour-managed proxy is written with a sibling file describing the colour space it was produced in: a small JSON document beside the media.

A proxy separated from the context that produced it has no recorded colour interpretation, and an inferred interpretation can result in a cut being graded against material that does not match the finishing source. Carrying the declaration with the file keeps the interpretation with the media.

ACES and OCIO#

Colour management is done through OCIO, and an ACES studio configuration ships inside the master bundle. There is nothing to install and no path to point at for the standard case.

Where a look-up table is part of the pipeline, it is baked as a step rather than applied by hand afterwards. The intended transform is therefore the applied transform on every frame and every worker, without depending on a manual operator step.

The tooling this relies on ships with the master. Confirm it resolves before committing a show to a colour-managed pipeline:

$ master probe-v-deps

Operational notes#

• Test one clip through the full path before a shoot. Colour problems are systematic: if the first file is wrong, every file is wrong, and discovering this after a week of ingest is expensive.
• Prefer sources that carry their colour metadata. When metadata is absent it must be inferred, and inference is where inconsistency enters. Camera presets exist partly for this reason; see Choosing a preset.
• Keep the fleet on one release. Mixed FFmpeg builds are the most likely source of two workers disagreeing about colour.
• Treat a refused chunk as diagnostic information. A rejected mismatch means the check operated correctly. Determine why the signature differed rather than bypassing the check.