support Contact Support | system status System Status
Page Contents

    CAE Settings

    This topic covers Context Aware Encoding (CAE) settings for Zencoder.

    Overview

    Context Aware Encoding creates multiple renditions of your source video based on guidelines you provide, but also based on the characteristics of the video itself. This helps to avoid the cost of transcoding and storing your videos by creating renditions that will be essentially worthless, given the characteristics of the source.

    See the CAE Guide for additional information and recommendations on settings.

    video_codecs

    video_codecs:Array

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Array Item Values: h264, hevc

    Default Value: none

    Compatible Job Types: VOD

    Example: ["h264", "hevc"]

    Description:

    For mixed-codec outputs, an array of the codecs to create renditions for. Currently, the allowed item values are h264 and hevc.

    {
        "dynamic_profile_options": {
          "max_renditions": 6,
          "video_codecs" : ["h264", "hevc"'],
          "video_codec_options": {
            "h264": {
              "min_renditions": 2,
              "max_resolution": { "width": 1280, "height": 720 }
            },
            "hevc": {
              "min_renditions": 2,
              "max_resolution": { "width": 1920, "height": 1080 }
            }
          }
        }
      }

    video_codec_options

    video_codecs:Object

    API Versions: V2

    Parent: dynamic_profile_options

    Default Value: none

    Compatible Job Types: VOD

    Example:

    "video_codec_options": {
      "h264": {
        "min_renditions": 2,
        "max_resolution": { "width": 1280, "height": 720 }
      },
      "hevc": {
        "min_renditions": 2,
        "max_resolution": { "width": 1920, "height": 1080 }
      }
    }

    Description:

    For mixed-codec outputs, an object specifying the options for each codec. Each property is an object with the name h264 or hevc, its properties are the set the constraints for renditions for that codec. The allowed properties for these objects are:

    • min_renditions required
    • min_bitrate
    • max_bitrate
    • max_first_rendition_bitrate
    • min_resolution
    • max_resolution
    • max_first_rendition_resolution
    {
        "dynamic_profile_options": {
          "max_renditions": 6,
          "video_codecs" : ["h264", "hevc"'],
          "video_codec_options": {
            "h264": {
              "min_renditions": 2,
              "max_resolution": { "width": 1280, "height": 720 }
            },
            "hevc": {
              "min_renditions": 2,
              "max_resolution": { "width": 1920, "height": 1080 }
            }
          }
        }
      }

    min_renditions

    min_renditions:Integer

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 1-15

    Default Value: 1

    Compatible Job Types: VOD

    Example: 3

    Description:

    The minimum number of renditions to generate.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2
              }
            }

    max_renditions

    max_renditions:Integer

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 1-15

    Default Value: 8

    Compatible Job Types: VOD

    Example: 10

    Description:

    The maximum number of renditions to generate.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10
              }
            }

    min_resolution

    min_resolution:Object

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 16x16 - 8192x8192

    Default Value: 192x108

    Compatible Job Types: VOD

    Example: see below

    Description:

    Minimum resolution to be considered for the ladder.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "min_resolution": {
                  "height": 180,
                  "width": 320
                }
              }
            }

    max_resolution

    max_resolution:Object

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 16x16 - 8192x8192

    Default Value: source resolution

    Compatible Job Types: VOD

    Example: see below

    Description:

    Maximum resolution to be considered for the ladder.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "min_resolution": {
                  "height": 180,
                  "width": 320
                },
                "max_resolution": {
                  "height": 1080,
                  "width": 1920
                }
              }
            }

    max_frame_rate

    max_frame_rate:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 0.1 - 120

    Default Value: 30

    Compatible Job Types: VOD

    Example: 60

    Description:

    Maximum frame rate that can be used.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "max_frame_rate": 60
              }
            }

    keyframe_rate

    keyframe_rate:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 0.5, 1.0

    Default Value: 0.5

    Compatible Job Types: VOD

    Example: 0.5

    Description:

    Keyframe rate. This value can be either 0.5 or 1. For SSAI enabled content, this value needs to be 1.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "keyframe_rate": 0.5
              }
            }

    fixed_frame_rate

    fixed_frame_rate:Boolean

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: true or false

    Default Value: true

    Compatible Job Types: VOD

    Example: true

    Description:

    Instructs generator to use same frame rate across all renditions. If false, H.264 baseline profile renditions at resolutions below 360p will be assigned halved frame rate.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "fixed_frame_rate": true
              }
            }

    min_bitrate

    min_bitrate:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 40 - 400

    Default Value: 200

    Compatible Job Types: VOD

    Example: 300

    Description:

    Minimum bitrate [kbps] that can be used.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "min_bitrate": 300
              }
            }

    max_bitrate

    max_bitrate:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 400 - 40000

    Default Value: 15000

    Compatible Job Types: VOD

    Example: 20000

    Description:

    Maximum bitrate [kbps] that can be used.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "min_bitrate": 300,
                "max_bitrate": 20000
              }
            }

    max_first_rendition_bitrate

    max_first_rendition_bitrate:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 40 - 1000

    Default Value: 400

    Compatible Job Types: VOD

    Example: 700

    Description:

    Maximum bitrate [kbps] that can be used for first rendition.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "min_bitrate": 300,
                "max_bitrate": 20000
                "max_first_rendition_bitrate": 700
              }
            }

    min_granularity

    min_granularity:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 1 - 100 (%)

    Default Value: 30 (%)

    Compatible Job Types: VOD

    Example: 20

    Description:

    Minimum relative change in bitrate between renditions.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "min_granularity": 20
              }
            }

    max_granularity

    max_granularity:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 1 - 100 (%)

    Default Value: 90 (%)

    Compatible Job Types: VOD

    Example: 80

    Description:

    Maximum relative change in bitrate between renditions.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "min_granularity": 20,
                "max_granularity": 80
              }
            }

    video_codec

    video_codec:String

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: h264, hevc

    Default Value: h264

    Compatible Job Types: VOD

    Example: h264

    Description:

    Video codec to use.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "video_codec": "h264"
              }
            }

    bitrate_cap_to_bitrate_ratio

    bitrate_cap_to_bitrate_ratio:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 1.0 - 2.0

    Default Value: 1.3

    Compatible Job Types: VOD

    Example: 1.5

    Description:

    Ratio of maximum bit rate to average bitrate to be used for VBR encoding.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "bitrate_cap_to_bitrate_ratio": 1.5
              }
            }

    buffer_size_to_bitrate_ratio

    buffer_size_to_bitrate_ratio:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: 1.0 - 4.0

    Default Value: 2.0

    Compatible Job Types: VOD

    Example: 2.5

    Description:

    Ratio of decoder buffer size to average bitrate to be used for VBR encoding.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "bitrate_cap_to_bitrate_ratio": 1.5,
                "buffer_size_to_bitrate_ratio": 2.5
              }
            }

    bitrate_cap_offset

    bitrate_cap_offset:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Default Value: 64 [KBPS]

    Compatible Job Types: VOD

    Example: 128

    Description:

    Constant added when computing maximum bitrate.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "bitrate_cap_to_bitrate_ratio": 1.5,
                "buffer_size_to_bitrate_ratio": 2.5,
                "bitrate_cap_offset": 128
              }
            }

    buffer_size_offset

    buffer_size_offset:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Default Value: 85 [KBPS]

    Compatible Job Types: VOD

    Example: 100

    Description:

    Constant added when computing VBV buffer size.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "bitrate_cap_to_bitrate_ratio": 1.5,
                "buffer_size_to_bitrate_ratio": 2.5,
                bitrate_cap_offset": 128,
                "buffer_size_offset": 100
              }
            }

    quality_rate_tune

    quality_rate_tune:Number

    API Versions: V2

    Parent: dynamic_profile_options

    Valid Values: -40.0 - 40.0

    Default Value: 0

    Compatible Job Types: VOD

    Example: 2

    Description:

    By setting quality_rate_tune to a positive number from 1 to 40, CAE profiles will have higher video quality at the cost of higher bitrates. Similarly, given a number in the range from -1 to -40 one can lower the bitrates, at the cost of decreasing video quality.

    For example, with -10 one can expect approximately 10% lower bitrates. With 10, bitrates will in general increase around 10%. These numbers are approximations, since CAE for positive values of quality_rate_tune takes extra precautions in ensuring very high video quality, and there may be other parameters that limit the bitrates such as granularity and number of renditions.

    Since typical content and desired video quality vs bandwidth vary greatly, it may be advisable to experiment with different values.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "quality_rate_tune": 2
              }
            }

    select_baseline_profile_configuration

    select_baseline_profile_configuration:Boolean

    API Versions: V2

    Parent: dynamic_profile_options

    Default Value: true

    Compatible Job Types: VOD

    Example: 100

    Description:

    At least one rendition used in the profile will be baseline profile. Note that select_baseline_profile_configuration is true by default, and it requires at least one rendition to have a resolution at or below 512x288.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "select_baseline_profile_configuration": true
              }
            }

    video_configurations

    video_configurations:Array

    API Versions: V2

    Parent: dynamic_profile_options

    Default: Profile generator uses lists of standard resolutions for all known aspect ratios. Whenever possible, aspect ratio, sample aspect ratio and framerate of the source is preserved in output configurations.

    Compatible Job Types: VOD

    Example: see below

    Description:

    An array of structures describing resolutions, frame rates and associated codec settings that should be preferentially or mandatorily generated as part of the CAE encoding. See the section below.

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options": {
                "min_renditions": 2,
                "max_renditions": 10,
                "video_configurations": [
                  {
                    "width": 1920,
                    "height": 1080,
                    "sample_aspect_ratio": "16:9",
                    "frame_rate": 30,
                    "video_codec_profile": "high",
                    "video_codec_level": 4.1,
                    "video_reference_frames": 4,
                    "video_bframes": 3,
                    "required": true
                  }
                  ]
              }
            }

    watermarks

    watermarks:Array

    API Versions: V2

    Parent: dynamic_profile_options

    Default: Profile generator uses lists of standard resolutions for all known aspect ratios. Whenever possible, aspect ratio, sample aspect ratio and framerate of the source is preserved in output configurations.

    Compatible Job Types: VOD

    Example: see below

    Description:

    An array of hashes describing watermarks.

        {
            "input": "s3://zencodertesting/test.mov",
            "generate_dynamic_profile": true,
            "dynamic_profile_options" : {
              "min_rendition": 2,
              "max_rendition": 6,
              "watermarks":[
               {
                  "url": "{url_to_watermark}",
                 "width": "10%",
                 "height": "10%"
               }
              ]
            }
          }

    Watermarks can also be part of video_configurations:

            {
              "input": "s3://zencodertesting/test.mov",
              "generate_dynamic_profile": true,
              "dynamic_profile_options" : {
                "video_configurations": [
                  {
                   "width": 640,
                   "height": 360,
                    "watermarks":[
                      {
                        "url": "{url_to_watermark}",
                        "x": "-10",
                        "y": 10"
                      }
                    ]
                  },
                  {
                   "width": 960,
                   "height": 540,
                    "watermarks":[
                      {
                        "url": "{url_to_watermark}",
                        "x": "-15",
                        "y": "15"
                     }
                    ]
                  },
                  {
                    "width": 1280,
                    "height": 720,
                    "watermarks":[
                      {
                        "url": "{url_to_watermark}",
                        "x": "-20",
                        "y": "20"
                     }
                    ]
                  }
                ]
              }

    Additional settings

    Below are additional general encoding settings that can be used for CAE.

    Additional Settings
    Name Type Description Default
    speed Integer Encoding speed setting. 3
    one_pass Boolean Force 1-pass encoding. false
    tuning String Codec-specific tuning option.  
    start_clip String/Number Create a clip of the original video, starting at a particular time. This can either be a timecode with a format of HH:MM:SS.S, or a decimal expressing the number of seconds to start at. 0
    clip_length String/Number Create a clip of a particular length. This can either be a duration with a format of HH:MM:SS.S, or a decimal expressing the length of the clip in seconds. source duration

    HDR settings

    CAE also supports HDR10 and the following settings can be included in dynamic_profile_options.

    Additional Settings
    Name Type Description Default
    master_display Object Hash containing color volume and luminance settings for HDR outputs. none
    max_content_light_level Integer Maximum light level for the content as a whole nits or candelas per square meter (cd/m2) - integer values. none
    max_frame_average_light_level Integer Maximum average light level for content frames nits or candelas per square meter (cd/m2) - integer values. Although values up to 10000 are allowed, values in the 100-200 range will generally produce the best results. none

    Video configurations settings

    You may want to use this feature if CAE is not producing specific configurations you must have in your outputs.

    This is an array of objects describing video resolutions and codec settings that CAE should/must produce as part of its output (see the example above). This array is optional. If omitted, an array of default resolutions, ranging from 192x108 to resolution of content will be used as the default input set for CAE.

    Video Configuration Settings
    Name Type Description Required?
    width Integer Video frame width [pixels] required
    height Integer Video frame height [pixels] required
    sample_aspect_ratio Integer:Integer pair Sample aspect ratio (e.g. 1:1, 4:3) optional
    frame_rate Number Video frame rate [fps] optional
    video_codec_profile String video codec profile optional
    video_codec_level String video codec level optional
    video_reference_frames Integer Constraint on number of reference frames. Default=4 (3 for H.264 baseline). optional
    video_bframes Integer Constraint on number of B frames. Default=3 (0 for H.264 baseline). optional
    required Boolean Setting this to true will guarantee the suggested configuration settings in the output. Default = false. optional

    Page last updated on 15 Sep 2020