Creating a User Friendly Video Player

  1. Documentation
  2. Tutorials
  3. Creating a User Friendly Video Player
Warning: Autoplay is never guaranteed to work for every user or every browser.

Adding video content to your website is an excellent way to engage with your users. This article will guide you in embedding videos on a web page using either HTML, Javascript and/or the imgix video library (@imgix/ix-player)

Using ix-player

The ix-player library is easy to configure, install and has a lot of documentation on styling the video player depending on your needs. As a result, ix-player is the recommended video playback solution for HLS files.

The ix-player player can be used in any React, Vue or Angular application.

You can also use ix-player in a static HTML page by using basic markup. Here is an example of ix-player usage in an HTML site:

<!-- Note: type 'module' here is important -->
<script defer type="module" src="https://static.imgix.net/ix-player/@latest/dist/ix-player.mjs"></script>
<ix-player gif-preview type="hls" src="https://assets.imgix.video/videos/girl-reading-book-in-library.mp4?ixembed=docs&fm=hls"></ix-player>

Click here to modify this in a CodeSandbox.

ix-player has several configurable attributes. To learn more, check out the ix-player documentation.

Load to Encode

When a video has been requested that has not yet been processed, the request to the video URL should return a 404 or 423 status code while it is processing. If the video is not found in our systems, we will return a 404. Otherwise, we will return a 423 as the video request is queued for processing.

Once the video has finished processing, subsequent requests should load the video as usual.

The imgix video player will periodically retry requests for a video on a 423 status code until the video loads successfully.

Note: If a video is requested but not in the allowed directory for processing, it will not be processed.

Using the <video> Element

If you prefer to manually code your video or create your own custom player, you can use the <video> HTML element, like the <img> element, is used to embed a media player that supports video playback onto a web page. The <video> element has several configurable attributes to control how a video is displayed.

Here is a basic code example of an embedded video web player:

<video
  controls
  style="width: 100%; max-width: 1500px;"
>
  <source src="https://assets.imgix.video/videos/girl-reading-book-in-library.mp4?fm=mp4" type="video/mp4">
   Your browser does not support embedded videos!
</video>

This will create the video below:

The controls attribute is used to show video controls to the user. If the user's browser does not support video, the text Your browser does not support embedded videos! will be displayed instead.

There are several other attributes that can be used to configure the <video> element. See the MDN docs for more information on video attributes.

Playing Videos With HLS

While it's possible to use formats such as mp4 or avi to play videos, it is considered best practice to stream videos using the HLS format.

To do this in your web application, you can use imgix's Video API to easily transform your files into HLS format. You can combine that with third-party library to stream HLS files using <video> element. Here is an example using hls.js:

<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="my-player" controls="controls" style="width: 100%; max-width: 1500px;" crossorigin="anonymous"/>
<script>
  let video = document.querySelector("#my-player");
  let src = "https://assets.imgix.video/videos/girl-reading-book-in-library.mp4?fm=hls";

  if (video.canPlayType("application/vnd.apple.mpegurl")) {
    video.src = src;
  } else if (Hls.isSupported()) {
    let hls = new Hls();

    hls.loadSource(src)
    hls.attachMedia(video);
  } else {
    console.error("This is a legacy browser that doesn't support Media Source Extensions");
  }
  
</script>

This will create the video player below:

Click here to modify this in a Codepen.

Here, we're detecting whether or not the user's browser supports HLS playback using the third-party library. If it does, we'll load it - if not, we'll log an error. We can even use a fallback method of serving a different video file in the code.

Setting up Autoplay

Automatically playing videos can be a great way to get users to interact with your content. At the same time, it can be detrimental to the user experience to play videos automatically each time they open up your app or webpage.

This tutorial will help you understand how autoplay works along with understanding use cases for enabling autoplay.

Browser compabiltity

All browser vendors (such as Chrome and Safari) have different policies and algorithms which determine whether or a not a video will be allowed automatically play. The requirements varies between browsers, but these are the general conditions that will give your videos a better chance of being autoplayed:

  • Your video element is muted with the muted attribute
  • The user has clicked anywhere on the page
  • (Chrome - desktop) The user's Media Engagement Index scores over a certain threshold
  • (Chrome - mobile) The user has added the site to their home screen
  • (Safari) The device is not in power-saving mode

If autoplay is not allowed, a user must click the video to initiate playback.

Enabling Autoplay

There are two methods of enabling autoplay for video.

Using the autoplay attribute

The autoplay attribute is the most common and easiest way to enable autoplay for a video. Here's a full HTML example that you can copy and paste, which includes other attributes for styling the video. The video may or may not autoplay depending on your browser:

<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>

<video
  id="my-autoplay-player"
  autoplay
  controls
  loop="loop"
  muted="muted"
  style="width: 100%; max-width: 1500px;"
  crossorigin="anonymous"
/>

<script>
  const video = document.querySelector('#my-autoplay-player');
  const src = 'https://assets.imgix.video/videos/girl-reading-book-in-library.mp4?fm=hls';
  if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = src;
  } else if (Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource(src)
    hls.attachMedia(video);
  } else {
    console.error("This is a legacy browser that doesn't support Media Source Extensions");
  }
</script>

This will create the video player below:

Clck here to modify this in a Codepen.

While this is the easiest method for enabling autoplay, it's not the best. The autoplay attribute only tells the browser what the video should do, but it does not define or log any fallback behavior for a video element.

This is not a problem most of the time since it will fallback to requiring input from a user to start plyaback. However, in cases such as a background video, you would instead want to define a fallback behavior that would not require any user input, such as showing a background image instead. To do this, you can use Javascript to initiate autoplay instead of the autoplay attribute.

Using video.play()

If Javascript is enabled, use the video.play() method to play the video instead of using a video attribute.

Here's a code example showing how to use video.play():

<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="my-player" controls="controls" style="width: 100%; max-width: 1500px;" crossorigin="anonymous"/>
<script>
  let video = document.querySelector("#my-player");
  let src = "https://assets.imgix.video/videos/girl-reading-book-in-library.mp4?fm=hls";

  if (video.canPlayType("application/vnd.apple.mpegurl")) {
    video.src = src;
  } else if (Hls.isSupported()) {
    let hls = new Hls();

    hls.loadSource(src)
    hls.attachMedia(video);
  } else {
    console.error("This is a legacy browser that doesn't support Media Source Extensions");
  }
  video.play().then(function () {
    // autoplay was successful!
  }).catch(function (error) {
    // do something if you want to handle or track this error});
</script>

This will create the video player below:

Click here to modify this in a Codepen.

Assuming the intention is to create a background video, the code above will automatically play a video if autoplay is allowed. If is not, we can use the .catch() function to log an autoplay error or to swap out the <video> element for an <image> element instead.

When to use autoplay

Autoplay's primary use case is to immediately grab a users attention on a web page. It can also save the user a click as long as the content is relevant to the user.

However, autoplay can also create a negative experience for users and have a negative effect on user engagement by creating too much website noise.

With that in mind, autoplay should be used in the following scenarios:

  • To create a background video as part of your design composition
  • To enrich the user experience by automatically playing a video they were guaranteed to click
  • To play a video that is immediately visible to the user when the page loads
  • To play a video that is critical for the user to watch

When using autoplay, you should avoid the following:

  • You should not autoplay videos below the fold
  • You should not autoplay videos that the user cannot see
  • You should not autoplay multiple videos at a time
Tutorials
Related Guides