DEV Community

AsyncMonk
AsyncMonk

Posted on

Fix a washed-out MP4 without re-encoding: rewrite the range tag in both places

Picture a ticket that says "the clip I uploaded looks foggy, the black parts are grey". When you run a product alone, you want that ticket closed in ten minutes, not a weekend spent on the transcode step. If the file is H.264 and only the range tag is wrong, re-encoding is unnecessary. A single ffmpeg command with -c copy rewrites the tag, leaves every compressed frame alone, and the blacks come back. The catch is that an MP4 stores that tag in two places, and the shortest version of the fix only touches one of them.

Grey blacks mean limited pixels tagged as full

The numbers below come from a self-made test pattern, not a customer clip: a 0–255 gray ramp on top and nine flat patches at 0, 8, 16, 64, 128, 192, 235, 247 and 255, encoded as 3 seconds of 8-bit H.264 (CRF 10, BT.709) on an Apple silicon Mac with ffmpeg, one run per variant. When pixels that only use Y 16–235 are tagged pc (full range), the decoder skips the stretch, and the nine patches come out as 16 / 23 / 30 / 71 / 126 / 181 / 218 / 228 / 235. Black never gets below 16, white stops at 235, and every patch in between is pulled toward the middle. That is the foggy look a user would describe. The opposite mistake looks nothing like it: full-range pixels tagged tv decode with 0–16 (17 levels) all flattened to 0 and 235–255 (21 levels) all pushed to 255. Nobody calls that washed out, which helps when all you have is a user's sentence.

The direction matters before you touch the file, because the fix in the next section turns a correct full-range file into exactly that crushed version. So the first check is the real Y range, not the tag. On the washed-out test file, ffmpeg's signalstats filter reported YMIN 16 and YMAX 235 while ffprobe said pc, so the tag is wrong and the pixels are fine.

One command rewrites both tags

The command is ffmpeg -i in.mp4 -c copy -bsf:v h264_metadata=video_full_range_flag=0 -color_range tv out.mp4. The h264_metadata bitstream filter flips the video_full_range_flag in the VUI, the flag the H.264 stream itself carries. The -color_range tv option changes what the MP4 muxer writes into the colr box, the container-level copy. -c copy means no decode and no encode, so there is no generation loss. After the rewrite, ffprobe reported pix_fmt=yuv420p and color_range=tv, and the patches decoded back to 0 for black, 128 for mid gray and 255 for white.

The filter alone leaves the container saying pc

The tempting shortcut is the bitstream filter alone, since decoders read that flag. In this test they did: a file with a tv bitstream flag and a pc container tag decoded exactly like the fully consistent tv file, both through ffmpeg and through a <video> element in desktop Chromium drawn to a canvas, and the two paths differed by at most 1 on any patch. The mirror case held too: a pc bitstream flag under a tv container tag decoded just as grey as the fully mis-tagged file, so on these two paths a container-only fix would not help.

So why bother with both? Because ffprobe -show_streams reports the container value, and -show_frames reports the bitstream value. After a filter-only fix, the first one still prints pc. If your upload validator checks with -show_streams, the fixed file looks broken and may get "fixed" back. The second reason is a guess, not a measurement: QuickTime, VLC, Safari, phone galleries and chat apps were not part of this test, and I don't know whether any of them prefers colr over the VUI. Writing the same value in both places makes that question irrelevant.

Fix the step that wrote the tag

Patching the file closes the ticket. The real bug is the step that produced limited pixels with a full-range tag, and the cheap way to catch it is a check in the upload path: read the frame-level tag with -show_frames, read YMIN and YMAX with signalstats, and flag any file tagged pc whose luma never leaves 16–235. I would not auto-fix on that rule, because a dim, low-contrast clip that really is full range can sit inside 16–235 too, so a flagged file still deserves a human look. HEVC was outside this test; h264_metadata only covers H.264.

To see what a compressor ought to hand back, I use ImgIng https://imging.ai/ , a browser-based video compressor. In this test it got a full-range copy of the same gray pattern on its "visually near-lossless" preset in a desktop browser. One caveat: on a 3-second still pattern the result came out larger than the input, so ImgIng did not adopt it automatically; the readings below come from the candidate saved by hand and say something about tags, not final quality. It did not keep full range. The output came back as limited range, correctly tagged tv, and decoded to 0 / 255 for H.265 and 2 / 254 for H.264, with no grey floor and no clipping. One self-made sample, one run, but it gave me a target for my own pipeline: convert when you have to, tag what you actually wrote, and check the tag against the pixels before a user does it for you.

Top comments (0)