DEV Community

Lank_M
Lank_M

Posted on

Your compressor dropped color_range, so now the player decides

The clip was 6.4 seconds of 1080p ocean waves, 17.4 MB, tagged as limited range (tv) with BT.709 matrix, primaries and transfer. In this test it went through a free online compressor without logging in, and 9.25 MB came back in about 15 seconds. Same resolution and frame rate, whole-clip SSIM 0.986, in the same band as an ffmpeg CRF 23 encode. By the usual checks it was fine. Then ffprobe ran on it, and color_range, color_space, color_primaries and color_transfer all came back unknown. I won't name the service, because the point is how a reasonable compression step quietly turned four answers into four questions.

The pixels were fine and only the labels were gone

A botched range conversion was the first suspect. After aligning frames, the mean luma of output and source came to 123.73 and 123.71, so nothing was stretched, which points to the data still being limited range. What disappeared was the sentence that says so. That moves the call. The compressor had the answer, since it decoded a source that carried it. Now every player, browser and thumbnailer that opens the file has to guess, and nothing in the file tells it how. This is one clip, one Apple-silicon Mac, one run: an observation about one file, not a survey.

A wrong guess has two directions

To price a wrong guess, the test encoded a grey pattern (0–255 ramp plus nine patches) as 3-second H.264 in four combinations of actual and declared range. Decoded to RGB, the two honest cases read back exactly: 0, 8, 16, 64, 128, 192, 235, 247, 255. Limited-range data declared as full came back as 16, 23, 30, 71, 126, 181, 218, 228, 235. Black became 16 and white became 235, so the usable contrast was 219/255, about 86%, the washed-out grey people complain about. The opposite mistake looks different. Full-range data declared as limited came back 0, 0, 0, 56, 130, 205, 255, 255, 255: 17 shadow levels collapsed into black and 21 highlights clipped to white. That one reads as crushed shadows and blown highlights rather than grey.

An unknown file of limited-range data only fails one way, if a reader guesses full. The unknown file was not run through a set of players, so who guesses what is open. My unverified understanding is that ffmpeg's scaler treats unspecified YUV as limited, so the SSIM comparison was probably decoded correctly. The matrix is the other open gap. The fallback I remember from codec SDK work is picking by frame height, BT.709 for HD and BT.601 below. Whether current browsers still do that, nothing here tests.

One MP4 carries the tag in two places

There's a second trap. An H.264 MP4 can declare range in the bitstream's VUI and again in the container's colr box, and the two don't have to agree. Rewrite the bitstream flag with h264_metadata and the container keeps its old value. ffprobe -show_streams then reports the container value while -show_frames reports the bitstream one. Two mismatched files were built to see which one decoders believe. Both ffmpeg decoding and a <video> element drawn to a canvas in desktop Chromium followed the bitstream and ignored the container, and their readings agreed within 1. QuickTime, VLC, Safari and phone galleries were not tested, so "players disagree" is neither proven nor disproven. A contract that only asserts the container field would have passed both broken files.

Colour metadata is part of the output contract

What I'd write down for any compression step is short. The output declares range, matrix, primaries and transfer explicitly, never unknown. Bitstream and container agree. If the step converts range, the label changes with the pixels. The check sits next to resolution and frame rate and fails when a field goes missing. When the source carries no tags, the step still chooses and records it, since it has the decoded pixels in hand.

For comparison I used ImgIng https://imging.ai/ in the same desktop Chromium on the same Mac: the full-range grey pattern went in on its "visually near-lossless" setting. Video compression isn't a module I worked on, so this is an outside reading of its output. Both outputs came back converted to limited range and tagged tv with BT.709 for all three colour fields. Decoded, black and white held up: 0 and 255 for H.265, 2 and 254 for H.264, with no grey lift and no clipping. Full range isn't preserved, 256 levels become at most 220, but the file says what it is.

I haven't settled whether a pipeline should reject unknown input outright or default it and log a warning. Rejecting is cleaner, but user uploads are messy. Either way, diffing those four fields between input and output of every step that touches video is cheap. For the mislabelled case, a stream copy with h264_metadata setting the full-range flag to 0, plus -color_range tv on the container, brought the readings back to 0, 128 and 255 without re-encoding. Restoring a fully unknown file that way was not tested.

The wave clip is from Wikimedia Commons, CC0, by Mostafameraji, re-encoded for this test. The grey pattern is my own.

Top comments (0)