xyz2yuv tool

Decode DCI XYZ' and apply conversions to your desired output colorspace. Supports Rec. 709, Rec. 2020, and others; along with HDR10 / HLG support, with transfer functions and gamma values.

Supports AVX-512 and AVX2 targets, and a generic implementation in C and Go as well.

See go-dcp for a tool that can handle sample trailer DCPs.

TODO

• Proper tests for specific functions and for full workflow / hashes etc.

Dependencies

• Go >= 1.22
• CGO enabled and working
• libopenjp2-dev OpenJPEG
  • Necessary due to FFMPEG's JPEG2000 now default decoder being broken and producing corrupted output.
• libavformat-dev
• libavcodec-dev
• libavutil-dev

Build

# initialize conv/simd_utils
git submodules update --init

# build binaries with specific Go toolchain path
GOROOT=~/go/go1.22.4 ./build.sh

After building multiple tools will appear under bin/. These binaries are compiled with

• xyz2yuv: Defaults to use the highest native features available. This includes 512-bit pipeline and AVX-512 usage if supported.
• xyz2yuv_avx2: Disables AVX-512 and 512-bit pipelines. Prefer using the above on most systems as it will pick native features.

Usage

The input file must include a video stream with codec JPEG2000 and with pixel format XYZ12. Other video inputs are unsupported.

Any other tracks (audio/subtitles) will be ignored.

Most containers that ffmpeg can support are valid, usually this will be MXF or Matroska.

You need to select the color space that matches what you need. Sometimes custom gamma values are applied on mastering depending on viewing targets. Custom color spaces can be defined via JSON files. See colorspace/config for examples. Companding or specific transfer functions require -use-go-pipeline. Pure gamma and PQ have SIMD / C versions.

Performance can be increased by using -float to reduce the precision of the conversion pipeline. This will cause precision issues.

Low-resolution JPEG2000 decoding can be implemented via -lowres parameter. Value of zero equals original resolution.

Default output is in the form of YUVMPEG2 16-bit 4:4:4 with full color range. Use -out-format mkv to output Matroska with FFV1 lossless video, with tagged color and HDR metadata. Depending on JSON file YCbCr output can be changed to YcCbcCrc or ICtCp Bit depth is configurable to 10/12/14/16 bit, and you can request limited range output.

HDR luminance parameters can be setup via custom colorspace values. Default is 100 cd/m² for rec2020_hdr10 in sdr, and 48 cd/m² for dci-p3_hdr10. Other values can be set in the colorspace JSON file. MaxCLL and MaxFALL are not set by default. You can override these values in the colorspace JSON file.

It can output to a file or stdout for immediate consumption.

./bin/xyz2yuv -lowres=0 \
-in /path/to/input.mkv \
-colorspace "rec709_pure22" \
-out-format matroska \
-out /path/to/output.mkv

Usage of xyz2yuv:
  -colorspace string
        Path to JSON colorspace and parameters to convert into. Default templates: rec709, rec709_pure22, rec709_pure24, rec2020, rec2020_pure22, rec2020_pure24, rec2020_hdr10, rec2020_hlg, srgb, dci-p3 (default "rec709_pure22")
  -decoder-threads uint
        Threads for JPEG2000 decoding. Defaults to number of logical CPU
  -depth int
        Output bit depth. Must be one of 10, 12, 14, 16 (default 16)
  -end uint
        End frame number exclusive (default 18446744073709551615)
  -float
        Use float pipeline instead of double, although less precise. Very fast.
  -hash
        Hash with SHA256 each output frame for accuracy comparisons
  -in string
        Input file
  -limited
        Output limited/tv YUV range instead of full/pc range
  -lowres uint
        Feed lowres parameter. Default is full resolution
  -out string
        Output file. Use - for stdout (default "-")
  -pipeline-threads uint
        Threads for colorspace conversion pipeline. Defaults to number of logical CPU
  -precision-rgb2yuv int
        RGB -> YUV conversion matrix precision. 0 = maximum
  -precision-xyz2rgb int
        XYZ -> RGB conversion matrix precision. 0 = maximum
  -progress
        Output progress and speed information
  -hdr-light-level
        Output progress and speed information
  -start uint
        Start frame number inclusive
  -use-go-pipeline
        Use Go pipeline, although slower. Does not support float mode.

Scripts

MPV playback

For convenience mpv playback scripts are included under scripts/.

The first audio track from the input file will also be included in the playback.

Playback will be loosely seekable as it decodes from pipe. 4 GiB of cache is default and recommended to keep a few seconds of buffer.

Rec. 709 output

./scripts/playback-rec709_22-mpv.sh /path/to/input.mkv

Rec. 2020 output

./scripts/playback-rec2020_24-mpv.sh /path/to/input.mkv

Rec. 2020 HDR10 100 cd/m² output

./scripts/playback-rec2020_hdr10-mpv.sh /path/to/input.mkv

ffmpeg FFV1 lossless encode