Overview
Zencoder supports various forms of adaptive and segmented streaming.
Each streaming format uses a different subset of the API options listed below. Refer to the guides for each streaming type for more information.
NOTES
- A job must have at least one standard or segmented output; creating jobs with only playlist outputs will not work.
- Playlist outputs will ignore most output options, except for url,
base_url,filename,streams,public, andtype. - If a segmented output is uploaded to temporary storage, it will be uploaded as a ZIP archive.
streaming_delivery_format
streaming_delivery_format:String
API Versions: V2
Parent: outputs
Valid Values: dash
Compatible Job Types: VOD
Example: dash
Description:
Sets the format/protocol for an output that will be delivered using a specific streaming configuration, including necessary manifests, directory structures, or other packaging.
For 'dash' outputs, this will also change the default segment_seconds to 2, enforce fixed keyframe intervals, include an MPD manifest, and create a directory structure with initialization and segment files.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "segmented",
"streaming_delivery_format": "dash"
}
]
}
See Also: streaming_delivery_profile
streaming_delivery_profile
streaming_delivery_profile:String
API Versions: V2
Parent: outputs
Default: live
Valid Values: live, hbbtv_1.5, on_demand
Compatible Job Types: VOD
Example: live
Description:
Sets the profile of the streaming delivery format, ensuring options are selected for compatibility with the profile. Valid options depend on the selected streaming_delivery_format.
For dash outputs, the currently supported profiles are:
- live - Will set the
DASHprofile to "urn:mpeg:dash:profile:isoff-live:2011" and use a singleSegmentTemplatefor eachAdaptationSet. For DRM, it will use an 8-byte IV, and forPlayReadywill use version 1.1, including a PSSH atom in the media. - hbbtv_1.5 - Will set the
DASHprofile to "urn:hbbtv:dash:profile:isoff-live:2012" and include required attributes for audio and video representations. For DRM, it will use a 16-byte IV, and forPlayReadywill use version 1.0, excluding PSSH atoms. - on_demand - Will set the
DASHprofile to "urn:mpeg:dash:profile:isoff-on-demand:2011" and encode media as single fragmented files for each stream rather than segmenting them. Otherwise the same as live profile.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "segmented",
"streaming_delivery_format": "dash",
"streaming_delivery_profile": "hbbtv_1.5"
}
]
}
See Also: streaming_delivery_format
playlist_format
playlist_format:String
API Versions: V2
Parent: outputs
Valid Values: dash, mpd, hls, m3u, m3u8, ism, mss, highwinds
Compatible Job Types: VOD
Example: dash
Description:
Sets format for a playlist (rendition manifest) output.
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "playlist",
"playlist_format": "dash"
}
]
}
segment_seconds
segment_seconds:Float
API Versions: V2
Parent: outputs
Default: 10
Valid Values: Numbers between 1.0 and 3600.0; values less than 2.0 are only allowed when byte_range_segmenting is enabled. Because very short segments have been found to cause playback issues, the final segment may be longer than the specified value.
Compatible Job Types: VOD
Example: 8
Description:
Sets the maximum duration of each segment in a segmented output.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "segmented",
"segment_seconds": 8
}
]
}
alternate_audio
alternate_audio:Hash
API Versions: V2
Parent: outputs
Valid Values: Hash of alternate audio groups, each of which is an array of audio stream rendition hashes
Compatible Job Types: VOD
Description:
Provides a set of alternate audio streams for HLS playlists. Requires max_hls_protocol_version to be 4 or greater.
This option will insert EXT-X-MEDIA tags into the playlist. If name is not set, then a name will be generated based on the given language.
Valid Options for Alternate Audio Renditions
language: The ISO 639 code for the language of the audio track, like "en", "es", or "zh".name(optional): The name of the alternate audio group. If name is not set, this will default to the language name.path(optional): An optional path to the M3U8 playlist for this audio rendition. If the path is not set, this alternate audio stream describes the audio contained in the source stream.source(optional): The label on a media output of the same job. This can be used to set the codec for renditions that use this audio stream.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "playlist",
"alternate_audio": {
"custom_audio_group": [
{
"source": "english-audio",
"path": "alternate-audio-en.m3u8",
"language": "en"
},
{
"source": "french-audio",
"path": "alternate-audio-fr.m3u8",
"language": "fr"
}
],
"secondary_audio_group": {
"path": "path/to/secondary-audio-group.m3u8",
"language": "en",
"name": "Secondary English Audio Track",
"source": "secondary-english-audio"
}
}
}
]
}
streams
streams:Array
API Versions: V2
Parent: outputs
Valid Values: Array of hashes containing playlist stream info
Compatible Job Types: VOD
Description:
Provides a list of stream info to be reformatted as a playlist.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "playlist",
"streams": [
{
"path": "low/index.m3u8",
"source": "low-hls-rendition"
},
{
"path": "high/index.m3u8",
"source": "high-hls-rendition"
}
]
}
]
}
path
path:String
API Versions: V2
Valid Values: String containing an absolute or relative path to a manifest file
Compatible Job Types: VOD
Description:
Specifies the path to a stream manifest file.
Note: Required for each stream for HLS, Microsoft Smooth Streaming, and Highwinds SMIL playlists.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "playlist",
"streams": [
{
"path": "low/index.m3u8",
"source": "low-hls-rendition"
},
{
"path": "http://example.com/video/high/index.m3u8",
"source": "high-hls-rendition"
}
]
}
]
}
bandwidth
bandwidth:Integer
API Versions: V2
Valid Values: Positive integer values in Kbps
Compatible Job Types: VOD
Example: 500
Description:
Specifies the bandwidth of a playlist stream. Overrides bandwidth determined from a source.
Note: Required for each stream for HLS and Highwinds SMIL playlists, unless a source is provided.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "playlist",
"streams": [
{
"path": "low/index.m3u8",
"bandwidth": 240
},
{
"path": "high/index.m3u8",
"bandwidth": 640
}
]
}
]
}
resolution
resolution:String
API Versions: V2
Valid Values: String containing width and height as: 800x600
Compatible Job Types: VOD
Description:
Specifies the resolution of a playlist stream. Overrides resolution determined from a source.
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "playlist",
"streams": [
{
"path": "low/index.m3u8",
"bandwidth": 240,
"resolution": "320x180"
},
{
"path": "high/index.m3u8",
"bandwidth": 640,
"resolution": "640x360"
}
]
}
]
}
codecs
codecs:String
API Versions: V2
Valid Values: String containing codecs in HTML5 format, such as: mp4a.40.2
Compatible Job Types: VOD
Description:
Specifies the codecs used in a playlist stream. Overrides codecs determined from a source.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "playlist",
"streams": [
{
"path": "low/index.m3u8",
"bandwidth": 240,
"codecs": "avc1.42001e, mp4a.40.2"
},
{
"path": "audio/index.m3u8",
"bandwidth": 64,
"codecs": "mp4a.40.2"
}
]
}
]
}
audio
audio:String
API Versions: V2
Valid Values: String containing the name of the audio GROUP-ID to use. This value must have been defined as an alternate_audio grouping. The codecs setting should reflect all codecs of the alternate audio group.
Compatible Job Types: VOD
Description:
Specifies an alternate audio track for the playlist.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "playlist",
"alternate_audio": {
"ac3_audio": {
"path": "path/to/ac3-audio.m3u8",
"language": "en",
"default": true,
"source": "ac3-audio-rendition"
},
"source_audio": {
"language": "en",
"default": true
}
},
"streams": [
{
"path": "low/index.m3u8",
"source": "low-hls-rendition",
"audio": "ac3_audio"
},
{
"path": "low/index.m3u8",
"source": "low-hls-rendition",
"audio": "source_audio"
}
]
}
]
}
segment_image_url
segment_image_url:String (URL)
API Versions: V2
Parent: outputs
Compatible Job Types: VOD
Description:
When creating audio-only segments, use the specified image file as a thumbnail for each segment.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "segmented",
"segment_image_url": "http://example.com/thumb.png"
}
]
}
segment_video_snapshots
segment_video_snapshots:Boolean
API Versions: V2
Parent: outputs
Default: false
Valid Values: true or false
Compatible Job Types: VOD
Example: true
Description:
When segmenting a video file into audio-only segments, take snapshots of the video as thumbnails for each segment.
This option has no effect if segment_image_file is set.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"segment_video_snapshots": true
}
]
}
See Also: segment_image_url
source
source:String
API Versions: V2
Compatible Job Types: VOD
Description:
References a label on a media output of the same job, to fill in the corresponding data in the playlist.
For HLS, the bandwidth, codecs, and resolution values are inferred from the source by default. Any bandwidth, codecs, or resolution values specified for the same stream will override the inferred values.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "playlist",
"streams": [
{
"path": "low/index.m3u8",
"source": "low-hls-rendition"
},
{
"path": "high/index.m3u8",
"source": "high-hls-rendition"
}
]
}
]
}
max_hls_protocol_version
max_hls_protocol_version:Integer
API Versions: V2
Default: 5 for sample AES encryption; otherwise, 2.
Valid Values: 2-5
Compatible Job Types: VOD
Example: 4
Description:
Sets the maximum HLS protocol version to use. Special features will be used as available.
This option should be greater or equal to hls_protocol_version when provided.
Note: Only applies to HTTP Live Streaming outputs.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "segmented",
"path": "file-240k.m3u8",
"bandwidth": 240,
"max_hls_protocol_version": 4
},
{
"type": "segmented",
"path": "file-64k.m3u8",
"bandwidth": 64,
"max_hls_protocol_version": 4
},
{
"filename":"playlist.m3u8",
"public":1,
"max_hls_protocol_version":4,
"streams":[
{
"path":"file-240k.m3u8"
},
{
"path":"file-64k.m3u8"
}
],
"type":"playlist"
}
]
}
See Also: hls_protocol_version
hls_protocol_version
hls_protocol_version:Integer
API Versions: V2
Default: Automatic according to max_hls_protocol_version setting
Valid Values: 2-5
Compatible Job Types: VOD
Example: 3
Description:
Sets the HLS protocol version to use. Special features will be used as available.
Note: Only applies to HTTP Live Streaming outputs.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "segmented",
"hls_protocol_version": 3
}
]
}
See Also: max_hls_protocol_version
hls_optimized_ts
hls_optimized_ts:Boolean
API Versions: V2
Default: true
Valid Values: true or false
Compatible Job Types: VOD
Description:
Optimizes TS segment files for HTTP Live Streaming on iOS devices.
Note: Only applies to HTTP Live Streaming outputs.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "segmented",
"hls_optimized_ts": false
}
]
}
prepare_for_segmenting
prepare_for_segmenting:String or Array
API Versions: V2
Parent: outputs
Valid Values: hls, mss, dash
Compatible Job Types: VOD
Example: hls,dash
Description:
If you plan to transmux an output to HLS, MSS, and/or DASH after encoding it with captions to MP4, set this option to true to include captions and keyframe timing for segmenting. This allows the segmented versions to include HLS-compatible captions despite transmuxing, and provides for segmenting at consistent time intervals.
Specify the type of segmented output(s) that this output will later be transmuxed to create, so that Zencoder can prepare the captions and keyframes as necessary.
Note: Captions can not currently be added to HLS outputs when transmuxing.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"prepare_for_segmenting": "hls,dash"
}
]
}
See Also: caption_url and skip_captions
smil-base-url
smil_base_url:String
API Versions: V2
Parent: outputs
Compatible Job Types: VOD
Example: rtmp://127.0.0.1/base/path/
Description:
This will add the tag <meta base="smil_base_url_value"/> to the <head> section of an SMIL playlist.
This example will output a playlist that looks like this:
<smil>
<head>
<meta base="rtmp://123.456.123.123/path/to/videos/"/>
</head>
<body>
<switch>
<video src="mp4:test.mp4" system-bitrate="500000"/>
</switch>
</body>
</smil>
Note: only functions on an output of type playlist, with a format of highwinds.
{
"input": "s3://zencodertesting/test.mov",
"output": [
{
"filename": "test.mp4",
"video_bitrate": 400,
"audio_bitrate": 96
},
{
"type": "playlist",
"format": "highwinds",
"smil_base_url": "rtmp://123.456.123.123/path/to/videos/",
"url": "ftp://my.server/playlist.smil",
"streams": [
{
"path": "test.mp4",
"bandwidth": 500
}
]
}
]
}
byte_range_segmenting
byte_range_segmenting:Boolean
API Versions: V2
Parent: outputs
Default: false
Valid Values: true or false
Compatible Job Types: VOD
Example: true
Description:
Configures HLS segmenting to produce a single output file rather than one file per segment.
Requires max_hls_protocol_version or hls_protocol_version set to 4 or higher.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "segmented",
"format": "ts",
"byte_range_segmenting": true
}
]
}
See Also: max_hls_protocol_version
generate_keyframe_manifest
generate_keyframe_manifest:Boolean
API Versions: V2
Parent: outputs
Default: false
Valid Values: true or false
Compatible Job Types: VOD
Example: true
Description:
Generates an HLS keyframe (I-frame) manifest which is required for fast-forward and reverse playback.
The default keyframe manifest filename is the same as the playlist filename, but with '-iframe-index' added (so for a 'master.m3u8' playlist, the keyframe manifest would be 'master-iframe-index.m3u8'). The keyframe manifest filename can be overridden with keyframe_manifest_filename.
Enabled by default if max_hls_protocol_version or hls_protocol_version is set 4 or greater.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "segmented",
"format": "ts",
"generate_keyframe_manifest": true,
"keyframe_manifest_filename": "my_iframe_index.m3u8"
}
]
}
See Also: keyframe_manifest_filename
keyframe_manifest_filename
keyframe_manifest_filename:String
API Versions: V2
Parent: outputs
Default: iframe_index.m3u8
Compatible Job Types: VOD
Example: my_iframe_index.m3u8
Description:
Unless specified, the filename used for the keyframe manifest is the same as the playlist filename, but with '-iframe-index' appended. For example, for the playlist 'master.m3u8', the keyframe manifest would be 'master-iframe-index.m3u8'.
This option requires that generate_keyframe_manifest is true, or hls_protocol_version is 4 or greater.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "segmented",
"format": "ts",
"generate_keyframe_manifest": true,
"keyframe_manifest_filename": "my_iframe_index.m3u8"
}
]
}
See Also: generate_keyframe_manifest
allow_skipped_sources
allow_skipped_sources:Boolean
API Versions: V2
Parent: outputs
Default: false
Valid Values: true or false
Compatible Job Types: VOD
Example: true
Description:
When generating the playlist, instead of failing the output if any of the referenced streams have been skipped (as part of the conditional outputs functionality), just leave them out of the playlist.
To properly ignore skipped sources, the streams for the playlist must have a source defined.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"type": "playlist",
"allow_skipped_sources": true,
"streams": [
{
"path": "low/index.m3u8",
"source": "low-hls-rendition"
},
{
"path": "high/index.m3u8",
"source": "high-hls-rendition"
}
]
}
]
}
See Also: source