HLS

Article Topics: Formats, Sets, Worker

HLS (HTTP Live Streaming) lets your members stream videos with adaptive quality. Instead of playing one fixed file, the player receives a single master playlist that lists every quality available for the video (for example 480p, 720p, and 1080p). The player starts on one of them and then switches up or down automatically as the member's connection allows. The result is faster start times and less buffering, especially for members on slower or unstable connections.

In NATS, HLS is built from the Formats you already use. You choose which formats are included in HLS, and the CMS Worker packages those formats into an HLS stream for each video.

Requirements

Before setting up HLS, make sure your CDN has the following settings. If you are on the MojoHost CDN, ask MojoHost to set them:

Secure Token Type: Highwinds (query string token), using token as the token parameter and expires as the expiration parameter.
HLS Rewrite: must be enabled, with the length parameter set to l (lowercase L).
CORS Headers: must be enabled, so members' video players can load the HLS stream.

For the full list of settings MojoHost needs when creating your CDN, see Setting up Object Store and CDN.

Setting Up HLS

Getting HLS working on your content takes four steps:

Include formats in HLS: In the Formats admin, enable Include in HLS for each format you want available in the stream, and set each one's HLS Master Playlist Order.
Turn on HLS in your Member Areas: In each Member Area's Format Settings, switch on HLS Streaming Preferred.
Process new content: New videos you upload and process will have HLS built for them automatically.
Build HLS for existing content: To add HLS to videos that were processed before you enabled it, click Regenerate HLS on the Content tab of a Set.

Each step is explained in more detail below.

Format Settings

Each format has the following HLS settings, found when adding or editing a format:

Include in HLS - Includes this format as a quality option (a "rendition") in the HLS stream.
HLS Master Playlist Order - The position of this format in the master playlist. The format with the lowest number is listed first and is the one players load initially.
HLS: Allow Transcode Fallback - If a video doesn't already have a file in this format, allow the CMS Worker to encode one from the source video for HLS. When disabled, this format is left out of that video's HLS stream.
HLS BANDWIDTH (bits/sec) - Optional. The peak bandwidth listed for this format in the master playlist. Leave blank to have NATS calculate it from the file size and duration.
HLS AVERAGE-BANDWIDTH (bits/sec) - Optional. The average bandwidth listed in the master playlist. Leave blank to leave it out.
HLS CODECS string - Optional. The codecs listed in the master playlist, for example avc1.640028,mp4a.40.2. Leave blank to leave it out.

On the Formats page, each format shows whether it is included in HLS and its HLS Master Playlist Order.

Choosing a Master Playlist Order

We recommend ordering your formats from lowest quality to highest quality: your smallest format gets the lowest number, and your largest format gets the highest number. This is how most major streaming services work.

Starting on the lowest quality means a video begins playing almost instantly on any connection. Within a few seconds, the player sees how much bandwidth is available and switches to a higher quality. If you start on the highest quality instead, members on slower connections may see a slow or stalled start.

For example:

Format

HLS Master Playlist Order

480p

720p

1080p

Please Note: Only the relative order matters. Video players never see the numbers themselves, only the order of the formats in the playlist. Starting at 0 or 1, or leaving gaps (10, 20, 30), all work the same way. Leaving gaps can make it easier to add a new format between existing ones later.

Member Area Format Settings

HLS is turned on per Member Area. Open a Member Area and find its Format Settings section.

Switch on HLS Streaming Preferred to enable HLS for that Member Area. The setting saves as soon as you switch it. Below the toggle, NATS lists the formats that are currently included in HLS.

When HLS Streaming Preferred is on:

Members watch the HLS version of a video whenever one is available, and playback adjusts to their connection.
If a video doesn't have HLS yet, it streams using your regular formats, the same as before.
The HLS stream overrides each format's own Stream setting in the selected Member Area.
Download settings are not affected. Members can still download the formats you allow.

Building HLS for Your Content

New Content

Once at least one format has Include in HLS enabled, HLS is built automatically when you process new content. When you add a video to a set, the import table on the set's Content tab shows which formats will be included in HLS once it's processed.

A Single Video

To build or rebuild HLS for one video, open the set's Content tab and use the video's actions menu (top right of the video) to select Generate HLS, or Regenerate HLS if the video already has one.

This rebuilds HLS for the entire video, including every format that's included in HLS, and replaces the video's current HLS stream.

You can also rebuild a single format for a video from that format's row. Only that format is rebuilt, and the video's master playlist is refreshed afterward.

Checking a Video's HLS Status

On a set's Content tab, each video format shows an HLS status:

N/A - This format isn't included in HLS.
Missing - This format is included in HLS, but it hasn't been built for this video yet.
Included - This format is part of the video's HLS stream.

The video's source file never shows an HLS status, because it isn't a rendition of its own. To preview a video's HLS stream as members will see it, click the play button on the video's thumbnail.

Best Practices

Set your playlist order before you regenerate. The order is saved into each video's playlist when its HLS is built. Decide on your formats and their order first, then run Regenerate HLS.
When you add a new format to HLS, check the order of all your formats. For example, if you already have 480p (1), 720p (2), and 1080p (3) and add a 4k format, give 4k an order of 4. If you add a 540p format instead, it belongs between 480p and 720p, so you'll need to renumber the formats above it (or use gapped numbers from the start).
Turn on HLS Streaming Preferred only after your formats are set up. Videos without HLS fall back to regular streaming, so nothing breaks in the meantime, but members won't get adaptive playback until HLS is built.

Formats Member Areas and Tours CMS Worker

Last updated 4 days ago

Was this helpful?