Apple ProRes Decoder Reference Source Code
==========================================

This directory contains source code to accompany SMPTE RDD 36:2015, "Apple
ProRes Bitstream Syntax and Decoding Process."  The code implements a reference
version of a ProRes decoder.


Compilation
-----------

Check the definitions of CXX and CXXFLAGS in the Makefile and modify as
necessary.  Run 'make' to build, which upon successful compilation and linkage
will produce an executable named "ProResDecoder."  Running 'make clean' will
remove all build products, while running 'make cleanobj' will remove just the
object modules produced by compilation and leave the executable intact.


Usage
-----

Run ProResDecoder without any arguments to see a full description of usage:

Usage: ProResDecoder [-n <count>] [-rgb <range>] [-b <bit depth>] [-e <endianness>] <bitstream file> <output file>

Options:
    -n <count>          Maximum number of frames to decode.
    -rgb <range>        Produce RGB pixel color component samples.  f for
                        full-range RGB samples (black and peak signal levels
                        corresponding respectively to 0 and maximum sample
                        quantization levels, e.g. 0 and 255 for 8-bit samples),
                        v for video-range RGB samples (black and nominal peak
                        signal levels corresponding to sample quantization
                        levels consistent with ITU-R BT.601/BT.709/BT.2020,
                        e.g. 16 and 235 respectively for 8-bit samples).
    -b <bit depth>      Bit depth of pixel component samples; 8 or 16.
                        (Default is 16.)
    -e <endianness>     Endianness of 16-bit pixel component samples.  l for
                        little endian, b for big endian, or n for native endian.
                        (Default is little endian; ignored for 8-bit samples.)

The bitstream file can be either a ProRes "elementary stream"--a succession of
one or more ProRes compressed frame bitstreams--or a ProRes QuickTime movie
file (note, however, that the code uses a very simple QuickTime parser that is
not guaranteed to work on all such movie files).  The output file will contain
decoded pixel data in raster scan order with component order CbY'CrY', AY'CbCr,
or ARGB for respectively 4:2:2 Y'CbCr, 4:4:4:4 AY'CbCr, or ARGB output; if
multiple frames are decoded, they appear in the output file in immediate
succession.


Examples
--------

Decode a ProRes QuickTime source file "ProRes422HQ_1920x1080i50_10sec.mov" to
16-bit little endian 4:2:2 CbY'CrY' output:

    ./ProResDecoder ProRes422HQ_1920x1080i50_10sec.mov ProRes422HQ_1920x1080i50_DecodedFrames.CbYCrY16LE

Decode the first 10 frames (at most) of a ProRes QuickTime source file
"ProRes422_1280x720p5994_10sec.mov" to 8-bit 4:2:2 CbY'CrY' output:

    ./ProResDecoder -n 10 -b 8 ProRes422_1280x720p5994_10sec.mov ProRes422_1280x720p5994_DecodedFrames0-9.CbYCrY8

Decode a ProRes QuickTime source file "ProRes4444withAlpha_1920x1080p25_10sec.mov"
to 16-bit big endian full-range ARGB output:

    ./ProResDecoder -rgb f -e b ProRes4444withAlpha_1920x1080p25_10sec.mov ProRes4444withAlpha_1920x1080p25_DecodedFrames.ARGB16BE


Licensing
---------

Please see the file "LICENSE.txt."


Feedback and Bug Reporting
--------------------------
Please email ProRes@apple.com.
