support Contact Support | system status System Status
Page Contents

    General Output Settings

    This topic contains details for encoding settings related to general output settings (applying to all outputs).

    type

    type:String

    API Versions: V1, V2

    Parent: outputs

    Default: standard

    Valid Values: standard, segmented, captions, playlist, and transfer-only

    Compatible Job Types: All

    Example: segmented

    Description:

    By default Zencoder will consider outputs to be standard audio or video files. Currently, there are two special types of outputs: segmented and playlist.

    • segmented: The typical use-case for segmentation is for Apple's Live HTTP Streaming (see Segmented Streaming). For segmented outputs the default format will be changed to ts instead of mp4.
    • captions: API V2 Only
      The captions output type creates a file containing just the captions from the source video, rather than a video with captions added to it. Note: captions type outputs may not be the only outputs for a job.
      Captions may be provided to Zencoder as a separate file (using the caption_url option), or will be extracted from the source video by default.
      Supported formats for extracting captions from the source video are MP4 and TS. In an MP4 file, the captions may be located in a separate track (in CEA-608 format); otherwise captions in an MP4 or TS file must be embedded in an MPEG2 or AVC video stream, compliant to A/53 or SCTE-128 (CC1 and CC3) standards.
      Supported output formats for captions type outputs: 'mp4', 'scc', 'webvtt', 'vtt', 'm3u8', 'dfxp'.
    • playlist: The playlist output type is used in multi-bitrate output streams to generate the master M3U8 playlist file. Note: playlist type outputs may not be the only outputs for a job.
    • transfer-only: API V2 Only
      A transfer-only output skips encoding and sends the original video to a url.
      A transfer-only output can also use source to transfer the video from another output to the specified url, rather than using the input.
    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "type": "segmented"
        }
      ]
    }

    See Also: source and caption_url

    label

    label:String

    API Versions: V1, V2

    Parent: outputs

    Valid Values: A string

    Compatible Job Types: All

    Example: iphone4

    Description:

    An optional label for the output. As of API v2, labels must be unique (case insensitive) per job when used on multiple outputs.

    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "label": "iphone4"
        }
      ]
    }

    See Also: source

    dynamic_profile_rendition

    dynamic_profile_rendition:Integer

    API Versions: V2

    Parent: outputs

    Compatible Job Types: All

    Description:

    The dynamic_profile_rendition setting specifies that this Output should use settings from the dynamically generated CAE profile, and specifically which rendition of the profile to use settings from. When dynamic_profile_rendition is set, there is no need to specify encoding settings such as resolution, bitrate, etc. (See the CAE Guide for the full list of settings that are automatically set by CAE.)

    {
      "input": "s3://zencodertesting/test.mov",
      "generate_dynamic_profile": true,
      "dynamic_profile_options":{ "max_renditions": 6 },
      "outputs" :[
      {"dynamic_profile_rendition": 1},
      {"dynamic_profile_rendition": 2},
      {"dynamic_profile_rendition": 3},
      {"dynamic_profile_rendition": 4},
      {"dynamic_profile_rendition": 5},
      {"dynamic_profile_rendition": 6}
      ]
    }

    See Also: source

    url

    url:String

    API Versions: V1, V2

    Parent: outputs

    Valid Values: A valid S3, Cloud Files, GCS, FTP, FTPS, SFTP, Aspera, Azure, or HTTP address.

    Compatible Job Types: All

    Example:

    • s3://my-output-bucket/final.mp4
    • cf://username:api_key@container/object
    • cf+uk://username:api_key@container/object
    • gcs://access_key:secret_key@gcs-bucket/object
    • ftp://user:password@ftp.example.com/final.mp4
    • sftp://user:password@sftp.example.com/final.mp4
    • aspera://user:password@host:ssh-port/path/to/file.mp4

    Description:

    A full URL, including a filename, to which the output file will be uploaded. Please see base_url for more information about providers.

    We officially support HTTP upload to S3, GCS, Cloud Files, and Akamai.

    Notes on S3:

    You must grant write permissions to Zencoder on the output bucket before submitting a job to Zencoder. Please note that it is the S3 bucket, and not the S3 "path" which needs write permission. For example, an asset at http://s3.amazonaws.com/my_files/0000/video.mp4 needs write access added to "my_files" (the bucket name), not "my_files/0000" (the path).

    To create keys containing special characters that are not valid in URLs (? or #), you must URL encode them (%3F and %23, respectively). All other characters must not be URL encoded.

    You may provide the region of the S3 bucket by setting the URL's protocol to s3+region-name, where "region-name" is defined by this document. For example, to access a file from a bucket in the Asia Pacific (Singapore) region, set the URL to s3+ap-southeast-1://my-bucket/file.mp4.

    Notes on Cloud Files:

    You can specify the region to use (DFW, ORD, or UK) by adding it to the protocol, like cf+ord://username:api_key@container/object. Currently the only Cloud Files regions supported are DFW, ORD and UK. The DFW region will be used by default.

    Any special characters in the container name must be URL encoded.

    Notes on Google Cloud Storage:

    GCS access keys can be found under the "Interoperable Access" section in the Google APIs console. Access keys must be properly escaped.

    GCS bucket names that include dots are not supported.

    Notes on Azure:

    If the URL contains authentication with special characters, make sure that they are properly escaped.

    Notes on FTP:

    If the URL contains authentication with special characters, make sure that they are properly escaped.

    We try to write from the root of your server, so use an absolute path for your URL to ensure that we can write to your server successfully.

    Notes on Aspera:

    The ssh-port portion of the URL is not required, and will default to 22.

    Zencoder runs an Aspera Client on the video encoding servers, which connects to your Aspera Enterprise or Connect Server, which hosts the files.

    This is a similar situation to you running an FTP server to make your files available and Zencoder using an FTP client for file transfer.

    Notes on Akamai NetStorage via HTTPS:

    Zencoder can upload content to Akamai NetStorage either via FTP or HTTPS. To upload content via HTTPS, construct an output url like https://[Host]-nsu.akamaihd.net/[CPCode]/[path]/[file.ext].

    You can reference your Akamai NetStorage Keyname and Key as External Server credentials by setting the External Server User field to the Akamai NetStorage Keyname and the External Server Password to the Akamai NetStorage Key.

    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "url": "s3://my-output-bucket/final.mp4"
        }
      ]
    }

    See Also: secondary_url

    secondary_url

    secondary_url:String

    API Versions: V2

    Parent: outputs

    Valid Values: A valid S3, Cloud Files, GCS, FTP, FTPS, SFTP, Aspera, Azure, or HTTP URL.

    Compatible Job Types: All

    Example: See URL documentation

    Description:

    For VOD Jobs

    A full URL, including a filename, to which the output file will be uploaded if transfer to url fails.

    See Also: url

    base_url

    base_url:String

    API Versions: V1, V2

    Parent: outputs

    Valid Values: A valid S3, Cloud Files, GCS, Aspera, FTP, FTPS, or SFTP URL, without a filename.

    Compatible Job Types: All

    Example:

    • s3://my-output-bucket/
    • cf://username:api_key@container/
    • gcs://access_key:secret_key@gcs-bucket/
    • ftp://user:password@ftp.example.com/path/to
    • http://s3.amazonaws.com/my-output-bucket/
    • aspera://user:password@host:ssh-port/path/to/

    Description:

    A base S3, Cloud Files, GCS, FTP, FTPS, or SFTP directory URL where the transcoded file will be uploaded, without a filename. If filename is not specified, a random filename plus an appropriate extension will be generated.

    Notes on S3:

    You must grant write permissions to Zencoder on the output bucket before submitting a job to Zencoder. Please note that it is the S3 bucket, and not the S3 "path" which needs write permission. For example, an asset at http://s3.amazonaws.com/my_files/0000/video.mp4 needs write access added to "my_files" (the bucket name), not "my_files/0000" (the path).

    You may provide the region of the S3 bucket by setting the URL's protocol to s3+region-name, where "region-name" is defined by this document. For example, to access a file from a bucket in the Asia Pacific (Singapore) region, set the URL to s3+ap-southeast-1://my-bucket/.

    Notes on Cloud Files:

    You can specify the region to use (DFW, ORD, or UK) by adding it to the protocol, like cf+ord://username:api_key@container/object. Currently the only Cloud Files regions supported are DFW, ORD and UK. The DFW region will be used by default.

    Any special characters in the container name must be URL encoded.

    Notes on Google Cloud Storage:

    GCS access keys can be found under the "Interoperable Access" section in the Google APIs console. Access keys must be properly escaped.

    GCS bucket names that include dots are not supported.

    Notes on Azure:

    If the URL contains authentication with special characters, make sure that they are properly escaped.

    Notes on FTP:

    If the URL contains authentication with special characters, make sure that they are properly escaped.

    We try to write from the root of your server, so use an absolute path for your URL to ensure that we can write to your server successfully.

    Notes on Aspera:

    The ssh-port portion of the URL is not required, and will default to 22.

    Notes on HTTP:

    We officially support HTTP upload to S3, GCS, Cloud Files, and Akamai.

    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "base_url": "s3://my-output-bucket/"
        }
      ]
    }

    See Also: filename

    filename

    filename:String

    API Versions: V1, V2

    Parent: outputs

    Valid Values: A valid video or audio filename.

    Compatible Job Types: All

    Example: final.mp4

    Description:

    The filename of a finished file. If you supply a filename but not a base_url, we will store the file with this filename in a S3 bucket temporarily for you to download.

    Notes on S3:

    To create keys containing special characters that are not valid in URLs (? or #), you must URL encode them (%3F and %23, respectively). All other characters must not be URL encoded.

    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "filename": "final.mp4"
        }
      ]
    }

    See Also: base_url

    package_filename

    package_filename:String

    API Versions: V1, V2

    Parent: outputs

    Valid Values: A valid package filename.

    Compatible Job Types: All

    Example: final.zip

    Description:

    The filename of a packaged output. If the extension matches a valid package_format, this will set the default value for package_format as well. When specified, this value is used in combination with base_url to generate an output URL, rather than filename. If filename is not specified, it will default to the same as package_filename, but with the correct file extension for the media type.

    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "package_filename": "final.zip"
        }
      ]
    }

    See Also: base_url and filename

    package_format

    package_format:String

    API Versions: V1, V2

    Parent: outputs

    Valid Values: zip and tar

    Compatible Job Types: All

    Example: zip

    Description:

    Creates a zip or tar file containing all the media files of an output, and uploads this single package rather than all the individual files. Thumbnails without a separate base_url will be included in sub-directories inside the package file as well.

    If package_filename not specified, the package filename will be generated based on filename (but with the package format as an extension). See package_filename for details on URL handling.

    Note: When thumbnails are included in the package file, the paths within the package will be returned through the API as their URL, rather than a full URL.

    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "package_format": "zip"
        }
      ]
    }

    See Also: package_filename

    device_profile

    device_profile:String

    API Versions: V1, V2

    Valid Values: mobile/advanced, mobile/baseline, mobile/legacy, v1/mobile/advanced, v1/mobile/baseline, v1/mobile/legacy, v2/mobile/advanced, v2/mobile/baseline, and v2/mobile/legacy

    Compatible Job Types: All

    Example: mobile/advanced

    Description:

    Zencoder's device profiles are shortcuts to a set of options that target the playback capability of a particular device or set of devices. Setting a device profile will do nothing more than change the default values used in the API call. That means you can completely override individual settings of a profile to suit your particular needs very easily.

    Versioned device profiles are available and listed below. Specifying a version (v1/mobile/baseline) will ensure that you'll always get the same profile, while non-version specific profiles (mobile/baseline) may be changed over time as better options become available.

    Profiles and their default values:

    • mobile/advanced: {"size": "1280x720", "audio_bitrate": 56, "max_audio_sample_rate": 48000, "max_frame_rate": 30, "max_video_bitrate": 5000, "video_codec_level": 3.1, "videoe_codec_profile": "main"}
    • mobile/baseline: {"size": "480x320", "audio_bitrate": 96, "max_audio_sample_rate": 44100, "max_frame_rate": 30, "max_video_bitrate": 1500, "video_reference_frames": 1}
    • mobile/legacy: {"size": "320x240", "audio_bitrate": 96, "max_audio_sample_rate": 44100, "max_frame_rate": 30, "max_video_bitrate": 768, "video_codec_level": 1.3, "video_reference_frames": 1}
    • v1/mobile/advanced: {"size": "1280x720", "audio_bitrate": 128, "max_audio_sample_rate": 48000, "max_frame_rate": 30, "max_video_bitrate": 5000, "video_codec_level": 3.1, "videoe_codec_profile": "main"}
    • v1/mobile/baseline: {"size": "480x320", "audio_bitrate": 96, "max_audio_sample_rate": 44100, "max_frame_rate": 30, "max_video_bitrate": 1500}
    • v1/mobile/legacy: {"size": "320x240", "audio_bitrate": 24, "max_audio_sample_rate": 16000, "max_frame_rate": 15, "max_video_bitrate": 192, "video_bitrate": 192, "bitrate_cap": 192, "upscale": true, "aspect_mode": "pad", "format": "3gp", "video_codec": "mpeg4"}
    • v2/mobile/advanced: {"size": "1280x720", "audio_bitrate": 56, "max_audio_sample_rate": 48000, "max_frame_rate": 30, "max_video_bitrate": 5000, "video_codec_level": 3.1, "videoe_codec_profile": "main"}
    • v2/mobile/baseline: {"size": "480x320", "audio_bitrate": 96, "max_audio_sample_rate": 44100, "max_frame_rate": 30, "max_video_bitrate": 1500, "video_reference_frames": 1}
    • v2/mobile/legacy: {"size": "320x240", "audio_bitrate": 96, "max_audio_sample_rate": 44100, "max_frame_rate": 30, "max_video_bitrate": 768, "video_codec_level": 1.3, "video_reference_frames": 1}
    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "device_profile": "mobile/advanced"
        }
      ]
    }

    See Also: format

    strict

    strict:Boolean

    API Versions: V1, V2

    Parent: outputs

    Default: false

    Valid Values: true or false

    Compatible Job Types: All

    Example: true

    Description:

    Enable "strict" mode. By default, we will try to correct encoding problems for you. This is called "compatible" mode. For example, if you set a video bitrate that is too low for our encoder, we will automatically correct and use the lowest possible bitrate. So if you ask for a bitrate of 150kbps, but the encoder can't do anything lower than 200kbps, we will automatically encode the video at 200kbps for you.

    If you enable "strict" mode, we will not correct encoding settings like these. Instead, we will fail the job, because we cannot meet your target spec.

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

    skip_video

    skip_video:Boolean

    API Versions: V1, V2

    Parent: outputs

    Default: false

    Valid Values: true or false

    Compatible Job Types: All

    Example: true

    Description:

    Passing skip_video will strip or remove the video track from the input and the resulting file will only contain audio.

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

    skip_audio

    skip_audio:Boolean

    API Versions: V1, V2

    Parent: outputs

    Default: false

    Valid Values: true or false

    Compatible Job Types: All

    Example: true

    Description:

    Passing skip_audio will strip or remove the audio track from the input and the resulting file will only contain video.

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

    source

    source:String

    API Versions: V2

    Parent: outputs

    Compatible Job Types: All

    Example: parent

    Description:

    References a label on another output and uses the video created by that output for processing instead of the input file.

    Using source in conjunction with a type of "transfer-only" allows transferring a single output video to a second url. Useful for sending a single video to multiple destinations.

    {
      "input": "s3://zencodertesting/test.mov",
      "output": [
        {
          "label": "parent",
          "url": "s3://bucket/video.mp4"
        },
        {
          "source": "parent",
          "url": "s3://other-bucket/video.mp4",
          "type": "transfer-only"
        }
      ]
    }

    See Also: label and type

    credentials

    credentials:String

    API Versions: V2

    Parent: outputs

    Compatible Job Types: All

    Example: s3_production

    Description:

    References the nickname of saved credentials to use for transfer.

    Credentials can only be used with URLs that match their type; for example, S3 credentials paired with an FTP URL will be rejected.

    Note: The most "precise" credentials specified take precedence. For instance, credentials passed in the URL will take precedence over the credentials parameter, just as the credentials parameter takes precedence over default credentials.

    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "url": "s3://bucket/video.mp4",
          "credentials": "s3_production"
        }
      ]
    }

    See Also: url and base_url

    generate_md5_checksum

    generate_md5_checksum:Boolean

    API Versions: V2

    Default: false

    Valid Values: true or false

    Compatible Job Types: All

    Description:

    Generates an MD5 checksum for the generated output file.

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

    parallel_upload_limit

    parallel_upload_limit:Integer

    API Versions: V1, V2

    Default: 30 for S3, 10 for all other destinations.

    Valid Values: An integer between 1 and 30

    Compatible Job Types: vod

    Example: 5

    Description:

    The maximum number of simultaneous uploads made when uploading multipart outputs, primarily HLS segments.

    parallel_upload_limit must be set for individual outputs, not the entire job.

     

    This may speed up transfer times, depending on the bandwidth at your remote server. Be aware that more connections can place a heavier load on the server. If you have trouble with upload timeouts, or want to prevent Zencoder from using too much bandwidth when uploading files, set this to 1.

    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "parallel_upload_limit": 5,
          "url": "s3://my-output-bucket/final.mp4",
          "credentials": "s3_production"
        },
        {
          "parallel_upload_limit": 5,
          "device_profile": "mobile/advanced",
          "url": "s3://my-output-bucket/mobile.mp4",
          "credentials": "s3_production"
        }
      ]
    }

    headers

    headers:Hash

    API Versions: V1, V2

    Parents: outputs OR thumbnails

    Compatible Job Types: All

    Example: { "Content-Type": "binary/octet-stream" }

    Description:

    HTTP headers to send with your file when we upload it. This feature is currently supported when using S3, GCS and Cloud Files.

    Zencoder supports setting a limited subset of these headers: Cache-Control, Content-Disposition, Content-Encoding, Content-Type, Expires, x-amz-acl, x-amz-storage-class, x-amz-server-side-encryption, x-amz-meta-*, x-goog-acl and x-goog-meta-*.

    Headers will be ignored when an output location is not specified.

    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "url": "s3://my-bucket/file.mp4",
          "headers": {
            "Content-Type": "binary/octet-stream",
            "x-amz-acl": "public-read-write"
          }
        }
      ]
    }

    Page last updated on 12 Jun 2020