Skip to main content

Saving The Day (kinda) with NCLC Tags

· 3 min read
Cameron Target
Cameron Target
Author

This post is about a common gotcha when transcoding QuickTime containers for review, and how I fixed it this one time.

Where people trip up​

Here's a scenario that will be familiar to anyone who's ever used QuickTime Player for editorial or client review: you render a DNxHD file. Same source, same codec, same colorspace. You open it up and it looks noticeably different; maybe lifted, maybe with a gamma shift, maybe slightly desaturated. You bring it into Nuke or something similar, with no color transforms applied, read as raw data, and it's pixel-for-pixel what you were looking at before. So what's going on?

The answer, more often than not, lives in the QuickTime container's color metadata, specifically the NCLC atom.

Wth is an NCLC?​

NCLC stands for Non-Constant Luminance Coding. In the context of QuickTime, it's a set of three tags embedded in the container (not in the codec stream itself) that tell the player how to interpret the color of the video. The three parameters define:

  1. Color Primaries - what color space the content lives in (e.g. BT.709, BT.2020)
  2. Transfer Function - the gamma curve used to encode the image (e.g. BT.709, sRGB, PQ)
  3. Matrix Coefficients - how to convert between YCbCr and RGB

When QuickTime Player opens your file, it reads these tags to decide how to display the image. If one of them is set to "Unspecified," the player has to guess (and it might guess wrong.)

My Recent Case​

The team I'm working with had a DNxHD QuickTime file where the color was super dark. I took the file and ran it through Nuke as a straight pass through with their encoder then brought it back in to see if it was identical. Here's what their metadata looked like side by side:

KeyOriginalNuke Output
quicktime/nclc_transfer_functionUnspecifiedITU-R BT.709

Both files looked identical in a Nuke viewer with no transforms applied or read in. But the one I output looked fine in Quicktime. When I looked at the metadata, the container-level nclc_transfer_function on File A was "Unspecified." That missing tag was what caused QuickTime Player to misinterpret the gamma, producing a visibly different image.

The Fix​

The approach depends on your tools, but the principle is the same: explicitly set your NCLC tags on the output QuickTime however you can. In my case these settings are default when you kick things out from Nuke.

If you're using ffmpeg and doing a stream copy (no re-encode), you can set the tags manually:

ffmpeg -i input.mxf -c copy \
  -color_primaries bt709 \
  -color_trc bt709 \
  -colorspace bt709 \
  output.mov

If the file already exists and you just want to re-tag it without re-encoding, ffmpeg can do that too — the flags above with -c copy will rewrite the container metadata while leaving the stream untouched.

Going Forward​

The frustrating thing about NCLC issues is that nothing is actually wrong with your image data. The pixels are correct. The problem is that the container is giving the player bad instructions on how to display them. It's the kind of thing that's hard to detect.

If you're transcoding media for review, make it a habit to verify your NCLC tags on the output if you know your client will be reviewing in QuickTime Player. A quick ffprobe or mediainfo check before you send anything downstream can save you a lot of "why does this look different?" conversations.