Skip to content

ReferenceMedia

mux-video

Video element for Mux-hosted HLS streams

Video element for playing Mux-hosted HLS streams.

Import

pnpm add @videojs/mux-video
import '@videojs/html/media/mux-video';

Or load it from the CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.5.0/media/mux-video.js"></script>

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.

Import Engine Choose it when
.../media/mux-video/spf SPF None of the cases under “When to use hls.js” applies to you.
.../media/mux-video hls.js today, SPF soon You want the recommended engine, and you’re fine with it changing in a future release.
.../media/mux-video/hls-js hls.js One of the cases under “When to use hls.js” applies to you.
import '@videojs/html/media/mux-video/spf';

All three imports register the same <mux-video> tag with the same basic API. Load only one of them on a page: the first one to load claims the tag, and the others are ignored.

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

<mux-video> takes Mux content two ways: a stream URL through src, or a structured source object.

<mux-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"></mux-video>

The source object 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.

const video = document.querySelector('mux-video')!;
video.source = {
  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
  customDomain: 'media.example.com',
  playback: { maxResolution: '1080p' },
};

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

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:

const video = document.querySelector('mux-video')!;
video.source = {
  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
  poster: { time: 2, width: 1280 },
  storyboard: { format: 'webp' },
};

For declarative HTML, poster-time="2" reflects to source.poster.time after the src attribute is parsed.

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:

<mux-video
  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
  crossorigin="anonymous"
></mux-video>

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.

const video = document.querySelector('mux-video')!;
video.source = {
  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
  playback: { token: playbackToken },
  poster: { token: posterToken },
  storyboard: { token: storyboardToken },
};

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.

const video = document.querySelector('mux-video')!;
video.source = {
  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
  playback: { token: playbackToken },
  drm: { token: drmToken },
};

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:

pnpm add @videojs/mux-data @videojs/google-cast
<script type="module">
  import '@videojs/html/video/player';
  import '@videojs/html/media/mux-video';
  import '@videojs/html/extensions/mux-data';
  import '@videojs/html/extensions/google-cast';
</script>

<video-player>
  <mux-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" playsinline></mux-video>
  <mux-data player-software-name="mux-video"></mux-data>
  <google-cast></google-cast>
</video-player>

Cast DRM-protected content

Google’s Default Media Receiver can’t license DRM, so while the source has a drm.token, the Cast button stays disabled until the Google Cast extension’s receiver is set. Cast DRM-protected content covers hosting your own receiver and passing it a license server through customData.

Build the Widevine license URL from the playback ID and DRM token: https://license.mux.com/license/widevine/{playbackId}?token={drmToken}. A receiver built with Mux’s Google Cast DRM guide reads customData.mux instead. For that receiver, pass { mux: { playbackId, tokens: { drm: drmToken } } }, the format Mux Player sends.

Examples

Basic Usage

<media-container class="media-container">
  <mux-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop crossorigin="anonymous"></mux-video>
</media-container>

API Reference

Attributes

Forwards these standard media attributes to the internal <video>. See the MDN media element reference: autopictureinpictureautoplaycontrolscontrolslistcrossorigindisablepictureinpicturedisableremoteplaybackloadingloopmutedplaysinlineposterpreloadsrc

These Video.js-specific attributes configure media behavior:

AttributeTypeDefaultDetails
stream-type'on-demand' | 'live' | 'unknown''unknown'

Properties

PropertyTypeDefaultDetails
audioRenditionsAudioRenditionListLike | undefined—
audioTracksAudioTrackListLike | undefined—
contentDataobject—
disableRemotePlaybackunknownfalse
engineHls | null—
engineNamestring | undefined—
errorMediaError | null—
isFullscreenboolean—
isPictureInPictureboolean—
liveEdgeStartnumber—
preloadMediaPreloadType'metadata'
sourceobjectnull
srcstring''
streamType'on-demand' | 'live' | 'unknown''unknown'
targetLiveWindownumber—
videoRenditionsVideoRenditionListLike | undefined—
videoTracksVideoTrackListLike | undefined—
webkitCurrentPlaybackTargetIsWirelessboolean | undefined—
webkitPresentationModeWebKitPresentationMode | undefined—
webkitSetPresentationModeundefined | function—

Also exposes these properties from the native media API. See HTMLVideoElement for details: autoplaybufferedcontrolscrossOrigincurrentSrccurrentTimedefaultMuteddefaultPlaybackRatedisablePictureInPicturedurationendedloopmutedpausedplaybackRateplayedplaysInlineposterreadyStateremoteseekableseekingtextTrackstitlevideoHeightvideoWidthvolume

Engine options

source.engine.nativeHls

Options passed under source.engine.nativeHls.

OptionTypeDetails
drmSystemsPartial<Record<KeySystem, DrmSystemCo...

Methods

Supports these media methods. See HTMLVideoElement for details: addTextTrackcanPlayTypeexitFullscreenexitPictureInPictureloadpauseplayremoveTextTrackrequestFullscreenrequestPictureInPicture

Events

Re-dispatches these standard media events from the internal media element: abortaddtrackcanplaycanplaythroughchangedurationchangeemptiedendedenterpictureinpictureerrorleavepictureinpictureloadeddataloadedmetadataloadstartpauseplayplayingprogressratechangeremovetrackresizeseekedseekingstalledsuspendtimeupdatevolumechangewaiting

Also emits these Video.js-specific events:

EventDescription
contentdatachangeFired when contentData changes: the derived URLs with source, and the metadata once it loads. Read contentData for the new value.
sourcechangeFired when source changes, either directly or by resolving a new src. Read source for the new value.
streamtypechangeFired when the detected stream type changes. Read streamType for the new value.
targetlivewindowchangeFired when the target live window changes. Read targetLiveWindow for the new value.

CSS custom properties

VariableDescription
--media-video-border-radiusBorder radius of the video element.
--media-object-fitObject fit for the video.
--media-object-positionObject position for the video.
--media-caption-track-durationDuration of the caption track transition.
--media-caption-track-delayDelay before the caption track transition.
--media-caption-track-yVertical offset of the caption track.