Skip to Content
Mux Docs: Home

Advanced usage of Mux Player

In this guide, you will learn about more 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:


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:

  • Playback 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 for timeline hover previews. This only works for on-demand video, live streams aren't supported.

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

Playback token:


Thumbnail token:


Storyboard token (only needed for on-demand):


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

Example with the HTML element:

metadata-video-title="Test video title"

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:

video_id: "video-id-54321",
video_title: "Test video title",
viewer_user_id: "user-id-007",
playback: "eyJhbGciOiJSUzI1NiI...",
thumbnail: "eyJhbGciOiJSUzI1N...",
storyboard: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsI...",

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

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". Or omit it for the default behavior.

When there is no preload attribute, the player will use the behavior that the browsers set initially. Most browsers use "auto", but some (like Chrome) use "metadata" instead. On mobile devices, preload is always none. For the most consistent user experience, we recommended providing the preload attribute.

The value "auto" 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 (and 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 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 then internally Mux Player will take that value and expand it to for images and for video.

Example with the HTML element:


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

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

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


Change playback engine

Mux Player will automatically handle Adaptive Bitrate Streaming with your Mux Asset. For a beginner's guide on how this 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';


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{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' } }
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) {
} 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);

Synchronize video playback

To facilitate synchronizing video playback across players, Mux Player exposes currentPdt and getStartDate().

If the stream includes Program Date Time tags, currentPdt and getStartDate() will return a Date object that corresponds to the PDT at the current time or at the begining of the stream. If there is no PDT, or if the video hasn't loaded yet, currentPdt and getStartDate() will return an Invalid Date object.

See Synchronize video Playback for more information.

currentPdt and getStartDate() currently require that Slates are enabled on your stream. If Slates are not enabled, it is possible that the times provides are not accurate.

Refer to this sample for the usage below:



This will return a JavaScript Date object that is based on the currentTime. If there is no PDT in the stream, an invalid date object is returned.

const player = document.querySelector('mux-player');
// assuming the above stream, the initial currentPdt would be
// Mon Jun 28 2021 13:53:25 GMT-0400 (Eastern Daylight Time)
// 1624902805533
// now if we seek forward, by 10 seconds
player.currentTime = 10;
// Mon Jun 28 2021 13:53:35 GMT-0400 (Eastern Daylight Time)
// 1624902815533


This will return a JavaScript Date object that is based on the beginning of the stream. This method is a reflection of the HTML specified method.

const player = document.querySelector('mux-player');
// assuming the above stream, getStartDate() would return
// Mon Jun 28 2021 13:53:25 GMT-0400 (Eastern Daylight Time)
// 1624902805533
// notice that when currentTime is 0, getStartDate() is equivalent to currentPdt
// now if we seek forward, by 10 seconds
player.currentTime = 10;
// Mon Jun 28 2021 13:53:25 GMT-0400 (Eastern Daylight Time)
// 1624902805533
// notice that even though we seeked forward, we still get the same value.

Full API reference

Any features or settings not mentioned above can be found in our full API reference covering all of the available events, attributes, properties, and methods exposed by the player.

Was this page helpful?