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_renditionsrequiredmin_bitratemax_bitratemax_first_rendition_bitratemin_resolutionmax_resolutionmax_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.
| 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.
| 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.
| 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 |