Resolution Settings

Overview

You can control the resolution of your output video using one or more resolution settings.

1. Start by setting either size, width, or height. width and height take precedence over size. If you do not set any of these, the original video resolution will be preserved.

2. Then determine if you want to increase the size of videos when the input is smaller than your target output (upscale). By default, we will not upscale videos. Often, your video player can upscale videos for you just fine, so there is no need to upscale the video at the point of encoding (which only increases file size).

3. Finally, select an approach to aspect ratio. If your input video has a different aspect ratio than the resolution that you choose, you can either preserve the original aspect ratio; stretch the video to fit the target aspect ratio; crop the input to match the target aspect ratio; or pad the video with black bars to match the target aspect ratio.

size

API Versions: V2

Parent: outputs

Valid Values: WxH, where W and H are the width and height, respectively. Both dimensions should be an integer divisible by 4.

Compatible Job Types: VOD

Example: 480x320

Description:

The resolution of the output file, expressed as WxH, like 640×480 or 1280×720. Note that width and height take precedence over size.

Aspect mode will be preserved by default, so if the input video is 16:9 and a 4:3 output resolution is requested, the output will maintain the 16:9 aspect ratio. This will result in the output dimensions not matching the requested size. Use aspect_mode to control this.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "size": "480x320"
    }
  ]
}

See Also: width, height, and aspect_mode

width

API Versions: V2

Parent: outputs

Valid Values: Integers divisible by 4.

Compatible Job Types: VOD

Example: 480

Description:

Video frame width. If no width is supplied, we will use the original width, or scale to size or height setting.

Note that width and height take precedence over size.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "width": "480"
    }
  ]
}

See Also: size and height

height

API Versions: V2

Parent: outputs

Valid Values: Integers divisible by 4.

Compatible Job Types: VOD

Example: 640

Description:

Video frame height. If no height is supplied, we will use the original height, or scale to size or width setting.

Note that width and height take precedence over size.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "height": "640"
    }
  ]
}

See Also: size and width

upscale

API Versions: V2

Parent: outputs

Default: false

Valid Values: true or false

Compatible Job Types: VOD

Example: true

Description:

By default, Zencoder will not increase the size of (or “upscale”) an input video to match the width and height you specify in an API request. Generally, upscaling a video just increases the size, but doesn’t really increase the quality. Your playback device (Flash, HTML5 Video, iPhone, etc.) can increase the size of a video rather than having the encoder do it.

But if you do want to force Zencoder to increase the size of an input video, set “upscale” to true. If you do, an input video that is smaller than the output resolution will expand to fit the resolution. For example, if your output spec is 480×360, and someone submits a video that is 320×240, the video will be upsized to 480×360 if you set this option to true, and will remain at 320×240 otherwise.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "upscale": true
    }
  ]
}

aspect_mode

API Versions: V2

Parent: outputs

Default: preserve

Valid Values: preserve, stretch, crop, or pad

Compatible Job Types: VOD

Example: crop

Description:

If the aspect ratio of the input does not match the requested output aspect ratio, what should the output resolution be? “aspect_mode” controls this decision. Note that both the width and height may be modified.

As an example, assume that an input file is 1280×720 (widescreen 16:9), but the target output is 640×480 (standard 4:3). There are four basic approaches to this problem, and Zencoder supports them all.

• preserve: By default, Zencoder will preserve the aspect ratio of the original file, so if you submit widescreen content and ask for standard resolution, the output file will fit keep the widescreen aspect ratio, and will fit within the output size. Presumably, the player will then add black bars to fill up the frame. In our example, the output file will be 640×360 (widescreen 16×9 that fits within the 640×480 target).
• stretch: When the aspect mode is “stretch”, the output video will exactly match the requested width and height, even if it distorts the image. So in our example, the output will be 640×480, but will look vertically stretched. NB: this is not the same as the “upscale” option, above, which governs whether or not a smaller video will be enlarged to a larger frame size.
• crop: This option tells Zencoder to “zoom in” to the video to match the output size, by cropping pixels from the top/bottom or left/right. So if the input is widescreen 1280×720, and the output target is standard 640×480, we will crop roughly 160 pixels from the left and from the right of the input file (creating a 4:3 movie), and then resize that down to 640×480. If you’re old enough to remember non-widescreen VHS (like us), this is the old “pan and scan” option.
• pad: The pad option tells Zencoder to letterbox the video to match the output frame size exactly. Use this option if your target player doesn’t know how to pad a video; otherwise, you’re just wasting bits by including black bars in the actual file. Following our example, this option would take 1280×720 (16:9) content and convert it to 640×480 (4:3) by creating a 640×360 movie, and then placing 60 pixel black bars at the top and bottom of the movie. So the movie would be 640×480, with black bars at the top and bottom.

Note that aspect_mode requires that both a width and a height are provided (or size); otherwise, if only one dimension is provided, we will calculate the other dimension proportionately.

Note: the VP6 video_codec does not support the "pad" aspect_mode. If you ask for "pad" with VP6 video, we will use the default mode of "preserve".

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "aspect_mode": "crop"
    }
  ]
}

sample_aspect_ratio

API Versions: V2

Parent: outputs

Compatible Job Types: VOD

Example: 8:9

Description:

The sample (pixel) aspect ratio to be used for the output video. The size, width, height, and aspect_mode mode options all refer to the encoded pixel dimensions, not the display dimensions.

Sets the aspect ratio to use for sample/pixels of the output video, specified as "8:9", "32:27", or any other ratio of two positive integers, each between 1 and 65535.

Specifying any (valid) value for this setting changes the default 'aspect_mode' from 'preserve' to 'stretch', which means that by default you'll also need to specify a width/height for the encoded output.

Note: It may be useful to use the 'upscale' option in conjunction with this option for predictable output resolutions.

This option only applies when using the H.264 and HEVC codecs.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "sample_aspect_ratio": "8:9"
    }
  ]
}

See Also: aspect_mode, width, height, and size

force_interlace_headers

API Versions: V2

Parent: outputs

Compatible Job Types: VOD

Default: false

Description:

Some decoders ask for interlaced content, but will play progressive content just fine. This setting will add "interlaced" headers to the metadata of progressive content, to make it look like it is actually interlaced.

Note: Some media inspection tools won't be tricked by this, and will report this content as progressive despite the header information.)

This option only applies when using the H.264 codec.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "force_interlace_headers": true
    }
  ]
}

See Also: aspect_mode, width, height, and size