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

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:

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

Thumbnail token:

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

Storyboard token (only needed for on-demand):

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:

<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:

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:

<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:

<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:

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:

<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.

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.

Adding CuePoints

Mux Player has an extended API for working with CuePoints metadata, which allows you to associate generic metadata with your stream's timeline and playback. This includes the addCuePoints() method to add CuePoints, cuePoints and activeCuePoint properties to get all CuePoints or the current active CuePoint (based on the element's currentTime), and the cuepointchange event, which fires whenever the activeCuePoint changes. The "shape" of a CuePoint is { time: number; value: any; }, where time is the playback time (in seconds) you want the CuePoint to begin, and value is whatever (JSON-serializable) value is appropriate for your CuePoint use case.

To add CuePoints via addCuePoint(), simply pass in an array of CuePoints (as described above). Note that CuePoints are tied to the loaded media source, so: (a) you'll need to wait until the media source (src or playback-id) has loaded before adding any CuePoints; and (b) the CuePoints will be removed if you unload() the current media source or change it by re-setting e.g. playback-id. Below is a simple example of using CuePoints:

const muxPlayerEl = document.querySelector('mux-player');
function addCuePointsToElement() {
  // NOTE: Time is in seconds
  const cuePoints = [
    { time: 1, value: 'Simple Value' }, 
    { time: 3, value: { complex: 'Complex Object', duration: 2 } },
    { time: 10, value: true },
    { time: 15, value: { anything: 'That can be serialized to JSON and makes sense for your use case' } }
  ];

  muxPlayerEl.addCuePoints(cuePoints);
}

function cuePointChangeListener() {
  // Do something with the activeCuePoint here. 
  console.log('Active CuePoint!', muxPlayerEl.activeCuePoint);
}

// 
muxPlayerEl.addEventListener('cuepointchange', cuePointChangeListener);
// Here, we're `duration` and `'durationchange'` to determine if the `<mux-player>` element has loaded src. This also gives
// us the opportunity to compare our intended CuePoints against the duration of the media source.
// Note that you could use other events, such as `'loadedmetadata'` if that makes more sense for your use case.
if (playerEl.duration) {
  addCuePointsToElement();
} else {
  muxPlayerEl.addEventListener('durationchange', addCuePointsToElement, { once: true });
}

One last thing to note about CuePoints: Although they only have a single time value, if a user seeks between the time of two CuePoints, the cuepointchange event will still fire and the activeCuePoint will be the earlier CuePoint. Using the example above for reference, we have a CuePoint with a time of 3 and another with a time of 10. If a user seeks to 8, the activeCuePoint will be the CuePoint with the time of 3. This is intentional to cover as many use cases as possible. If you only care about the activeCuePoint when the currentTime is roughly the same as the time, you can add some simple logic to account for that, e.g.:

function cuePointChangeListener() {
  // Only do something with the activeCuePoint if we're playing "near" its `time`.
  const MARGIN_OF_ERROR = 1;
  if (Math.abs(muxPlayerEl.currentTime - muxPlayerEl.activeCuePoint.time) <= MARGIN_OF_ERROR) {
    console.log('Active CuePoint playing near its time!', muxPlayerEl.activeCuePoint);
  }
}