support Contact Support | system status System Status
Page Contents

    Segmented Streaming Settings

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


    Page last updated on 28 Sep 2020