Use Video.js with Mux

Learn what video.js kit is and how to use it in your application.

In this guide:

1
Introduction to video.js kit

1 Introduction to video.js kit

Find out what video.js kit is and the features it includes

2
Integrate video.js kit

2 Integrate video.js kit

Learn how to add and use video.js kit in your application

3
Set configuration options

3 Set configuration options

Learn how to enable options such as timeline hover previews or enable Mux Data

4
Using signed URLs

4 Using signed URLs

Learn how to playback Mux videos with signed playback policies

5
Release notes

5 Release notes

Check the latest release and change log to see what's new

1Introduction to video.js kit

Video.js kit is a project built on Video.js with additional Mux specific functionality built in. This includes support for:

Enabling timeline hover previews
Mux Data integration
playback_id helper (we'll figure out the full playback URL for you)

2Integrate video.js kit

Video.js kit is hosted on npm. To install it, navigate to your project and run:


// npm
npm install @mux/videojs-kit

// yarn
yarn add @mux/videojs-kit

Now import the JavaScript and CSS in your application like this:


// include the video.js kit JavaScript and CSS
import videojs from '@mux/videojs-kit';
import '@mux/videojs-kit/dist/index.css';

If you're not using a package manager such as npm, there are hosted versions provided by unpkg.com available too. Use the hosted versions by including this in your HTML page:


// script
<script src="https://unpkg.com/@mux/videojs-kit@latest/dist/index.js"></script>
// CSS
<link rel="stylesheet" href="https://unpkg.com/@mux/videojs-kit@latest/dist/index.css">

Then, on your page include a <video> element where you want to add your player.


<video 
  id="my-player" 
  class="video-js vjs-16-9" 
  controls 
  preload="auto" 
  width="100%"
  data-setup='{}'
>
  <source src="{PLAYBACK_ID}" type="video/mux" />
</video>

Replace the {PLAYBACK_ID} with the playback_id of your video from Mux.

Source Code

Video.js kit is open source and can be found on GitHub here: https://github.com/muxinc/videojs-mux-kit

3Set configuration options

There are some built in additional features which can be set when you initialize video.js kit.

Include a timeline hover preview

You can enable a timeline hover preview by including timelineHoverPreviews: true in the configuration options when you create your player.


<video id="my-player" class="video-js vjs-16-9" controls preload="auto" width="100%"
  data-setup='{
    "timelineHoverPreviews": true
  }'
>
  <source src="{PLAYBACK_ID}" type="video/mux" />
</video>

Enable Mux Data

You can enable Mux Data by including the following options when you create your player.


<video id="my-player" class="video-js vjs-16-9" controls preload="auto" width="100%"
  data-setup='{
    "plugins": {
      "mux": {
        "debug": true,
        "data":{
          "env_key": "ENV_KEY",
          "video_title": "Example Title"
        }
      }
    }
  }'
>
  <source src="{PLAYBACK_ID}" type="video/mux" />
</video>

Get your ENV_KEY from the Mux environments dashboard.

Env Key is different than your API token

ENV_KEY is a client-side key used for Mux Data monitoring. These are not to be confused with API tokens which are created in the admin settings dashboard and meant to access the Mux API from a trusted server.

The videojs-mux data plugin is included by default, so you don't need to include this in addition to video.js kit. To link your data integration to your account, you should replace the ENV_KEY in the configuration with an appropriate Mux environment key, as well as set metadata.

Set the video source

You can set the video source using the playback_id from your video in Mux, and we'll figure out the fully formed playback URL automatically.

When you set the source for video.js, make sure you set the type as video/mux and the src as your playback_id.


<video id="my-player" class="video-js vjs-16-9" controls preload="auto" width="100%">
  <source src="{PLAYBACK_ID}" type="video/mux" />
</video>

Initialize with JavaScript

The options above can also be initialized with JavaScript. Here's an example showing how you could enable all options with JavaScript.


<video id="my-player" class="video-js vjs-16-9" controls preload="auto" width="100%">
</video>

