support Contact Support | system status System Status
Page Contents

    Resolution Settings

    This topic contains details for encoding settings related to video resolution.

    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

    size:String

    API Versions: V1, 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: All

    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

    width:Integer

    API Versions: V1, V2

    Parent: outputs

    Valid Values: Integers divisible by 4.

    Compatible Job Types: All

    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

    height:Integer

    API Versions: V1, V2

    Parent: outputs

    Valid Values: Integers divisible by 4.

    Compatible Job Types: All

    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

    upscale:Boolean

    API Versions: V1, V2

    Parent: outputs

    Default: false

    Valid Values: true or false

    Compatible Job Types: All

    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

    aspect_mode:String

    API Versions: V1, V2

    Parent: outputs

    Default: preserve

    Valid Values: preserve, stretch, crop, or pad

    Compatible Job Types: All

    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

    sample_aspect_ratio:String

    API Versions: V2

    Parent: outputs

    Compatible Job Types: All

    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

    force_interlace_headers:Boolean

    API Versions: V2

    Parent: outputs

    Compatible Job Types: All

    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


    Page last updated on 28 Sep 2020