General Output Settings

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

type

type:String

API Versions: V2

Parent: outputs

Default: standard

Valid Values:

  • cae
  • captions
  • playlist
  • segmented
  • standard
  • transfer-only

Compatible Job Types: VOD

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.

  • cae for Context Aware Encoding (see CAE Guide)
  • 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.
    • Alternatively, if your account is enabled for auto-captioning by Brightcove Support, you can request that captions be generated automatically from the audio track - see Auto Transcription.
    • 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 and Auto Transcription.

label

label:String

API Versions: V2

Parent: outputs

Valid Values: A string

Compatible Job Types: VOD

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

cae_options

cae_options:Hash

API Versions: V2

Parent: outputs

Compatible Job Types: VOD

Description:

The cae_options object specifies the settings for CAE encoding. (See the CAE Settings for the full list of settings that are automatically set by CAE.) cae_options may only be used if the output type is cae

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "cae",
      "label": "cae_profile",
      "cae_options": {
        "min_renditions": 1,
        "max_renditions": 6
      }
    },
    {"source": "cae_profile", "cae_rendition": 1}, {"source": "cae_profile", "cae_rendition": 2},
    {"source": "cae_profile", "cae_rendition": 3}, {"source": "cae_profile", "cae_rendition": 4},
    {"source": "cae_profile", "cae_rendition": 5}, {"source": "cae_profile", "cae_rendition": 6}
  ]
}

See Also: source

reference_profile_for_comparision

reference_profile_for_comparision:<cae-output-label> String

API Versions: V2

Parent: outputs

Compatible Job Types: VOD

Description:

The reference_profile_for_comparision compares and analyzes the CAE-generated profile for a reference static profile. The string used should match the label of the reference CAE output. For example, if your static profile contains seven renditions, to see how that profile does, you can use the following: 

{
  "input": "s3+us-east-1://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "cae",
      "label": "ref_static_profile",
      "cae_options": {
        "video_configurations":[
        {"width": 416, "height": 234, "video_codec": "h264", "bitrate": 145},
        {"width": 640, "height": 360, "video_codec": "h264", "bitrate": 365},
        {"width": 768, "height": 432, "video_codec": "h264", "bitrate": 730},
        {"width": 768, "height": 432, "video_codec": "h264", "bitrate": 1100},
        {"width": 960, "height": 540, "video_codec": "h264", "bitrate": 2000},
        {"width": 1280, "height": 720, "video_codec": "h264", "bitrate": 3000},
        {"width": 1280, "height": 720, "video_codec": "h264", "bitrate": 4500}]
      }
    },
    {
      "type": "cae",
      "label": "cae_profile",
      "reference_profile_for_comparison": "ref_static_profile",
      "cae_options": {
        "max_bitrate": "5000",
        "max_resolution": { "height": 1080},
        "max_renditions": 7
      }
    }
  ]
}

See Also: source

cae_rendition

cae_rendition:Integer

API Versions: V2

Parent: outputs

Compatible Job Types: VOD

Description:

The cae_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 cae_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" :[
  {"cae_rendition": 1},
  {"cae_rendition": 2},
  {"cae_rendition": 3},
  {"cae_rendition": 4},
  {"cae_rendition": 5},
  {"cae_rendition": 6}
  ]
}

See Also: source

dynamic_profile_rendition DEPRECATED

dynamic_profile_rendition:Integer

API Versions: V2

Parent: outputs

Compatible Job Types: VOD

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

Parent: outputs

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

Compatible Job Types: VOD

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

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. Zencoder will upload to a temp s3 place when you do not provide this.

See Also: url

base_url

base_url:String

API Versions: V2

Parent: outputs

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

Compatible Job Types: VOD

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

Parent: outputs

Valid Values: A valid video, audio, or captions filename.

Compatible Job Types: VOD

Examples: final.mp4, captions.vtt

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

Parent: outputs

Valid Values: A valid package filename.

Compatible Job Types: VOD

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

Parent: outputs

Valid Values: zip and tar

Compatible Job Types: VOD

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

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

Parent: outputs

Default: false

Valid Values: true or false

Compatible Job Types: VOD

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

Parent: outputs

Default: false

Valid Values: true or false

Compatible Job Types: VOD

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

Parent: outputs

Default: false

Valid Values: true or false

Compatible Job Types: VOD

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

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

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

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

Parents: outputs OR thumbnails

Compatible Job Types: VOD

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