ReferenceMedia
MuxVideo
Video element for Mux-hosted HLS streams
Video element for playing Mux-hosted HLS streams.
Import
Choose a playback engine
The Mux video component can play your video through one of two engines: SPF or hls.js. An engine is the code that downloads the stream and feeds it to the browser. You choose one by its import path.
SPF is Video.js’s own engine, built for the streams Mux delivers. It’s a fraction of hls.js’s size, and it will become the default in an upcoming release. hls.js is mature, widely used, and plays almost any HLS stream. The default import uses hls.js today.
All three imports give you a MuxVideo component with the same basic API.
When to use SPF
- You want a smaller page. SPF is about a quarter of hls.js’s size, which matters most with several players on a page or on slower connections.
- You use AirPlay. Starting and stopping AirPlay works smoothly on SPF. hls.js can get into a bad state when you do either.
When to use hls.js
SPF is still under development. Use hls.js if any of these applies to you:
- You stream live without slates. A slate is the image Mux shows while a broadcaster reconnects. Without one, playback stops at the point where the broadcaster dropped and came back, in the live stream and in the recording Mux makes of it.
- You rely on detailed Mux Data. With SPF, Mux Data doesn’t receive playback errors, or detail like quality switches and download speed.
- You need low latency. SPF plays low-latency live streams with the delay of an ordinary live stream.
- You set quality limits on the player. SPF doesn’t let you set the lowest or highest quality the player picks on its own, or stop it from matching quality to the player’s size.
- You support older iPhones. SPF needs iOS 17.1 or later.
SPF limitations in detail
Live streams without slates. When an encoder disconnects, Mux keeps the live stream open for its reconnect_window. With a slate, Mux fills that time with the slate image, so the stream stays continuous. Without one, no media arrives until the encoder reconnects, and Mux marks the break with EXT-X-DISCONTINUITY. The asset Mux records from the stream keeps the same discontinuity. SPF doesn’t handle discontinuities yet, in CMAF or MPEG-TS, so playback breaks there. To avoid it, set reconnect_window above 0 and, for standard-latency streams, use_slate_for_standard_latency to true. Handle live stream disconnects covers the settings.
Mux Data. Mux Data plugs into hls.js to collect engine-level data. It has no such integration for SPF, so it monitors the media element alone. Views, startup time, and rebuffering still come through. Errors SPF raises itself, such as a manifest that fails to load or content it can’t play, don’t, and neither do rendition switches or request timing and throughput.
Low-Latency HLS. SPF skips the partial segments (EXT-X-PART) that make LL-HLS low latency and loads whole segments instead. The stream plays as standard-latency live, at the distance from the live edge that the playlist’s HOLD-BACK sets. SPF logs a console warning when this happens.
Rendition limits. maxAutoResolution, minAutoResolution, and capRenditionToPlayerSize are hls.js options, so the SPF flavor doesn’t take them. SPF always caps the rendition to the player’s size. To limit renditions on either engine, use source.playback.maxResolution or source.playback.minResolution, which Mux applies to the playlist itself.
Browsers without Media Source Extensions. SPF plays through MediaSource, or ManagedMediaSource on iPhone, and has no fallback to the browser’s own HLS playback. iPhone Safari before iOS 17.1 has neither, so SPF can’t play there. The hls.js flavor falls back to native HLS.
Load a source
The source param builds the URL for you from a playback ID, an optional custom domain, and playback params. Playback params are just camelCased Mux playback query params; for example, max_resolution becomes maxResolution.
If for some reason you need a bit more control, you can use the src param with a plain ’ol URL, too:
MuxVideo ignores the same source object when it is assigned again. A new object fires sourcechange even when its values are equal, although an equivalent playback source does not reload.
Posters and storyboards
The Mux video component derives a poster image and a storyboard from the playback ID. source.poster and source.storyboard configure the generated URLs.
When the Mux video component is inside a player, it supplies the poster for the skin to display. Set poster on the player when you want to use your own image instead.
A generated poster becomes available after MuxVideo mounts. Pass poster to the player when the image must appear in server-rendered HTML.
The Mux video component injects the derived storyboard <track> automatically and removes it when the media detects a live stream. Configure the derived URLs through the source object:
The storyboard lives on a Mux domain, so the Mux video component has to be CORS-enabled for that cross-origin <track> to load at all. The thumbnail component then fetches the sprite sheets its cues point at the same way:
Signed playback
For signed playback, put the playback token on source.playback.token. The token replaces every other playback param, so bake modifiers like resolution and time bounds into the token when you sign it.
Signed playback needs a separate token for each image URL. Put the thumbnail token (aud: 't') at source.poster.token and the storyboard token (aud: 's') at source.storyboard.token. If either token is missing or has the wrong audience, the Mux video component does not generate the corresponding URL.
Protected content
For DRM-protected playback, put the DRM license token on source.drm.token. The Mux video component derives the FairPlay, Widevine, and PlayReady license servers from it. DRM playback is always signed, so a playback.token belongs alongside it.
Media sources covers mixing Mux’s license servers with your own.
Analytics and casting
The Mux video component plays Mux streams. It doesn’t monitor them or cast them — Mux Data and Google Cast are separate extensions you add to the player alongside it. Mux Data needs no environment key here, since Mux attributes the views to the environment that owns the playback ID:
Install both extensions before using the example below:
Examples
Basic Usage
API Reference
Props
Accepts the standard React props for a native <video>, plus these Video.js-specific props:
Engine options
source.engine.nativeHls
Options passed under source.engine.nativeHls.
Refs
ref
Forwards to the rendered <video>,
an HTMLVideoElement with its complete native property and method API.
mediaRef
Receives the MuxVideoAdapter that
drives the <video>, the same
object useMedia() returns inside a
player. It forwards the native media methods, properties, and
events, such as play() and currentTime, and exposes the
playback engine through engine. It
is set once the adapter has attached to the element and cleared
when the element unmounts. For DOM-only APIs, use ref.
Events
Handle standard media events with React event props such as onPlay and onTimeUpdate. For native events without a React prop, attach a listener through the ref with addEventListener.