Zencoder Encoding Settings: Segmented Streaming

Product(s)
Zencoder
Role(s)
API Developer
Topic(s)
Encoding Settings
API(s)
Zencoder API

This topic contains details for encoding settings related to segmented streaming.

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, and type.
  • 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: V1, V2

Parent: outputs

Valid Values: dash

Compatible Job Types: All

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

Parent: outputs

Default: live

Valid Values: live, hbbtv_1.5, on_demand

Compatible Job Types: All

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 DASH profile to "urn:mpeg:dash:profile:isoff-live:2011" and use a single SegmentTemplate for each AdaptationSet. For DRM, it will use an 8-byte IV, and for PlayReady will use version 1.1, including a PSSH atom in the media.
  • hbbtv_1.5 - Will set the DASH profile 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 for PlayReady will use version 1.0, excluding PSSH atoms.
  • on_demand - Will set the DASH profile 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: V1, V2

Parent: outputs

Valid Values: dash, mpd, hls, m3u, m3u8, ism, mss, highwinds

Compatible Job Types: All

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

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

Parent: outputs

Valid Values: Hash of alternate audio groups, each of which is an array of audio stream rendition hashes

Compatible Job Types: All

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

Parent: outputs

Valid Values: Array of hashes containing playlist stream info

Compatible Job Types: All

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

Parent: outputs / streams

Valid Values: String containing an absolute or relative path to a manifest file

Compatible Job Types: All

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

Parent: outputs / streams

Valid Values: Positive integer values in Kbps

Compatible Job Types: All

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

Parent: outputs / streams

Valid Values: String containing width and height as: 800x600

Compatible Job Types: All

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

Parent: outputs / streams

Valid Values: String containing codecs in HTML5 format, such as: mp4a.40.2

Compatible Job Types: All

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

Parent: outputs / streams

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

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

Parent: outputs

Compatible Job Types: All

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

Parent: outputs

Default: false

Valid Values: true or false

Compatible Job Types: All

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

Parent: outputs / streams

Compatible Job Types: All

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

Parent: outputs / streams

Default: 3 for Live outputs, 5 for sample AES encryption; otherwise, 2.

Valid Values: 2-5

Compatible Job Types: All

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

Parent: outputs / streams

Default: Automatic according to max_hls_protocol_version setting

Valid Values: 2-5

Compatible Job Types: All

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

Parent: outputs / streams

Default: true

Valid Values: true or false

Compatible Job Types: All

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

Parent: outputs

Valid Values: hls, mss, dash

Compatible Job Types: All

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

Parent: outputs

Compatible Job Types: All

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

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

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

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

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