<script>
const player = videojs('my-player', {
  timelineHoverPreviews: true,
  plugins: {
    mux: {
      debug: false,
      data: {
        env_key: 'ENV_KEY',
        video_title: 'Example Title'
      }
    }
  }
});

player.src({
  src: "{PLAYBACK_ID}",
  type: "video/mux",
});
</script>

4Using signed URLs

Playback of Mux videos with a signed playback policy is now supported from v0.3.0 onward.

Before continuing, ensure you have followed the secure video playback guide, and are comfortable generating JSON Web Tokens (JWTs) to use with Mux.

Playback a video with a signed URL

Use the playback_id from your video in Mux and then append your video JWT token like this {PLAYBACK_ID}?token={YOUR_VIDEO_JWT} as your player source. When you set the source for video.js, make sure you set the type as video/mux.

In HTML:


<video id="my-player" class="video-js vjs-16-9" controls preload="auto" width="100%" data-setup="{}">
  <source src="{PLAYBACK_ID}?token={JWT_VIDEO_TOKEN}" type="video/mux" />
</video>

Or, achieve the same result using JavaScript:


<video id="my-player" class="video-js vjs-16-9" controls preload="auto" width="100%">
</video>

<script>
const player = videojs('my-player', {
  plugins: {
    mux: {
      debug: false,
      data: {
        env_key: 'ENV_KEY',
        video_title: 'Example Title'
      }
    }
  }
});

player.src({
  src: `{PLAYBACK_ID}?token={JWT_VIDEO_TOKEN}`,
  type: `video/mux`,
});

</script>

Enable a timeline hover preview from a signed URL

Mux requires a separate JWT token to access the timeline hover preview storyboard URL, which isn't something that Video.js Kit is able to automatically figure out, unlike with public playback URLs. Instead, we require the fully formed URL to be passed to the player.

To setup timeline hover previews with a signed URL, first make sure that timelineHoverPreviews is set to false or not set at all, which stops the automatic URL generation taking place. Then, either set the timelineHoverPreviewsUrl in the player configuration like this:


<video id="my-player" 
  class="video-js vjs-16-9" 
  controls 
  preload="auto" 
  width="100%" 
  data-setup='{
    "timelineHoverPreviewsUrl": "https://image.mux.com/{PLAYBACK_ID}/storyboard.vtt?TOKEN={JWT_STORYBOARD_TOKEN}"
  }'>
  <source src="{PLAYBACK_ID}?token={JWT_VIDEO_TOKEN}" type="video/mux" />
</video>

Or, achieve the same result using JavaScript and use the player.timelineHoverPreviews() function:


<video id="my-player" class="video-js vjs-16-9" controls preload="auto" width="100%">
</video>

<script>
const player = videojs('my-player', {
  plugins: {
    mux: {
      debug: false,
      data: {
        env_key: 'ENV_KEY',
        video_title: 'Example Title'
      }
    }
  }
});

player.src({
  src: `{PLAYBACK_ID}?token={JWT_VIDEO_TOKEN}`,
  type: `video/mux`,
});

player.timelineHoverPreviews({
  enabled: true, 
  src: "https://image.mux.com/{PLAYBACK_ID}/storyboard.vtt?TOKEN={JWT_STORYBOARD_TOKEN}"
});

</script>

player.timelineHoverPreviews is a function that can be used to set, update or remove timeline hover previews from a player, and takes a single object parameter.

The object has two properties, src which should be a string pointing to the VTT file which contains the timeline hover previews information, and enabled which can be either true for the player to attempt to use the provided source and setup the timeline hover previews, or false which will disable any timeline hover previews which are currently configured on the player.

Remove timeline hover previews

To switch off timeline hover previews, you can use the following API;


player.timelineHoverPreviews({
  enabled: false, 
});

5Release notes

Current release: v0.3.0

Adds support for Mux signed playback policies
Fix an issue with live stream playback not correctly updating the player UI to live mode
Fix an issue where changing sources in an existing player caused an error

Older releases

Check the GitHub releases page for full version history.

Docs