Improve video streaming using HLS with Mux and Contentful

How to use HLS through a Mux Contentful combination
June 15, 2020


Mux is an API-first video platform for streaming and analytics. Mux handles hosting, encoding and delivery to ensure that every viewer gets the best streaming experience.

The Mux app lets you upload your video files via the Contentful web app and deliver videos with HTTP Live Streaming (HLS). That means you’re one app away from giving your viewers the best video experience, no matter what device they’re on.

You might have used HTML5 video before with mp4 files. That looks something like this with a <video> element, the same way you would put an “src” attribute on an “<img>” element.

This works under some conditions, but it doesn’t always deliver a smooth streaming experience to your end users. In this approach, the video is only available in a single resolution—and it’s probably made with mp4 in HD with a 1080p resolution because you want a high-quality video. If some of your users are on normal network speeds, they will not be able to easily watch the video. It’ll be slow to start and their device will not be able to download the video fast enough to continuously watch.

Adaptive streaming fixes this problem by getting the right resolution for each device and connection — a high-resolution ultra HD version of the video if their connection can handle it. Otherwise, they get a slightly lower resolution version of the video. The same goes for different devices. It doesn’t make sense to deliver the same size video to a 50-inch television on a fast WiFi connection and to a smartphone screen on a 3G connection. Different networks and devices have different requirements for delivering the best video experience. 

HTTP Live Streaming, or HLS, is a form of adaptive streaming that ensures high-quality delivery regardless of device or connection.

HTTP Live Streaming (HLS)

Imagine you have a ten-minute video saved in a large mp4 file. With HLS, that video is processed (“transcoded”) into several small files (“segments”). Depending on the video source, Mux will create up to five versions (“renditions”) of this video of various quality levels (“resolutions”).

Segment lengths can vary, but let’s say we are delivering six-second segments. Your 10-minute video will be broken up into 100 small video files for each rendition that gets created. For example:

  • 1920x1080 rendition: 100 video files that are each six seconds

  • 1280x720 rendition: 100 video files that are each six seconds

  • 960x960 rendition: 100 video files that are each six seconds

  • 640x360 rendition: 100 video files that are each six seconds

  • 480x270 rendition: 100 video files that are each six seconds

To deliver your 10-minute video optimally over HLS, Mux will create 600 small video files that are six seconds each and make them available via multiple CDNs globally to give your end users the fastest video delivery experience.


The HLS video is accessed through an URL that ends with “m3u8.” With Mux that looks like this:

Drop that URL into a player that understands HLS, and the player will handle the logic of picking the best rendition based on the player size and client network.

On the web, HLS is supported natively by Safari and Edge, but other browsers require a little javascript help with a library like HLS.js or a fully featured player like Video.js, which supports HLS out of the box.

For playback on iOS, HLS support is baked right into iOS’s native video player, AVPlayer. Initialize it the same way you would with an URL to a mp4 file.

On Android, HLS support is also supported directly by ExoPlayer, which is developed and supported by Google. 

Adaptive Bitrate Streaming

When a player gets initialized with an HLS video it will perform what’s called Adaptive Bitrate Streaming. In the background, the player constantly monitors how much bandwidth is available and makes tradeoffs in real time to give your users the highest possible video quality that it can, while minimizing the amount of rebuffering.If you want to learn more about HLS video streaming, check out

Using Mux and Contentful

The Mux app lets you upload your video files via the Contentful web app and deliver videos with HTTP Live Streaming (HLS). 

Mux also has some fun features to help you get the most out of your videos. With the playbackId for your Mux asset, you can create thumbnails and animated gifs on the fly by passing in a timestamp and other query parameters. With these APIs you can build interactive experiences. Show a gif preview when your user hovers over a video or grab a thumbnail image that you can use as poster images on your <video> element.

How to add Mux HLS API to Contentful web app

Like Contentful, Mux is extensible. It doesn’t make decisions about the look and feel of the web app. You get to bring your own player to the party and take control of the user experience while Mux seamlessly handles the storage and delivery. 

What Mux HLS API video looks like in Contentful

We love video at Mux, and we love hearing about all the ways you are using video in your applications and sites. Please tell us about it! 

Start building

Use your favorite tech stack, language, and framework of your choice.

About the author

Don't miss the latest

Get updates in your inbox
Discover how to build better digital experiences with Contentful.
add-circle arrow-right remove style-two-pin-marker subtract-circle remove