QuickTime File Format and ProRes Video Parameter Editing
Part of the HDR-TV series. Last updated April 2017.
Several post-production tools and utilities are now aware of the colour and transfer function parameters specified in ITU-R BT.2100-0. However, some tools are unable to correctly signal the correct parameters, and may result in a file with the incorrect video parameters. Subsequent tools or displays may then look at these video parameters and render the image incorrectly, for instance, video that this signalled as ITU-R BT.709 colour primaries and in fact is ITU-R BT.2020 colour primary and then displayed on a monitor will look desaturated when the display is interpreting the signalling contained within the file. Incorrect signalling may also result in unnecessary and incorrect transcoding between colour spaces and transfer functions.
QuickTime File Format (qtff)
The QuickTime File Format (qtff) is a container file supporting a wide range of video, audio and other data formats. The format itself is object-orientated, consisting of a collection of objects that can be parsed and expanded.
The basic data unit is known as an Atom. The Atom that defines the relevant information required to define the colour primaries, colour matrix and transfer function are found in the "colr" data Atom, which is located inside the Video Media Atom. The structure of the "colr" Atom is as follows:
|Type = "colr"||4|
|Colour Parameter type = "nclc"||4|
|Primary index = 1||2|
|Transfer Function index = 1||2|
|Colour Matrix index = 1||2|
SMPTE RDD 36:2015 - Apple ProRes Bitstream Syntax and Decoding Process
SMPTE RDD 36 describes the syntax and decoding process for the Apple ProRes video compression scheme. It is an intra-frame codec, specifically designed for high-quality workflows and supports a variety of video formats, and is common usage.
In addition to the colour information carried within the Color Atom, information regarding the transfer function, colour matrix and primaries are also stored within the frame header information of the ProRes elementary stream, alongside other parameters, such as frame rate, spatial resolution and chroma format. This header is repeated throughout the bitstream. Full details of the header layout can be found in the SMPTE specification.
To avoid any ambiguity in any workflows, it is imperative that the the information in the header for the ProRes stream match that of the qtff colr Atom.
The colour primaries can be selected from the list:
|10||SMPTE ST 428-1|
The transfer function can be selected from the list:
|4||Gamma 2.2 curve|
|5||Gamma 2.8 curve|
|12||ITU-R BT.1361 Extended Colour Gamut|
|14||ITU-R BT.2020 10 bit|
|15||ITU-R BT.2020 12 bit|
|16||SMPTE ST 2084 (PQ)|
|17||SMPTE ST 428-1|
|18||ARIB STD-B67 (HLG)|
The colour matrix can be selected from the list:
|9||BT2020 Non-constant Luminance|
|10||BT2020 Constant Luminance|
This repository contains a number of tools that will aid in analysing a video file to obtain the video characteristics, and subsequently allow modification of the qttv container and ProRes bitstream to alter the characteristics
ffprobe is required to find the extract the location of the frame headers from the ProRes bitstream. Downloads can be found here for your OS. Static builds for Linux are available if building from source is not an option. Static builds for Windows and OSX are available via third party websites. Once obtained, ffprobe must be put into the
MediaInfo is a convenient unified display of the most relevant technical and tag data for video and audio files. The tool is useful checking the outputs to the tools within thsi repository are reporting accurate information.
Standard developer tools (gcc/g++, make, bash) will be required to build and run the code.
Building the code
A makefile has been provided to build the code.
cd src make
The repository contains 3 main programs:
movdump- This tool creates a text dump of the header data at the qtff (mov) level.
rdd36dump- This tool creates a text dump of the header data at the ProRes level.
rdd36mod- This tool modifies the ProRes data to adjust the transfer function, colour primaries and matrix.
Running the code
The programs above can be run individually as follows:
movdump ipFile > movdump.txt
Where the output movdump.txt will look something like this:
mdat: s= 5884636816 (0x000000015ec06e90), o= 0 (0x00000000) ...skipped 5884636800 bytes free: s= 24332 (0x00005f0c), o= 5884636816 (0x000000015ec06e90) ...skipped 24324 bytes wide: s= 8 (0x00000008), o= 5884661148 (0x000000015ec0cd9c) mdat: s= 12 (0x0000000c), o= 5884661156 (0x000000015ec0cda4) ...skipped 4 bytes moov: s= 24938 (0x0000616a), o= 5884661168 (0x000000015ec0cdb0) mvhd: s= 108 (0x0000006c), o= 5884661176 (0x000000015ec0cdb8) version: 0 flags: 0x000000 ... ...
rdd36mod, the location of the headers must first be located with
ffprobe -loglevel panic -show_packets -select_streams v:0 ipFile.mov | grep pos > header_offsets.txt
The header_offsets.txt can then be provided to
rdd36dump --offsets header_offsets.txt ipFile.mov > rdd36dump.txt
Where the output rdd36dump.txt will look something like this:
frame: num=0, pos=96256 frame_size: 221808 frame_identifier: 0x69637066 (icpf) frame_header: frame_header_size: 148 reserved: 0x00 bitstream_version: 0 encoder_identifier: 0x61626d30 (abm0) horizontal_size: 3840 vertical_size: 2160 chroma_format: 2 (4:2:2) ... ...
Modifying the video characteristics
Using the tools above the transfer function, colour primaries and matrix can be edited using the binary offset information in the dump files. Alternatively, a script has been prepared that does it all for you. The help from the bash script describes its usage:
qtff-parameter-editor.sh This script can be used to edit the primaries, transfer functions and matrix fields in a .mov file, it can be extended for further editting if required." Usage: qtff-parameter-editor.sh [--help] [-h] [-p priValue] [-t tfValue] [-m matValue] InputFile OutputFile or qtff-parameter-editor.sh InputFile Where: -h, --help : Displays this help page -p --primaries priValue: Where priValue is the required primaries value number -t --tf tfValue: Where tfValue is the required transfer function value number -m --matrix matValue: Where matValue is the required matrix function value number InputFile: Source mov file OutputFile: Output mov file (Can be the same as the Input file) If only an Input file is provided (as in the second example, the script will return the information for the input file Example 1: ./qtff-parameter-editor.sh input.mov Return video parameter information for input.mov Example 2: ./qtff-parameter-editor.sh -p 1 -t 1 -m 1 input.mov output.mov Will create a copy with input.mov and modify the video parameters to bt709 primaries, transfer function and matrix. Example 3: ./qtff-parameter-editor.sh --primaries 9 --tf 18 --matrix 9 input.mov input.mov Will modify the video parameters in situ to bt2020 primaries, HLG transfer function and bt2020 non constant luminance matrix
If a colr Atom is not present in the video file, the process will not attempt to insert one, and will quit the processing.
Please visit our project page for more information about High Dynamic Range (HDR) and Hybrid Log-Gamma (HLG).
This software was written by Philip de Nier (philip.denier at bbc.co.uk) and Manish Pindoria.
Contact and Legal Information
Copyright 2009-2017 British Broadcasting Corporation
The qtff-parameter-editor is free software; you can redistribute it and/or modify it under the terms of license agreement.
The qtff-parameter-editor is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.