Advanced usage of Mux Player

Listen for events

Mux Player emits all of events available on the HTML5 video element.

For example, if you want to keep track of how much of a particular video a user has watched, you probably want to use the timeupdate event like this:

HTML element

import '@mux/mux-player';

const muxPlayer = document.querySelector("mux-player"); 

muxPlayer.addEventListener("timeupdate", function (event) {
console.log('time update!', event);
});

In React, the events are camel-cased and prefixed with on\*. For example timeupdate becomes onTimeUpdate:

React

copy
function saveWatchProgress(event) {
  /* event */
}

<MuxPlayer onTimeUpdate={saveWatchProgress} />; 

Using with signed urls

If you followed the guide for Secure video playback then you are using signed URLs and a few extra steps are required to use Mux Player (or any player for that matter).

First off, you should already be creating JSON Web Tokens (JWTs) on your server. If you're not doing that already, head over to that guide and do that part first.

Note that JWTs are granular, so a unique token is used for each resource:

• PlaybackID is used to get the actual video.
• Thumbnail is used to get a still image from the video. Mux Player uses it for a poster image
• Storyboard is used to get a storyboard representation of the video. Mux Player uses this for the timeline hover previews feature. This is only relevant for on-demand stream types (live and ll-live stream types don't support timeline hover previews).

Each JWT will look something like this below. These examples were created with playback ID qIJBqaJPkhNXiHbed8j2jyx02tQQWBI5fL6WkIQYL63w.

Playback token:

copy
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFkamYzb2JpYURUcEF0QVlpS3NCMkpvRlkwMXBpbEJMTHdYcUQzaHpJYURJIn0.eyJleHAiOjE5NjE2NDY0MDMsImF1ZCI6InYiLCJzdWIiOiJxSUpCcWFKUGtoTlhpSGJlZDhqMmp5eDAydFFRV0JJNWZMNldrSVFZTDYzdyJ9.mukZou10_iwaqPeHVFbXwTZShMK1D8kWpFAFOl6bwuIMB7hx0bAqscZxj5FwrIB8dzB6s_9YtJEEVXcR6ezxOhOc_y2ij1XM4YQYCuGH-elJc3rapHbahv2K7L_asz9Bdu1Ld6i6Ux7keNpEuGSYCDmsPmvdII7_XAPmzU01ZTvaXqCgzCY2PO7xz6z3hu1HOww2eL41TSif_Zu0okNZlhfHE9U-nyr4OVpuS9Q-rTtVvfE2ILSd9Ezt02AuOK-JkBCeR3Xf-UrbXB33ZFHLJrYVA-B516Iym0CGRfVssZsAn80_PNaxS_3M_OmVzyaDJ4zudb-YjGcaNl0yf96h6w 

Thumbnail token:

copy
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFkamYzb2JpYURUcEF0QVlpS3NCMkpvRlkwMXBpbEJMTHdYcUQzaHpJYURJIn0.eyJleHAiOjE5NjE2NTkzMzAsImF1ZCI6InQiLCJzdWIiOiJxSUpCcWFKUGtoTlhpSGJlZDhqMmp5eDAydFFRV0JJNWZMNldrSVFZTDYzdyJ9.zQ0tDimpgu7nsT9Tb7GBgitMpYSbLBodwS-fSc7U0K0WT-giCUgxXXSqXquwpHMjEEfSuCsCU3Y1gq2P7WaJUBGTOTLKT5GOwyhjeoJzTPXEQqW7T-tpKXhjEDVwy_H2UPNVdA9ZALos5R9rrWyiTQA53sxT56FWy-IhvaISpiB16nzankRKCAo98kh6lloexE8p3lXnUhLwIK8Hqco4hRmHSmWqUndnJrbq0_kag0o8R0drffSMj6CvKas8_f6v3MtHXDhW0JkJ1TZKwICt7W-jrSyMfhgAb9wltBCUXdNHYvQTXkFfFnsI1R-BuZodQL2zN3pVBqzuhQA0UPADMw 

Storyboard token (only needed for on-demand):

copy
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFkamYzb2JpYURUcEF0QVlpS3NCMkpvRlkwMXBpbEJMTHdYcUQzaHpJYURJIn0.eyJleHAiOjE5NjE2NTkzMTQsImF1ZCI6InMiLCJzdWIiOiJxSUpCcWFKUGtoTlhpSGJlZDhqMmp5eDAydFFRV0JJNWZMNldrSVFZTDYzdyJ9.QxvtM-FBakS8IPl_mZloBKLKyHRU8md7IbSifAYbAVHrLwUre3-CXlOcsd6sKi0hVen_DnSqQeuuFTYF6o2TeS31gnBsf5U4W7JDpOjxAepj4ODM6bpPJBu6XDpZmMTduuwVrIXP9pQWSwiHSQ93hk6RR17YrPgGz6sCXIL5gt0re_WqkSEazwYEscu9eByMN3F_sM7W830C7Wzeatb1TMeEf6wQhbpKABLB33VM0FOuM5ojjI9DWmDhJksfFVrOxaZtoju4hjiWQtNPVBCFP28J9LHNLA7brRXvDGaIUxHG5-vrcVuImlghdWgPyrAOb0lWYSiklYx2ObHhNWJK1g 

When you have generated the 3 tokens, pass them into Mux Player:

Example with the HTML element:

copy
<mux-player
  playback-id="qIJBqaJPkhNXiHbed8j2jyx02tQQWBI5fL6WkIQYL63w"
  playback-token="eyJhbGciOiJSUzI1NiI..."
  thumbnail-token="eyJhbGciOiJSUzI1N..."
  storyboard-token="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsI..."
  metadata-video-id="video-id-54321"
  metadata-video-title="Test video title"
  metadata-viewer-user-id="user-007"
  stream-type="on-demand"
></mux-player> 

If you are using JavaScript and Mux Player, you can use the tokens property too:

copy
const muxPlayer = document.querySelector("mux-player");
muxPlayer.tokens = {
  playback: "eyJhbGciOiJSUzI1NiI...",
  thumbnail: "eyJhbGciOiJSUzI1N...",
  storyboard: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsI...",
}; 

If you're using the React version of Mux Player, use the tokens prop:

copy
<MuxPlayer
  playbackId="qIJBqaJPkhNXiHbed8j2jyx02tQQWBI5fL6WkIQYL63w"
  metadata={{
    video_id: "video-id-54321",
    video_title: "Test video title",
    viewer_user_id: "user-id-007",
  }}
  tokens={{
    playback: "eyJhbGciOiJSUzI1NiI...",
    thumbnail: "eyJhbGciOiJSUzI1N...",
    storyboard: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsI...",
  }}
  streamType="on-demand"
/> 

Mux Player send errors to Mux Data when tokens are incorrect. The most common error cases with signed URLs that Mux Player detects are:

• Playback ID mismatch
• Expired token
• Malformatted token

These errors will be logged to the browser console and sent to your Mux Data dashboard.

Preloading assets

By default preload will behave similar to the HTML5 <video> element.

Use the preload= attribute with values of "none", "metadata" or "auto".

The default is "auto", which will start loading the video as soon as possible and give the user the best experience with the shortest startup time.

If you want to preserve bandwidth (& delivery cost) set preload="none" (load nothing until the user tries to play) or preload="metadata" (load the minimum amount of data for the media to get basic information like its duration).

The tradeoff with using preload="metadata" or preload="none" is that when the user plays the video they will experience a slower startup time because the video has to load before playback can start. You'll see the slower startup time reflected in your Mux Data dashboard and this will negatively impact the Overall Viewer Experience metric.

Use custom video domains

By default, all Mux Video assets will be hosted on mux.com. This includes things like posters, storyboards, and media sources.

Custom Domains, is a feature which allows you to stream these assets from a domain of your choice.

Once you have your custom domain set up, provide it via the custom-domain attribute or customDomain property. If your custom domain is media.example.com then internally Mux Player will take that value and expand it to image.media.example.com for images and stream.media.example.com for video.

Example with the HTML element:

copy
<mux-player
  playback-id="qIJBqaJPkhNXiHbed8j2jyx02tQQWBI5fL6WkIQYL63w"
  custom-domain="media.example.com"
  stream-type="on-demand"
></mux-player> 

If you are using JavaScript and Mux Player, you can use the customDomain property too:

copy
const muxPlayer = document.querySelector("mux-player");
muxPlayer.customDomain = "media.example.com"; 

If you're using the React version of Mux Player, use the customDomain prop:

copy
<MuxPlayer
  playbackId="qIJBqaJPkhNXiHbed8j2jyx02tQQWBI5fL6WkIQYL63w"
  streamType="on-demand"
  customDomain="media.example.com"
/> 

Change playback engine

Mux Player will automatically handle Adaptive Bitrate Streaming with your Mux Asset. For a beginner's guide on how this works, howvideo.works is an informational site that explains the basic concepts. Under the hood, Mux Player uses HLS.js and Mux Player will pick the optimal HLS.js configuration based on the provided stream-type.

On iOS, iPadOS, and MacOS, Mux Player will use Apple's native HLS streaming engine. On Android, Mux Player will use HLS.js.

It is not recommended, but if you have a good reason to control whether Mux Player uses HLS.js (MSE, Media Source Extension) or native HLS playback you can with the prefer-playback attribute (in React preferPlayback). Values can be "mse" or "native". When a value is provided for prefer-playback, Mux Player will use that playback strategy if available.

Note that setting the prefer-playback attribute should be done with caution. If you are setting this, make sure you thoroughly test playback on the various operating systems and browsers that Mux Player will be running in. Also, keep an eye on Mux Data to verify that your playback metrics are on track.

Re-using player instances

Mux Player instances can be re-used by re-setting the playback-id.

In React, this is done by changing the playbackId prop to a new value.

In the web component, this can be done by either calling setAttribute with a new value for the playback-id attribute or by assigning the playbackId property. Both are equally valid ways of interacting with the <mux-player> element instance.

copy
const muxPlayer = document.querySelector('mux-player');

// using setAttribute
muxPlayer.setAttribute('playback-id', 'new-playback-id-xxx');
// using the `playbackId` prop
muxPlayer.playbackId = 'new-playback-id-xxx'; 

Debugging

Add the debug attribute or React prop in order to print verbose logging to the developer console. This will enable verbose logging from:

• Mux Player itself (prefixed with [mux-player])
• HLS.js
• Mux Data

Note that this must be set before setting a playback-id to take full advantage of debug logging.

Disabling Cookies

Even though Mux Data cookies do not contain any personally identifiable information (PII) and are used for more reliable and informative QOE metrics, there are times when you may want or need cookies to be disabled.

In those cases, you can use the disable-cookies attribute or disableCookies React prop to turn off use of cookies by Mux Data. Note this must be set before setting a playback-id to take effect.

For more on the use of cookies in Mux Data, see the docs.

Custom Storyboards

By default Mux Player will use the storyboard WebVTT text track that corresponds to your plaback-id

https://image.mux.com/{PLAYBACK_ID}/storyboard.vtt?format=webp

If you want to use a different WebVTT source file for your storyboard, you can use the storyboard-src attribute or storyboardSrc React prop to override it. Keep in mind that the WebVTT source file must conform to our expectations for storyboards.