Table of Contents
- Should Fix:: Specify
--[iss|hls|hds|mpd].minimum_fragment_lengthfor relevant output formats
- Should Fix: Use
--variant_setto list ~2Mbit variant first (affects HLS only)
- Should Fix: Configure
--variant_setwhen offering stereo and multi-channel audio (affects HLS only)
- Should Fix: Set
--hls.client_manifest_versionto '4' (affects HLS TS only)
- Should Fix: Enable
--hls.no_multiplex(affects HLS TS only)
- Should Fix: Set
--mpd.segment_templateto 'time' (affects DASH only)
- Should Fix: Enable
--mpd.inline_drmwhen using DRM (affects DASH only)
- Should Fix: Set
--iss.client_manifest_versionto '22' (affects Smooth only)
- Must Fix: Deliver over HTTPS (especially when streaming DRM protected content)
- Should Fix: Enable gzip compression on HLS playlists
- Should Fix: Validate HLS streams with MediaStreamValidator
By default, the length of the segments that Origin generates will differ depending on output format and source type (progressive, dref, remixed or fragmented MP4):
|Source||Progressive, dref or remixed MP4||Fragmented MP4|
|Video||GOP length||GOP length||4s||fragment length||fragment length||4s|
|Audio||2s||2s||4s||fragment length||fragment length||4s|
|Text||2s||2s||4s||fragment length||fragment length||4s|
Instead of relying on these defaults it is better to explicitly specify a value, especially for Live streams with embedded captions, for HLS in general, or when your source is a progressive, dref or remixed MP4.
This option should always be configured as a multiple of the GOP length of your ingest. For HLS, set it (close to) 6 to follow Apple's recommendations. A fractional notation may be used.
By default, the first variant in the Master Playlist is the variant that a HLS player will start playback with. Use --variant_set to list the variant with a video bitrate closest to 2Mbit as the first variant in the Master Playlist, as recommended by Apple. If one of your video tracks has a bitrate of exactly 2Mbit you may use the option like below (once to ensure the variants that contain the 2Mbit video track are listed first, and once more to make sure variants with video tracks that contain other bitrates are listed as well):
It is unlikely that one of your video track has a bitrate of exactly 2Mbit.
Thus, you should adjust the configuration of this option to the characteristics
of your source content (as found in the server manifest (
Should Fix: Configure
--variant_set when offering stereo and multi-channel audio (affects HLS only)¶
If multiple audio 'groups' are part of a HLS stream (e.g., when offering both stereo and multi-channel audio), Origin will pair the audio group with the lowest bitrate with the lowest bitrate video track only. When offering both stereo and multi-channel audio this might not be the desired behavior.
Instead, you may want to make sure that sets of variants are created for all video tracks with stereo audio and all video tracks with multi-channel audio. If so, you can use a configuration like the following:
The default value for --hls.client_manifest_version is '1' and setting it to a value of '4' or higher is recommended because it ensures that your HLS stream will support relatively basic functionality like the use of multiple audio tracks and subtitles, amongst others.
Note that Origin will still signal compatibility with a lower HLS protocol
version for playlists that do not contain any tags that require a higher
protocol version. For example, a Master Playlist for a stream with multiple
audio track will signal a version of '4' if
is set, but a Media Playlist that is referenced by this Master Playlist will
probably still signal a version of '1'. This behavior is compliant with the HLS
By default, Origin muxes video of a variant with the default audio track of the audio group that is associated with the variant. Another default is that even separate audio tracks are delivered in TS segments. The latter is incompatible with the HLS specification, which requires separate audio tracks to be delivered as elementary streams (or in a fMP4 / CMAF container, which is not relevant for Origin's HLS TS output).
Bottom-line is that you need to enable
--hls.no_multiplex if you want to
deliver HLS TS streams that are fully compliant with the HLS specification.
Use --mpd.segment_template to ensure the MPD will always use a 'SegmentTimeline' with timestamps to identify segments (i.e., '$Time$' instead of '$Number$'). Some benefits of using SegmentTimeline based addressing:
- Efficient signaling of all available segment URLs, without the need to time into an estimated segment number
- Direct signaling of any variation in segment durations, which may occur when content is prepared for splicing
- Discontinuities can be signaled, thereby avoiding excessive 404 errors (although this should only be relevant in for VOD when former Live content is used as a source)
Please refer to SegmentTimeline blog to read more about the advantages of this DASH feature
Use --mpd.inline_drm if you add DRM to your content, to ensure that the signaling that a player needs will be added to the MPD directly, instead of the media only (this enables a player to request a license sooner, reducing.
Use --iss.client_manifest_version with value '22' to ensure version 2.2 is used for the Smooth client manifest that Origin generates, which enables compressed timelines that greatly reduce the length and size of said manifest.
In general, it is good practice to deliver your content over HTTPS. However, this becomes a hard requirement when streaming DRM protected content (or modern browsers will refuse playback). Do keep in mind that HTTPS does not have to be enabled on Origin per se and that HTTPS adds a slight bit of overhead (because of the additional handshakes it requires). It may therefore be preferred to enable HTTPS further downstream, on the load balancer in front of your Origins for example (as well as each endpoint further downstream from there).
Setting up a server to support HTTPS delivery is beyond the scope of this document.
In order to create more efficiently sized HLS playlists it is possible and preferable to employ gzip compression, as recommended in the HLS specification. The example below uses an Apache module called deflate to enable this functionality:
# Serve playlists with gzip compression <IfModule deflate_module> AddOutputFilterByType DEFLATE application/vnd.apple.mpegurl Header append Vary Accept-Encoding env=!dont-vary </IfModule>
Apple's MediaStreamValidator may be used to validate the stream, where the Media Stream Validator Tool Results Explained document will outline how to interpret the output.
However, not everything the MediaStreamValidator may output needs attention. When the output would be a warning about 'EXT-X-INDEPENDENT-SEGMENTS' this carefully needs to be compared to what the tvOS specification outlines, in this case the following:
You SHOULD use the EXT-X-INDEPENDENT-SEGMENTS tag in the master playlist. If you do not, then you MUST use the EXT-X-INDEPENDENT-SEGMENTS tag in all video media playlists.
In short, not having EXT-X-INDEPENDENT-SEGMENTS in the master playlist is according to specification. This is in line with the EXT-X-INDEPENDENT-SEGMENTS definition.