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 thing distribution can break in a way nobody notices until it is expensive. This page covers what protects it and where you still have to make a decision.
The distributed colour risk#
In a single-machine encode, colour is interpreted once. Whatever the encoder decided, it decided for the whole file, and any mistake is at least consistent.
Split that across machines and consistency stops being free. 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 metadata that is absent and has to be guessed — the result is a file whose appearance changes partway through. Every frame is valid. The file is unusable, and the problem looks like a grade error rather than a transcode error.
What is read from a source#
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.
A mismatch becomes a failed job with a stated reason, rather than a delivered file that shifts halfway through. Of everything in this documentation, this is the mechanism that most directly earns the right to split a professional encode across machines.
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.
The direction that needs care is HDR to SDR. 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 is an opinion about how to do that.
For a deliverable where the SDR version matters — most broadcast, most client work — review the tone-mapped result rather than shipping it unseen. An automatic map protects you from an obviously wrong file. It does not replace a colourist's trim pass, and it should not be presented internally as though it does.
Proxies declare their colour#
Every colour-managed proxy is written with a sibling file describing the colour space it was produced in — a small JSON document next to the media.
This solves a real problem. A proxy separated from the context that produced it is a file whose colour interpretation you have to guess. Guessing is how a cut gets graded against something that does not match what the finish will come from. Carrying the declaration with the file makes the answer travel 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, so the transform that was intended is the transform that was applied — on every frame, on every worker, without depending on an operator remembering to do it.
The tooling this relies on ships with the master. Confirm it resolves before committing a show to a colour-managed pipeline:
$ master probe-v-depsIn practice#
- Test one clip through the full path before a shoot. Colour problems are systematic — if the first file is wrong, all of them are, and finding that out after a week of ingest is expensive.
- Prefer sources that carry their colour metadata. When metadata is absent it has to 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 information. Assembly rejecting a mismatch means the check worked. Find out why the signature differed rather than looking for a way around it.