# How to Check a Video's Colour Space and HDR Metadata on Mac | Stoic

[ All posts](https://www.stoicplayer.com/blog)

## Key takeaways

* Four tags matter: colour primaries, transfer function, matrix coefficients and range.
* One ffprobe command prints all four. Untagged files print unknown, and players then have to guess.
* HDR10 adds mastering display and content light level data. Dolby Vision and HDR10+ add more.
* If the tags look right and the picture still does not, the problem is in the player or the display.

When a video looks wrong, the first useful question is what the file claims to be. The answer lives in a handful of numbers stored with the stream. Players trust them, and when they are missing players guess. Reading them takes a minute, and it turns "something is off" into a specific, fixable fact.

## The four tags

**Colour primaries** say which red, green and blue the picture was made with. HD video usually uses BT.709\. HDR and wide-gamut video uses BT.2020\. Use the wrong set and colours look muted or over-saturated.

**Transfer characteristics** describe how brightness values map to light. BT.709 is the ordinary SDR curve. PQ (SMPTE ST 2084, shown as `smpte2084`) and HLG (`arib-std-b67`) are the two HDR curves. Mix these up and you get the grey, washed-out look, or a picture that is far too dark.

**Matrix coefficients** say how the stored luma and chroma convert back to red, green and blue. HDR video uses `bt2020nc`. Dolby Vision Profile 5 is the odd one, using a different encoding (IPTPQc2) that ordinary players do not understand.

**Range** says whether black is stored at 0 or at 16 (`tv` or limited range, versus `pc` or full range). A range mismatch is the classic reason for crushed blacks or a hazy, lifted picture.

## Read them with ffprobe

ffprobe comes with FFmpeg. If you use Homebrew, `brew install ffmpeg` adds it. Then:

```
ffprobe -v error -select_streams v:0 \
  -show_entries stream=codec_name,pix_fmt,color_range,color_space,color_transfer,color_primaries \
  -of default=noprint_wrappers=1 file.mkv
```

On an HDR10 test clip we generated, the output was:

```
codec_name=hevc
pix_fmt=yuv420p10le
color_range=tv
color_space=bt2020nc
color_transfer=smpte2084
color_primaries=bt2020
```

That reads as 10-bit HEVC, limited range, BT.2020 matrix and primaries, PQ transfer: standard HDR10\. On an ordinary H.264 file with no tags, the same command printed `unknown` for all four. That is not an error. It means the encoder did not write them, and every player is left to assume. Many assume BT.709, which is right for HD and wrong for anything HDR.

## The HDR extras

HDR10 adds two blocks of data. Mastering display metadata describes the screen the film was graded on: its primaries, white point and minimum and maximum luminance. Content light level gives MaxCLL and MaxFALL, the brightest pixel and the brightest average frame. Ask for them with:

```
ffprobe -v error -select_streams v:0 -show_frames -read_intervals "%+#1" \
  -show_entries frame=side_data_list file.mkv
```

The test clip printed a mastering display block, with a maximum luminance of 10,000,000 over 10,000 (1,000 nits), and a content light level entry. HDR10+ files add an entry named `HDR Dynamic Metadata SMPTE2094-40 (HDR10+)` (see [HDR10+ on Mac](https://www.stoicplayer.com/blog/hdr10-plus-on-mac)). Dolby Vision files carry a configuration record with a profile number, and the profile is what decides whether a player can show them correctly. Two guides cover that: [Profile 5 vs 8.1](https://www.stoicplayer.com/blog/dolby-vision-profile-5-vs-8-1-on-mac) and [Dolby Vision MKV on Mac](https://www.stoicplayer.com/blog/dolby-vision-mkv-on-mac).

## Other ways to look

* **MediaInfo** prints the same data in a friendlier layout, including a line for the HDR format.
* **Our browser tools** read a file's metadata without installing anything. Find them on the [tools page](https://www.stoicplayer.com/tools).
* **The player itself.** What matters in the end is what your player decided, not only what the file says.

## What Stoic shows

Press Command I in Stoic to open the media inspector. It shows the format, the colour decision, headroom and scene peak, and it marks any value it had to infer because the file did not tag it, so you can tell a file that says BT.2020 from one Stoic assumed was. When a file's tags are missing, Stoic infers them cautiously instead of silently trusting BT.709.

## Reading the result

If PQ and BT.2020 show up and the picture looks grey, look at the display and player, not the file: [why HDR looks washed out on Mac](https://www.stoicplayer.com/blog/hdr-looks-washed-out-on-mac). If the tags are unknown on a file that should be HDR, the file needs retagging or a player that infers sensibly. If everything is as expected and the picture is right, you can stop worrying about it.

## See what the player decided

Stoic's inspector shows colour, headroom and inferred tags for the file you are playing. Native for Apple silicon Macs on macOS 26 or later, with one purchase for up to three Macs.

[Buy now](https://checkout.dodopayments.com/buy/pdt%5F0NoFF3ULkfeucBnMycGW2?quantity=1&redirect%5Furl=https%3A%2F%2Fwww.stoicplayer.com%2Factivate&paymentCurrency=USD&showCurrencySelector=true)

---

> Read a video's colour primaries, transfer, matrix and range with ffprobe, with real output, and learn what each value says about how it should look.

Source: https://www.stoicplayer.com/blog/check-video-colour-space-on-mac