Zencoder: CAE Settings

Product(s)
Zencoder
Role(s)
API Developer
API(s)
Zencoder API

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.

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: -20.0 - 20.0

Default Value: 0

Compatible Job Types: VOD

Example: 2

Description:

Quality vs rate tuning parameter.

  {
    "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.

  {
    "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
        }
        ]
    }
  }

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 subclip 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 subclip 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 Settins
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