HDR Settings

This topic contains details for encoding settings related to HDR video outputs.

Overview

For details on the HDR formats that Zencoder supports and recommendations on the HDR format parameters, see the HDR Video Guide.

preserve_hdr_metadata

master_display:Boolean

API Versions: V2

Parent: outputs

Default: false

Compatible Job Types: vod

Description:

When set to true, this parameter instructs Zencoder to import (most or all) HDR-related metadata from input file and pass them to the output.

For example, transcoding of HEVC-encoded video streams in HDR10, PQ10, or HLG10 formats can be accomplished by using the following job request: 

{
  "input": "s3://mybucket/hdr_master.mp4",
  "outputs": [
    {
     "video_codec": "hevc",
     "video_codec_profile": "main10",
     "video_bit_depth": 10,
     "preserve_hdr_metadata": true
    }
  ]
}

This parameter may also be used in combination with other parameters, specifying HDR-related metadata directly. For example, below JSON job request shows how preserve_hdr_metadata parameter may also be used for carrying over master display and content light level metadata from HEVC-encoded DolbyVision 8.1 streams, while DolbyVision dynamic metadata (RPU file) is communicated separately by using the dolby_vision_rpu_url parameter:

{
  "input": "s3://mybucket/dv81_master.mp4",
  "outputs": [
    {
     "video_codec": "hevc",
     "video_codec_profile": "main10",
     "video_bit_depth": 10,
     "video_color_format": "dv8.1",
     "preserve_hdr_metadata": true,
     "dolby_vision_rpu_url": "s3://mubucket/dv81_master_rpu.rpu"
    }
  ]
}

See also:

video_color_format

video_color_format:String

API Versions: V2

Parent: outputs

Valid Values:

video_color_format Color Primaries Transfer Characteristics Matrix Coefficients color_range
sdr bt709 (1) bt709 (1) bt709 (1) Limited (default)
hlg10 bt2020 (9) arib-std-b67 (18) bt2020nc (9) Limited (default)
wcg / bt2020 bt2020 (9) bt2020 (14) bt2020nc (9) Limited
pq10 / hdr10 / dv8.1 bt2020 (9) smpte2084 (16) bt2020nc (9) Limited
dv5 unknown (2) unknown (2) unknown (2) Full

Description:

This parameter converts output video colors to the given video_color_format.

  • To convert colors from one format to another, you need:
    • Valid metadata to be present in the input media.
    • color_conversion feature flag enabled for the account.
  • For HDR formats (hlg10, pq10, hdr10, dv8.1 and dv5). It is required to use "video_codec" : "hevc" and "video_bit_depth": 10
  • See Supported HDR Video Formats for more information about HDR Formats.

Example:

  • Covert to sdr: 
      {
  "video_codec": "h264",
  "video_color_format": "sdr"
}
  • Covert to pq10: 
          {
        "video_codec": "hevc",
        "video_bit_depth": 10,
        "video_color_format": "pq10"
      }

master_display

master_display:Object

API Versions: V2

Parents: outputs, dynamic_profile_options

Default: none

Compatible Job Types: vod

Description:

Structure describing the color volume (the color primaries, white point, and luminance range) of the display that was used in mastering of video content. Specific values used in this structure are defined by SMPTE ST 2086 standard.

Master display metadata is mandatory and must be carried out to the outputs when encoding of videos in HDR-10 and DolbyVision 8.1 formats.

The example below shows how the master display metadata can be specified:

