Unified Origin - General Recommendations¶
Table of Contents
- Recommended: Specify a --hls.minimum_fragment_length (affects HLS only)
- Recommended: Use --variant_set to list ~2Mbit variant first (affects HLS only)
- Recommended: Set --hls.client_manifest_version to '4' (affects HLS TS only)
- Recommended: Enable --hls.no_multiplex (affects HLS TS only)
- Recommended: Set --mpd.segment_template to 'time' (affects DASH only)
- Recommended: Enable --mpd.inline_drm when using DRM (affects DASH only)
- Recommended: Do not set --mpd.minimum_fragment_length (affects DASH only)
- Recommended: Set --iss.client_manifest_version to '22' (affects Smooth only)
- Recommended: Specify a --fixed_gop
- Required: Deliver over HTTPS (especially when streaming DRM protected content)
- Recommended: Enable gzip compression on HLS playlists
- Required: Content Delivery Network (CDN)
- Recommended: Validate HLS streams with MediaStreamValidator
Whereas Origin dynamically adjusts the length of the media segments that it
generates for DASH and Smooth based on the ingest, Origin relies on a set target
for the length of HLS media segments. By default this target is twice the value
--fixed_gop, while the default value for
--fixed_gop is '2' (making
the default target for HLS media segments '4').
As explained above it is recommended to explicitly specify a
addition, an explicit --[iss|hls|hds|mpd].minimum_fragment_length
should be specified if you want your HLS media segments to not be twice as long
as the GOP length of your ingest, but a different multiple (to make the media
segments equal to the GOP length or make them three times as long instead, for
This option should always be configured as a multiple of the GOP length of your ingest. 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):
--variant_set='systemBitrate==2000000 || type!="video"' --variant_set='systemBitrate!=2000000 || type!="video"'
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 (
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.
Do not use --[iss|hls|hds|mpd].minimum_fragment_length to specify a segment length for DASH output. The default that follows the GOP length of the source content is recommended.
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.
As detailed in the Content Preparation section of these Best Practices, you should configure your encoder to output video with a fixed GOP, which is something that all modern encoders support. Ideally, your chosen GOP length fits an exact multiple of audio frames (each AAC frame is 1024 audio samples long).
--fixed_gop option allows you to inform Origin about the GOP
length that you have configured your encoder to output (the default value is
- For HLS, Origin will aim to output segments of twice this length (you can override this behavior using --[iss|hls|hds|mpd].minimum_fragment_length, which we also recommend to do).
- For HLS, Origin will use the specified fixed GOP length as the interval for the I-frame playlists it generates
- For DASH, setting this option enables a basic version of trickplay, as explained in How to add trick play to DASH.
When specifying this option a fractional notation may be used.
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>
Using one or more CDNs is crucial when delivering streams at scale, especially when the audience is distributed across regions. The CDN will act as a reverse proxy cache, caching HTTP GET requests: initial hits will reach Origin, but any subsequent requests for the same content will hit the CDN, thereby offloading Origin considerably and making sure the content is as close to customers as possible.
Using multiple CDNs, failures on the CDN can be avoided, and for optimum performance it may even be worthwhile to choose the CDN to route a request through on a per-request basis, making sure the most performant route is taken. Specific third-party tooling is available to support such use cases.
Origin does not support push based transfer of content to CDNs. In general, we do not recommended this approach either, as it may be unclear what content needs to be pushed and your content's footprint on the CDN might become very large and costly, especially for VOD use cases. However, if you do want to take this approach you can do so for VOD using Unified Packager instead of Origin.
Although several CDNs offer builtin shield caching functionality, it is recommended to add on to your setup anyways, to protect Origin against thundering herd: Shield caching and CDN.
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
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 inline with the EXT-X-INDEPENDENT-SEGMENTS