Welcome to the new Mux Docs.
The old version is still available here

Core functionality of Mux Player

In this guide, see the features and functionality that Mux Player gives you out of the box.

In this guide:

Mux Platform integration

Understand how Mux Player integrates with the Mux Platform

Responsiveness

Understand how Mux Player handles responsiveness at different sizes

Controls and UI

See how Mux Player handles controls based on the stream type, and feature availability

Accessibility

Understand how Mux Player addresses accessibility

Error handling

Understand how Mux Player handles errors

Audio player

Understand how Mux Player supports audio only

Mux Player is built for playing assets hosted with Mux Video. Features like timeline hover previews and automatically pulling poster images work with minimal configuration because the video is hosted by Mux.

Mux Player will use the optimal Hls.js settings based on the provided stream-type. New versions of Mux Player will contain upgraded versions of Hls.js that are known to be stable versions and tested with Mux Player.

Mux Data integration

Mux Player is integrated with Mux Data automatically to measure the performance and quality of experience. See the Understand metric definitions guide to learn more about the metrics that are tracked with Mux Data.

Your Mux Data environment will be inferred from the playback ID provided to Mux Player. No configuration is necessary. If you would like to override that default and send the video views to a specific Mux environment, you can pass the env-key (HTML element) attribute or envKey (React) prop.

Responsiveness

Mux Player has different UI permutations based on stream type (on-demand, live, ll-live, live:dvr, ll-live:dvr), device availability, and screen size.

Note that the responsiveness of Mux Player is based on the size of the container that it is being rendered in, not the viewport size. If you have a collection of small players in a large viewport, the layout of the controls for each player will be sized appropriately.

<div>
<mux-player
  stream-type="live"
  playback-id="v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM"
  metadata-video-title="Test Live Stream"
  metadata-viewer-user-id="user-id-007"
></mux-player>
</div> 

<div style="max-width: 250px;">
<mux-player
  stream-type="live"
  playback-id="v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM"
  metadata-video-title="Test Live Stream"
  metadata-viewer-user-id="user-id-007"
></mux-player>
</div>

Here is a CodeSandbox environment you can view samples in

Controls and UI

Mux Player will show or hide controls based on availability.

On iPhone browsers Mux Player uses Apple's fullscreen functionality.

On iPhone and iPad browsers, the volume slider is not present. Volume level must be controlled via the hardware buttons. This is a restrictions of iOS and iPadOS.

The fullscreen button will not show if fullscreen functionality is not available on the page (for example, if Mux Player is embedded inside of an iframe that does not include the allow="fullscreen" attribute. This is currently the case on CodeSandbox examples and other similar code testing platforms.

If you are embedding Mux Player in an iframe, use the <iframe allow="fullscreen"> in order to access fullscreen functionality.

You'll notice the controls are different for "on-demand", "live", "ll-live", live:dvr and ll-live:dvr stream types.

Chromecast

Chromecast support is built-in. The only thing you need to do in order to enable it is add the Google Cast script to the <head> of your webpage.

<script
  defer
  src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"
></script>

When this script is loaded and a Chromecast is detected on the network then Mux Player will show the Chromecast button in the control bar.

Note that the default Chromecast receiver app does not currently support low-latency Live Streams. If you have your own receiver app that you want to use instead of the default Chromecast receiver app you can over-ride the variable: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID to point to your receiver app ID.

Live Stream playback

When live streaming with Mux you have 2 options for viewers:

Non-DVR mode: This is most common. Use the playback_id associated with the Live Stream for playback. Non-DVR mode keeps viewers on the "live edge" of the live content and does not allow them to seek backwards while the stream is live.
DVR mode: This is less common, but might be what you want depending on the use case. Use the playback_id associated with the Asset that corresponds to the Live Stream for playback. DVR mode allows users to seek backwards while the stream is still live.

For more information about non-DVR mode and DVR mode and some of the tradeoffs to consider, take a look at this guide.

When viewing live streams with Mux Player you have 2 options:

Use the playback_id associated with the Live Stream itself. If the Live Stream was created with "latency_mode": "low" then it is a low-latency live stream and in Mux Player you should specify stream-type="ll-live", otherwise specify stream-type="live".
Live Stream created in Mux have a corresponding Asset. Use the playback_id associated with the Asset in order to view the live stream in DVR-mode. For DVR-mode, if the Live Stream was created with "latency_mode": "low" then in Mux Player specify stream-type="ll-live:dvr", otherwise specify stream-type="live:dvr".

When using DVR-mode in Mux Player, the UI will show a timeline for users to scroll back to the beginning of the Live Stream while the Live Stream is still active.

Timeline hover previews

Timeline hover previews show a small thumbnail of the video content at a given timestamp. They help to provide a contextual visual for the viewer based on where their cursor is positioned over the timeline.

When you play back a video hosted on Mux using Mux Player, you’ll see built-in timeline hover previews for the video with no extra work on your end.

Accessibility

Mux Player has taken steps to being fully WCAG AA compliant. At this time Mux Player supports:

Keyboard navigation
Screen reader compatibility with the Accessibility Object Model
Closed captions / subtitles will show by default (if the video has them)

Best practices

Make sure to take accessibility into consideration when customizing Mux Player. See the guide for customizing the look and feel of Mux Player to change things like primary color, secondary color, or styling with CSS.

When setting color variables and changing styles make sure your implementation meets the contrast ratio requirements for WCAG 2.1.

Error handling

Mux Player will internally make every attempt to recover from errors and maintain smooth playback.

When Mux Player encounters unrecoverable fatal errors, it will try to:

Make it clear to the viewer where the error is coming from and what, if anything, they can do about it.
Provide context for a developer to debug and prevent the error from happening in the future. Developer logs prefixed with [mux-player] will contain debugging details and a link to more information.
The error will be tracked with details in your Mux Data dashboard.

Audio player

If you have an audio-only Mux asset, you can set the audio attribute on mux-player to display the audio player. You can also add the audio attribute to a video asset to make a video look like an audio player.

<div>
<mux-player
  stream-type="on-demand"
  playback-id="x00Y6AhtNCs01UIW02FhPY4H6hZHkQLuiLoD1tTMj00zuxE"
  metadata-video-title="Test Audio Stream"
  metadata-viewer-user-id="user-id-007"
  muted
  audio
  primary-color="#075389"
  secondary-color="#d6e6f1"
></mux-player>
</div>