{
  "input": "s3://mybucket/j2k_master.mfx",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_codec_profile": "main10",
      "video_bit_depth": 10,
      "video_color_format": "hdr10",
      "master_display": {
        "red": {"x": 0.708, "y": 0.292},
        "green": {"x": 0.17, "y": 0.797},
        "blue": {"x": 0.131, "y": 0.046},
        "white_point": {"x": 0.31273,"y": 0.329},
        "luminance": {"max": 1000,"min": 0.0001}
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

See also:

max_content_light_level

max_content_light_level:Number

API Versions: V2

Parents: outputs, dynamic_profile_options

Default: none

Valid Values: 0-10000

Compatible Job Types: vod

Example: 1000

Description:

Describes maximum pixel (and red, green, and blue channel)-wise light level across video sequence. Expressed in candellas per meter squared. This value can be set 0, implying that such bound is unknown or not imposed. This parameter, also known as MaxCLL is defined by the CAE 861.3 standard.

The example below shows how max_content_light_level, and max_frame_average_light_level metadata can be specified:

{
  "input": "s3://mybucket/j2k_master.mfx",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_codec_profile": "main10",
      "video_bit_depth": 10,
      "video_color_format": "hdr10",
      "master_display": {
        "red": {"x": 0.708, "y": 0.292},
        "green": {"x": 0.17, "y": 0.797},
        "blue": {"x": 0.131, "y": 0.046},
        "white_point": {"x": 0.31273,"y": 0.329},
        "luminance": {"max": 1000,"min": 0.0001}
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

See also:

max_frame_average_light_level

max_frame_average_light_level:Number

API Versions: V2

Parents: outputs, dynamic_profile_options

Default: none

Valid Values: 5.0-10000.0

Compatible Job Types: vod

Example: 180

Description:

Describes maximum frame-average (and maximum red-, green-, and blue- channel-wise) light level across video sequence. Expressed in candellas per meter squared. This value can be set 0, implying that such bound is unknown or not imposed. This parameter, also known as MaxFALL is defined by the CAE 861.3 standard.

Both the max_content_light_level and max_frame_average_light_level parameters are mandatory and must be included in the outputs when encoding videos in HDR-10 format.

The example below shows how max_content_light_level, and max_frame_average_light_level metadata can be specified:

{
  "input": "s3://mybucket/j2k_master.mfx",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_codec_profile": "main10",
      "video_bit_depth": 10,
      "video_color_format": "hdr10",
      "master_display": {
        "red": {"x": 0.708, "y": 0.292},
        "green": {"x": 0.17, "y": 0.797},
        "blue": {"x": 0.131, "y": 0.046},
        "white_point": {"x": 0.31273,"y": 0.329},
        "luminance": {"max": 1000,"min": 0.0001}
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

See also:

dolby_vision_rpu_url

dolby_vision_rpu_url:String

API Versions: V2

Parents: outputs, dynamic_profile_options

Default: none

Compatible Job Types: vod

Description:

This parameter is currently required when transcoding videos in DolbyVision 5 and DolbyVision 8.1 formats.

Usage example: 

{
  "input": "s3://mybucket/dv5_master.mp4",
  "outputs": [
   {
    "video_codec": "hevc",
    "video_codec_profile": "main10",
    "video_bit_depth": 10,
    "video_color_format": "dv5",
    "video_color_range": "full",
    "dolby_vision_rpu_url": "s3://mubucket/dv5_master_rpu.rpu"
   }
  ]
}

See also:

video_color_range

video_color_range:String

API Versions: V2

Parents: outputs, dynamic_profile_options

Valid values: limited, full

Default: none

Compatible Job Types: vod

Description:

Indicates the dynamic range of pixel values. For example, for 8-bit pixels, limited implies that Y (luma) pixel values will stay in the range from 16 to 235, while full implies that Y (luma) pixel values will be in range from 0 to 255.

The vast majority of content is currently produced and encoded using limited pixels. However full-range pixels may also be sometimes used. For example, 10-bit-wide full-range pixels are used in the DolbyVision 5 format.

Usage example: 

{
  "input": "s3://mybucket/dv5_master.mp4",
  "outputs": [
   {
    "video_codec": "hevc",
    "video_codec_profile": "main10",
    "video_bit_depth": 10,
    "video_color_format": "dv5",
    "video_color_range": "full",
    "dolby_vision_rpu_url": "s3://mubucket/dv5_master_rpu.rpu"
   }
  ]
}

See also:

red

red:Object

API Versions: V2

Parent: master_display

Default: none

Compatible Job Types: vod

Description:

Hash containing color volume setting for red.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

x

x:Number

API Versions: V2

Parent: master_display:red

Default: none

Valid Values: 0.0001-0.7400

Compatible Job Types: vod

Example: 0.708

Description:

Color volume x setting for red.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

y

y:Number

API Versions: V2

Parent: master_display:red

Default: none

Valid Values: 0.0001-0.8400

Compatible Job Types: vod

Example: 0.292

Description:

Color volume y setting for red.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

green

green:Object

API Versions: V2

Parent: master_display

Default: none

Compatible Job Types: vod

Description:

Hash containing color volume setting for green.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

x

x:Number

API Versions: V2

Parent: master_display:green

Default: none

Valid Values: 0.0001-0.7400

Compatible Job Types: vod

Example: 0.17

Description:

Color volume x setting for green.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

y

y:Number

API Versions: V2

Parent: master_display:green

Default: none

Valid Values: 0.0001-0.8400

Compatible Job Types: vod

Example: 0.797

Description:

Color volume y setting for green.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

blue

blue:Object

API Versions: V2

Parent: master_display

Default: none

Compatible Job Types: vod

Description:

Hash containing color volume setting for blue.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

x

x:Number

API Versions: V2

Parent: master_display:blue

Default: none

Valid Values: 0.0001-0.7400

Compatible Job Types: vod

Example: 0.131

Description:

Color volume x setting for blue.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

y

y:Number

API Versions: V2

Parent: master_display:blue

Default: none

Valid Values: 0.0001-0.8400

Compatible Job Types: vod

Example: 0.046

Description:

Color volume y setting for blue.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

white_point

white_point:Object

API Versions: V2

Parent: master_display

Default: none

Compatible Job Types: vod

Description:

Hash containing color volume setting for white_point.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

x

x:Number

API Versions: V2

Parent: master_display:white_point

Default: none

Valid Values: 0.0001-0.7400

Compatible Job Types: vod

Example: 0.31273

Description:

Color volume x setting for white_point.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

y

y:Number

API Versions: V2

Parent: master_display:white_point

Default: none

Valid Values: 0.0001-0.8400

Compatible Job Types: vod

Example: 0.329

Description:

Color volume y setting for white_point.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

luminance

luminance:Object

API Versions: V2

Parent: master_display

Default: none

Compatible Job Types: vod

Description:

Hash containing luminance settings.

{
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

min

min:Number

API Versions: V2

Parent: master_display:luminance

Default: none

Valid Values: 0.0001-5.0

Compatible Job Types: vod

Example: 0.0001

Description:

Minimum luminance in nits or candelas per square meter (cd/m2).

        {
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}

max

max:Number

API Versions: V2

Parent: master_display:luminance

Default: none

Valid Values: 5.0-10000.0

Compatible Job Types: vod

Example: 1000

Description:

Maximum luminance in nits or candelas per square meter (cd/m2).

        {
  "input": "s3://mybucket/hdr_master.mov",
  "outputs": [
    {
      "video_codec": "hevc",
      "video_bit_depth": 10,
      "master_display": {
        "red": {
          "x": 0.708,
          "y": 0.292
        },
        "green": {
          "x": 0.17,
          "y": 0.797
        },
        "blue": {
          "x": 0.131,
          "y": 0.046
        },
        "white_point": {
          "x": 0.31273,
          "y": 0.329
        },
        "luminance": {
          "max": 1000,
          "min": 0.0001
        }
      },
      "max_content_light_level": 1000,
      "max_frame_average_light_level": 180
    }
  ]
}