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: cae_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.

{
    "input": "s3://zencodertesting/test.mov",
    "outputs": [
      {
        "type": "cae",
        "cae_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: cae_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
{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "cae"
      "cae_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: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2
      }
    }
  ]
}

max_renditions

max_renditions:Integer

API Versions: V2

Parent: cae_options

Valid Values: 1-15

Default Value: 6

Compatible Job Types: VOD

Example: 10

Description:

The maximum number of renditions to generate.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10
      }
    }
  ]
}

min_resolution

min_resolution:Object

API Versions: V2

Parent: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10,
        "min_resolution": {
          "height": 180,
          "width": 320
        }
      }
    }
  ]
}

max_resolution

max_resolution:Object

API Versions: V2

Parent: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_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: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10,
        "max_frame_rate": 60
      }
    }
  ]
}

keyframe_rate

keyframe_rate:Number

API Versions: V2

Parent: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10,
        "keyframe_rate": 0.5
      }
    }
  ]
}

fixed_frame_rate

fixed_frame_rate:Boolean

API Versions: V2

Parent: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10,
        "fixed_frame_rate": true
      }
    }
  ]
}

min_bitrate

min_bitrate:Number

API Versions: V2

Parent: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10,
        "min_bitrate": 300
    }
  ]
  }
}

max_bitrate

max_bitrate:Number

API Versions: V2

Parent: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_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: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_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: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10,
        "min_granularity": 20
      }
    }
  ]
}

max_granularity

max_granularity:Number

API Versions: V2

Parent: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10,
        "min_granularity": 20,
        "max_granularity": 80
      }
    }
  ]
}

video_codec

video_codec:String

API Versions: V2

Parent: cae_options

Valid Values: h264, hevc

Default Value: h264

Compatible Job Types: VOD

Example: h264

Description:

Video codec to use.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "cae",
      "cae_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: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_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: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_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: cae_options

Default Value: 64 [KBPS]

Compatible Job Types: VOD

Example: 128

Description:

Constant added when computing maximum bitrate.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "cae",
      "cae_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: cae_options

Default Value: 85 [KBPS]

Compatible Job Types: VOD

Example: 100

Description:

Constant added when computing VBV buffer size.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "cae",
      "cae_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: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10,
        "quality_rate_tune": 2
      }
    }
  ]
}

select_baseline_profile_configuration

select_baseline_profile_configuration:Boolean

API Versions: V2

Parent: cae_options

Default Value: false

Compatible Job Types: VOD

Example: 100

Description:

Note that select_baseline_profile_configuration is false by default. If set to 'true' it requires at least one rendition to have a resolution at or below 512x288.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10,
        "select_baseline_profile_configuration": true
      }
    }
  ]
}

select_distinct_configurations

select_distinct_configurations:Boolean

API Versions: V2

Parent: cae_options

Default Value: false

Compatible Job Types: VOD

Example: true

Description:

If true, CAE will ensure that no two renditions use the same combination of: resolution, frame rate, and codec profile.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "min_renditions": 2,
        "max_renditions": 10,
        "select_distinct_configurations": true
      }
    }
  ]
}

video_configurations

video_configurations:Array

API Versions: V2

Parent: cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_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: cae_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",
  "outputs": [
    {
      "type": "cae",
        "cae_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",
  "outputs": [
    {
      "type": "cae",
      "cae_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"
              }
            ]
          }
        ]
    }
  ]
}

true_resolution

true_resolution:String

API Versions: V2

Parent: cae_options

Valid Values: off, detect, limit

Default: off

Compatible Job Types: VOD

Example: detect

Description:

Enables detection of the input video's original or true resolution and limits the CAE-generated profile to true resolution. This option is helpful when input video is upscaled and does not deliver quality as expected at a given resolution. If true_resolution is set to detect, CAE will detect the true resolution, and if it is less than the declared pixel resolution of the input video file, it will produce a warning, advising that the input file is upscaled. If true_resolution is set to limit, CAE will detect the true resolution. Suppose it is less than the declared pixel resolution of the input video file. In that case, it will produce a warning advising that the input file is upscaled. It will also limit the resolutions of renditions to be included in the CAE-generated profile not to exceed the input file's true resolution. Such limiting will enable additional savings in bandwidth and storage needed for a given asset. By default, this feature is off.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "cae",
      "cae_options": {
        "max_renditions": 10,
        "max_resolution": {"width": 1920, "height": 1080},
        "true_resolution": "detect"
      }
    }
  ]
}

Additional settings

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

Additional Settings
Name Type Description Default
deblock Boolean Apply a deblocking filter to the video. false
deinterlace String Determines whether or not to apply a deinterlacing filter. Default is "detect" – if the input file is detected as interlaced, it will be deinterlaced. Set this to "on" to force deinterlacing (which will reduce quality if the input is not interlaced), or "off" to avoid deinterlacing. detect
deinterlace_mode String If not included or set to frame-to-frame, Zencoder outputs will match the framerate of the input file. If set to field-to-frame, Zencoder will double the framerate of the input file for the output. If you manually set framerate to double the framerate of the input file, Zencoder will automatically set deinterlace_mode to field-to-frame and double the framerate for the output. frame-to-frame
denoise String Apply a denoise filter to the video. Valid options are weak, medium, strong, and strongest. Typically reduces file size by 5%-20%, depending on denoising level, bitrate, and source video. Any denoising slows down encoding by about 20%. Values above 'weak' should be used carefully, though animation can sometimes handle a high level of denoising. none (denoising not applied)
speed Integer Encoding speed setting. 3
one_pass Boolean Force 1-pass encoding. false
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 cae_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