How to add colour space metadata to an HEVC/H265 file with ffmpeg
The high quality to space ratio of HEVC/H265 makes it a good candidate to create review files with high dynamic range (HDR). For a platform like FrameIO, or video players to recognize the file with the right colour space and EOTF, you’ll need to add the corresponding metadata tags to the file.
Most of the time the software you’ll use to encode those H265 files will have an option to add these tags or metadata. This guide from FrameIO has step-by-step instructions to export a file with the right tags from a lot of NLE, Colour grading or VFX software. But sometimes you either don’t have this option available to you on the software you’re using, or you forgot to add these tags and now you just want to add them afterwards without having to re-encode the file.
Here is where ffmpeg comes to help you. With the right command, you can change the metadata, and since it doesn’t re-encode the file, it’s almost instant. The only problem : it’s not well documented.
Checking the metadata
To make troubleshooting easier, it’s good to start with a good inspector tool. Mediainfo has us covered here. When inspecting your file, you’ll see the 3 characteristics to look for :
- Color primaries : This will give you the gamut of your file (BT.709, P3, BT.2020, etc).
- Transfer characteristics : This gives you the EOTF (PQ, HLG, etc).
- Matrix coefficients : This is a bit more complicated, it gives you some values to convert between RGB space and YUV or XYZ.
You may not see all of them, because some encoders don’t set them at all. When the values are set to unknown, they are skipped by mediainfo.
Ffmpeg syntax
The syntax to change the metadata of an H265 file is as follows :
ffmpeg -i $INPUT \
-c copy \
-bsf:v hevc_metadata=colour_primaries=$X:transfer_characteristics=$Y:matrix_coefficients=$Z \
$OUTPUT
You will need to replace the $INPUT and $OUTPUT with the path to your source
file and destination file respectively.
And for the metadata, you’ll need to replace the $X, $Y and $Z with
numbers that are listed in the HEVC
specification pdf (in the
tables E.3, E.4 and E.5).
But here are the values that you’ll most likely encounter :
| Output colour space | Output EOTF | $X | $Y | $Z |
|---|---|---|---|---|
| Rec709 | Gamma 2.4 | 1 | 1 | 1 |
| P3D65 | PQ (ST.2084) | 12 | 16 | 1 |
| Rec2020 | PQ (ST.2084) | 9 | 16 | 9 |
| Rec2020 | HLG | 9 | 18 | 9 |
Once your metadata change has ran, don’t forget to check your output file in mediainfo to make sure you have the right tag.
Going further
There is also a bitstream filter in ffmpeg to change metadata in Prores and H264 files. Feel free to have a look in the ffmpeg documentation to see how this works.