Advanced usage of Mux Player | Mux

Advanced usage of Mux Player

Copy pageCopiedError

Go further with Mux Player: listen for events, add chapters, and set cue points. Use this guide when the basic setup works and you want more control.

This guide covers advanced features of Mux Player: events, chapters, and cue points. Use it when the basic integration works and you want more control. For example, you can track how much of a video a viewer watches, or add chapters to a long lecture.

Listen for events

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

Events are unavailable if you are using the Mux Player HTML embed through player.mux.com.

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

index.html

index.js

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

// React example

Secure your playback experience

Mux offers a couple of ways to secure your media content:

using signed URLs, which ensures only people with a valid, unexpired token can load your video in allowed playback contexts
using Digital Rights Management Beta

Both options are easy to use with Mux Player and are discussed below.

Use 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.
DRM is used for playing DRM-protected content. See the section below.

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

Playback token:

// example playback token

Thumbnail token:

// example thumbnail token

Storyboard token (only needed for on-demand):

// example storyboard token

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

// Mux Player integration with tokens

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.

Use Digital Rights Management (DRM)

This feature is currently in beta. Learn more about DRM. Beta

To play DRM protected content on iOS and iPadOS devices the device should be running the current minor and patch version of iOS or iPadOS.

We strongly recommend that viewers use the latest version of iOS/iPadOS 17 or 18 when viewing DRM protected content.

Playing DRM protected content on an OS version that is not the latest minor and patch version of a major release is known to result in playback failures.

If you've setup your playback ID to be DRM-protected, playback is as simple as adding the DRM token to your set of tokens used.

// DRM example

Controlling an iframe-embedded Mux Player with Player.js

Mux Player embedded within an iframe with player.mux.com supports the Player.js spec. This means you can control the player from your own window's JavaScript. See the Player.js docs for more information.

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.

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.

Access the underlying video element

The media.nativeEl property is a reference to the underlying video element. When using the Mux Player Web Component or React component, You can use this to access the video element's properties and methods.

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.

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.

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

Custom storyboards

By default Mux Player will use the storyboard WebVTT text track that corresponds to your playback-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.

Add chapters and time-based metadata

The Mux Player Web Component and React component support both chapters and time-based metadata (cue points). Chapters visually split the timeline into sections with titles that users can click to jump to. Cue points allow you to associate custom metadata with ranges of time in the timeline.

If you omit endTime from a cue point or chapter, it will automatically end when the next one begins by joining them together without gaps.