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 and install and can be stylized to your needs. As a result, ix-player is the recommended video playback solution for the Video API. It also supports both Long-Form Video and Short-Form Video.

You can use the ix-player player in any React, Vue, or Angular application by installing the npm library. Using basic markup, you can use ix-player on a static HTML page. 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 Long-Form Video has been requested but has not yet been transcoded, we will return a 423 status code to indicate that the video is queued for transcoding. If the video is not found in our systems, we will return a 404. The video will not be available for playback through Long-Form Video during this time. However, requesting the video through the imgix.net subdomain with no parameters will still be available as a passthrough.

Once the video has finished processing, subsequent requests to Long-Form Video 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.

First-time requests to Short-Form Video may be delayed as the video is being processed. However, it will always return a 200 success status code along with the video, assuming it is under 5 minutes and exists at the Source.

Using the `<video>` Element

If you prefer to code your video or create your custom player manually, you can use the <video> HTML element, like the <img> element, which 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 shows the user video controls. 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

The primary video format of Long-Form Video is the HLS streaming format. This format is not supported natively by all modern browsers and, in many cases, will require an external library or video player to manage playback.

To play HLS videos in your web application, you can easily use Imgix’s Long-Form Video API to transform your files into HLS format. You can combine that with a third-party library to stream HLS files using the <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 hereto 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 and use cases for enabling autoplay.

Browser compatibility

All browser vendors (such as Chrome and Safari) have different policies and algorithms that determine whether or not a video will be allowed to play automatically. The requirements vary 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 you can copy and paste, including 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>
</video>

This will create the video player below:

Click 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 fall back to requiring input from a user to start playback. However, in cases such as a background video, you would instead want to define a fallback behavior that would not require user input, such as showing a background image. 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 hereto 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 immediately grabbing a user’s 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 user experience and hurt 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

How to Add an Asset to the Asset Manager Managing Brand Assets from PDFs

Creating a User Friendly Video Player

Using ix-player

Load to Encode

Using the <video> Element

Playing Videos With HLS

Setting up Autoplay

Browser compatibility

Enabling Autoplay

Using the autoplay attribute

Using `video.play()`

When to use autoplay

Using `ix-player`

Using the `<video>` Element

Using the `autoplay` attribute