REFERENCE.md

Attributes

Attribute	Type	Description	Default
autoplay	boolean | "any" | "muted"	For booleans, identical to the <video autoplay/> attribute. Additionally support "muted" to start autoplay with the media muted and "any" to try autoplaying "by any means necessary"	false
crossorigin	string (enum)	Identical to the <video crossorigin/> attribute, except default is "" (equivalent to "anonymous")	""
loop	boolean	Identical to the <video loop/> attribute	false
muted	boolean	Like the <video muted/> attribute, only updates the muted property instead of the defaultMuted property	false
poster	string (URL)	Identical to the <video poster/> attribute. Will use the automatically generated poster based on your playback-id by default unless in audio mode. Explicitly set this attribute to show a poster in audio mode. Remove the poster by setting the value to an empty string.	Derived
preload	string (enum)	Identical to the <video preload/> attribute (with an appropriate equivalent for HLS media content)	Varies
volume	number (0-1)	Attribute equivalent of the volume property	Varies
playbackrate	number	Attribute equivalent of the playbackRate property	1
env-key	string	Your Mux Data environment key. Note that this is different than your API Key. Get your env key from the "Mux Data" part of your Mux Environments Dashboard. If unset, the environment will be inferred based on your Mux Video asset.	N/A
debug	boolean	Enables debug mode for the underlying playback engine (currently hls.js) and mux-embed, providing additional information in the console.	false
no-volume-pref	boolean	Disables storing the selected volume in localStorage.	false
disable-tracking	boolean	Disables Mux Data tracking. For more, check out the Mux Docs	false
disable-cookies	boolean	Disables cookies used by Mux Data. For more, check out the Mux Docs.	false
playback-id	string	The playback ID for your Mux Asset or Mux Live Stream. This will also be used for automatically assigning a poster image and (thumbnail previews)[https://docs.mux.com/guides/video/create-timeline-hover-previews]. For more, check out the Mux Docs.	N/A
prefer-playback	"mse" | "native"	Specify if Mux Player should try to use Media Source Extension or native playback (if available). If no value is provided, Mux Player will choose based on what's deemed optimal for content and playback environment.	Varies
max-resolution	"720p" | "1080p" | "1440p" | "2160p"	Specify the maximum resolution you want delivered for this video.	N/A
min-resolution	"480p" | "540p" | "720p" | "1080p" | "1440p" | "2160p"	Specify the minimum resolution you want delivered for this video.	N/A
rendition-order	"desc"	Change the order in which renditions are provided in the src playlist. Can impact initial segment loads. Currently only support "desc" for descending order	N/A
program-start-time	number	Apply PDT-based instant clips to the beginning of the media stream.	N/A
program-end-time	number	Apply PDT-based instant clips to the end of the media stream.	N/A
asset-start-time	number	Apply media timeline-based instant clips to the beginning of the media stream.	N/A
asset-end-time	number	Apply media timeline-based instant clips to the end of the media stream.	N/A
metadata-video-id	string	This is an arbitrary ID sent to Mux Data that should map back to a record of this video in your database.	N/A
metadata-video-title	string	This is an arbitrary title for your video that will be passed in as metadata into Mux Data. Adding a title will give you useful context in your Mux Data dashboard. (optional, but encouraged)	N/A
metadata-viewer-user-id	string	If you have a logged-in user, this should be an anonymized ID value that maps back to the user in your database that will be sent to Mux Data. Take care to not expose personal identifiable information like names, usernames or email addresses. (optional, but encouraged)	N/A
metadata-*	string	This metadata-* syntax can be used to pass any arbitrary Mux Data metadata fields	N/A
beacon-collection-domain	string (domain name)	Assigns a custom domain to be used for Mux Data collection.	N/A
custom-domain	string (domain name)	Assigns a custom domain to be used for Mux Video.	N/A
stream-type	"on-demand" | "live" | "ll-live" | "live:dvr" | "ll-live:dvr"	The type of stream associated with your Mux Asset. Used to determine what UI/controls to show and what optimizations to make for playback.	"on-demand"
default-stream-type	"on-demand" | "live"	The default assumed stream-type before any playback-id has been loaded. Used along with target-live-window to determine what UI/controls to show by default.	on-demand
target-live-window	number	An offset representing the seekable range for live content, where Infinity means the entire live content is seekable (aka "standard DVR"). Used along with stream-type to determine what UI/controls to show.	(inferred from playback-id and/or stream-type, otherwise NaN)
start-time	number (seconds)	Specify where in the media's timeline you want playback to start.	0
default-hidden-captions	boolean	Hide captions by default instead of showing them on initial load (when available)	false
default-duration	number (seconds)	Applies a duration value before the media has loaded. Useful when used in conjunction with preload="none"	N/A
primary-color	string (Any valid CSS color style)	The primary color used by the player's UI	N/A
secondary-color	string (Any valid CSS color style)	The secondary color used by the player's UI	N/A
accent-color	string (Any valid CSS color style)	The accent color used by the player's UI	N/A
forward-seek-offset	number (seconds)	Offset applied to the forward seek button and keyboard navigation	10
backward-seek-offset	number (seconds)	Offset applied to the backward seek button and keyboard navigation	10
playback-token	string	The playback token for signing the src URL.	N/A
thumbnail-token	string	The thumbnail token for signing the poster URL.	N/A
storyboard-token	string	The storyboard token for signing the storyboard URL.	N/A
drm-token	string	The token for signing DRM license and related URLs.	N/A
storyboard-src	string (URL) pointing to a .vtt file	Full URL string for the storyboard asset. Typically derived from the playbackId, setting this attribute will override the derived storyboard.	undefined
thumbnail-time	number (seconds)	Time offset for the default poster image based on your playback-id. If no thumbnail-time is specified, start-time will be used by default. NOTE: This feature currently cannot be used with thumbnail-token.	0
audio	boolean	Indicate that you want an "audio only" UI/chrome. This may be used for audio-only assets or audio+video assets.	false
nohotkeys	boolean	Toggles keyboard shortcut (hot keys) support when focus in inside the player	false
hotkeys	DOMTokenList (space separated enum list)	A blocklist of keyboard shortcuts (hotkeys) you want to disable. Based on Media Chrome's implementation	N/A
playbackrates	number[] (space separated list)	A space separated string of playback rates used by the playback rate button.	N/A
default-show-remaining-time	boolean	Show remaining playback time (instead of current playback time) by default	false
title	string	Title text to show for your content in the Mux Player UI.	""
placeholder	string (URI)	Image to show as various assets load. Typically a data URI when used	N/A
cast-receiver	string (Receiver ID)	The app ID to use for a custom Google cast receiver. If none is provided, the default receiver app will be used.	N/A
no-tooltips	boolean	Toggles disabling tooltips in the UI	false
player-init-time	number (timestamp)	Overrides the default player initialization time, used by Mux Data for time-based quality-of-experience (QOE) metrics. It will be inferred from instantiation time by default.	Varies

Methods

Method	Description
play()	Identical to the native play() method.
pause()	Identical to the native pause() method.
addCuePoints()	Add an array of CuePoints with the shape { startTime: number; endTime?: number, value: any; } to the Mux Player instance
addChapters()	Add an array of chapters with the shape { startTime: number; endTime?: number, value: string; } to the Mux Player instance
getStartDate()	Will return a Date that matches the earliest PDT in your stream. Identical to native getStartDate() method, if exists.

|

Properties

Prop	Type	Description	Default
paused Read only	boolean	Identical to the native paused property	true
duration Read only	number	Identical to the native duration property	NaN
ended Read only	boolean	Identical to the native ended property	false
buffered Read only	TimeRanges	Identical to the native buffered property	(empty TimeRanges instance)
seekable Read only	TimeRanges	Identical to the native seekable property	(empty TimeRanges instance)
readyState Read only	number (enum)	Identical to the native readyState property	NaN
videoWidth Read only	number	Identical to the native videoWidth property	0
videoHeight Read only	number	Identical to the native videoHeight property	0
currentTime	number	Identical to the native currentTime property	0
currentPdt	Date	Will return a Date that matches current PDT in your stream. Accounting for currentTime.	0
volume	number	Identical to the native volume property	1
noVolumePref	boolean	Disables storing the selected volume in localStorage.	false
poster	string (URL)	Identical to the native poster property. Will use the automatically generated poster based on your playback-id by default. Remove the poster by setting the value to an empty string.	Derived
storyboard	string (URL)	URL for the Mux Storyboard. Will automatically generate the url based on your playback-id and token. Will not be set if the provided storyboardToken is invalid.	Derived
playbackRate	number	Identical to the native playbackRate property	1
defaultPlaybackRate	number	Identical to the native defaultPlaybackRate property	1
crossOrigin	string	Identical to the native crossOrigin property, except default is "" (equivalent to "anonymous")	""
autoplay	boolean | "any" | "muted"	For booleans, identical to the native autoplay property. Additionally support "muted" to start autoplay with the media muted and "any" to try autoplaying "by any means necessary"	false
loop	boolean	Identical to the native loop property	false
muted	boolean	Identical to the native muted property	false
defaultMuted	boolean	Identical to the native defaultMuted property	false
preload	string (enum)	Identical to the native preload property (with an appropriate equivalent for HLS media content)	undefined
hasPlayed Read only	boolean	Indicates whether playback has begun for the current media asset associated with the playback-id	false
inLiveWindow Read only	boolean	Indicates whether the playback time is currently near the live edge (only relevant for live/dvr content)	false
audio	boolean	Indicate that you want an "audio only" UI/chrome. This may be used for audio-only assets or audio+video assets.	false
hotkeys Read only*	DOMTokenList	A DOMTokenList (similar to classList) blocklist of keyboard shortcuts (hotkeys) you want to disable. Based on Media Chrome's implementation	''
nohotkeys	boolean	Toggles keyboard shortcut (hot keys) support when focus in inside the player	false
thumbnailTime	number (seconds)	Time offset for the default poster image based on your playback-id. If no thumbnail-time is specified, start-time will be used by default. NOTE: This feature currently cannot be used with thumbnail-token.	0
title	string	Title text to show for your content in the Mux Player UI.	""
placeholder	string (URI)	Image to show as various assets load. Typically a data URI when used	N/A
primaryColor	string (Any valid CSS color style)	The primary color used by the player's UI	undefined
secondaryColor	string (Any valid CSS color style)	The secondary color used by the player's UI	undefined
accentColor	string (Any valid CSS color style)	The accent color used by the player's UI	undefined
defaultShowRemainingTime	boolean	Show remaining playback time (instead of current playback time) by default	false
playbackRates	number[]	Array of numbers used by the playback rate button.	N/A
forwardSeekOffset	number (seconds)	Offset applied to the forward seek button and keyboard navigation	10
backwardSeekOffset	number (seconds)	Offset applied to the backward seek button and keyboard navigation	10
defaultHiddenCaptions	boolean	Hide captions by default instead of showing them on initial load (when available)	false
defaultDuration	number (seconds)	Applies a duration value before the media has loaded. Useful when used in conjunction with preload="none"	N/A
beaconCollectionDomain	string (domain name)	Assigns a custom domain to be used for Mux Data collection. NOTE: Must be set before playbackId to apply to Mux Data monitoring.	undefined ("litix.io")
playbackId	string	The playback ID for your Mux Asset or Mux Live Stream. This will also be used for automatically assigning a poster image and (thumbnail previews)[https://docs.mux.com/guides/video/create-timeline-hover-previews]. For more, check out the Mux Docs.	undefined
customDomain	string (domain name)	Assigns a custom domain to be used for Mux Video.	undefined ("mux.com")
envKey	string	Your Mux Data environment key. Note that this is different than your API Key. Get your env key from the "Mux Data" part of your Mux Environments Dashboard. If undefined, the environment will be inferred based on your Mux Video asset.	undefined (inferred)
debug	boolean	Enables debug mode for the underlying playback engine (currently hls.js) and mux-embed, providing additional information in the console. NOTE: Must be set before playbackId to fully apply to debug logging contexts.	false
disableTracking	boolean	Disables Mux Data tracking. For more, check out the Mux Docs	false
disableCookies	boolean	Disables cookies used by Mux Data. For more, check out the Mux Docs.	false
streamType	"on-demand" | "live" | "ll-live" | "live:dvr" | "ll-live:dvr"	The type of stream associated with your Mux Asset. Used to determine what UI/controls to show and what optimizations to make for playback.	"on-demand"
defaultStreamType	"on-demand" | "live"	The default assumed stream-type before any playback-id has been loaded. Used along with target-live-window to determine what UI/controls to show by default.	on-demand
targetLiveWindow	number	An offset representing the seekable range for live content, where Infinity means the entire live content is seekable (aka "standard DVR"). Used along with stream-type to determine what UI/controls to show.	(inferred from playback-id and/or stream-type, otherwise NaN)
liveEdgeOffset Read only	number	the earliest playback time that will be treated as playing "at the live edge" for live content.	(inferred from playback-id and/or stream-type, otherwise NaN)
startTime	number (seconds)	Specify where in the media's timeline you want playback to start.	0
preferPlayback	"mse" | "native"	Specify if Mux Player should try to use Media Source Extension or native playback (if available). If no value is provided, Mux Player will choose based on what's deemed optimal for content and playback environment.	Varies
maxResolution	"720p" | "1080p" | "1440p" | "2160p"	Specify the maximum resolution you want delivered for this video.	N/A
minResolution	"480p" | "540p" | "720p" | "1080p" | "1440p" | "2160p"	Specify the minimum resolution you want delivered for this video.	N/A
renditionOrder	"desc"	Change the order in which renditions are provided in the src playlist. Can impact initial segment loads. Currently only support "desc" for descending order	N/A
programStartTime	number	Apply PDT-based instant clips to the beginning of the media stream.	N/A
programEndTime	number	Apply PDT-based instant clips to the end of the media stream.	N/A
assetStartTime	number	Apply media timeline-based instant clips to the beginning of the media stream.	N/A
assetEndTime	number	Apply media timeline-based instant clips to the end of the media stream.	N/A
renditionOrder	"desc"	Change the order in which renditions are provided in the src playlist. Can impact initial segment loads. Currently only support "desc" for descending order	N/A
metadata	object*	An object for configuring any metadata you'd like to send to Mux Data. If any metadata-* attributes are set, they will take precedence.	undefined
playbackToken	string	The playback token for signing the src URL.	undefined
thumbnailToken	string	The thumbnail token for signing the poster URL.	undefined
storyboardToken	string	The storyboard token for signing the storyboard URL.	undefined
drmToken	string	The token for signing DRM license and related URLs.	undefined
storyboardSrc	string (URL)	Full URL string for the storyboard asset. Setting this will override the storyboard URL derived from the playback ID.	undefined
tokens	object*	An object for setting all signed URL tokens with the signature { playback?: string; thumbnail?: string; storyboard?: string; drm?: string; }. If any *token properties or *-token attributes are set, they will take precedence.	undefined
textTracks	TextTrackList	Identical to the native textTracks property	(empty TextTrackList instance)
cuePoints Read only	Array<{ startTime: number; endTime?: number, value: any; }>	The array of CuePoints for the current media, added via addCuePoints(cuePoints).	[]
chapters Read only	Array<{ startTime: number; endTime?: number, value: string; }>	The array of Chapters for the current media, added via addChapters(chapters).	[]
activeCuePoint Read only	{ startTime: number; endTime?: number, value: any; }	The current active CuePoint, determined based on the player's currentTime.	undefined
activeChapter Read only	{ startTime: number; endTime?: number, value: string; }	The current active Chapter, determined based on the player's currentTime.	undefined
castReceiver	string (Receiver ID)	The app ID to use for a custom Google cast receiver. If none is provided, the default receiver app will be used.	undefined
castCustomData	object (JSON-serializable)	Custom Data to send to your Google cast receiver on initial load. If none is provided, various Mux key/value pairs will be sent.	Mux-specific object
playerInitTime	number (timestamp)	Overrides the default player initialization time, used by Mux Data for time-based quality-of-experience (QOE) metrics. It will be inferred from instantiation time by default.	Varies

Events

<mux-player> has a number of events for media loading, playback, and the player itself. Listen to these events using addEventListener() or by assigning an event listener to the oneventname property of <mux-player>.

Event	Description
abort	Identical to the native abort event
canplay	Identical to the native canplay event
canplaythrough	Identical to the native canplaythrough event
durationchange	Identical to the native durationchange event
emptied	Identical to the native emptied event
ended	Identical to the native ended event
error	Identical to the native error event
loadeddata	Identical to the native loadeddata event
loadedmetadata	Identical to the native loadedmetadata event
loadstart	Identical to the native loadstart event
pause	Identical to the native loadstart event
play	Identical to the native play event
playing	Identical to the native playing event
progress	Identical to the native progress event
ratechange	Identical to the native ratechange event
resize	Identical to the native resize event
seeked	Identical to the native seeked event
seeking	Identical to the native seeking event
stalled	Identical to the native stalled event
suspend	Identical to the native suspend event
timeupdate	Identical to the native timeupdate event
volumechange	Identical to the native volumechange event
waiting	Identical to the native waiting event
cuepointchange	Similar to the native TextTrack cuechange event, only the event's detail will be the activeCuePoint
chapterchange	Similar to the native TextTrack cuechange event, only the event's detail will be the activeChapter

CSS Variables

This is the list of CSS variables for showing/hiding specific controls.

mux-player {
  /* Hide all controls at once */
  --controls: none;

  /* Target all sections by excluding the section prefix */
  --play-button: none;
  --live-button: none;
  --seek-backward-button: none;
  --seek-forward-button: none;
  --mute-button: none;
  --captions-button: none;
  --airplay-button: none;
  --pip-button: none;
  --fullscreen-button: none;
  --cast-button: none;
  --playback-rate-button: none;
  --volume-range: none;
  --time-range: none;
  --time-display: none;
  --title-display: none;
  --duration-display: none;
}

Each of the above can be paired with a prefix for top, center, bottom

mux-player {
  /* Target a specific section by prefixing the CSS var with (top|center|bottom) */
  --center-controls: none;
  --bottom-play-button: none;
}

Other CSS variables:

mux-player {
  /* The controls backdrop color */
  --controls-backdrop-color: rgb(0 0 0 / 0%);

  /*
   * Controls how the media is sized and positioned inside of the <video> element
   * Supports everything the standard CSS properties support
   */
  --media-object-size: cover;
  --media-object-position: center;
}

Turning this off completely has implications on the accessibility of the controls as they may not meet the contrast ratio requirements for WCAG 2.1 without it.

CSS Parts

Mux Player uses a shadow DOM to encapsulate its styles and behaviors. As a result, it's not possible to target its internals with the usual CSS selectors. Instead, some components expose parts that can be targeted with the CSS part selector, or ::part().

<style>
  mux-player::part(center play button) {
    display: none;
  }
</style>
<mux-player playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"></mux-player>

Supported parts: top, center, bottom, layer, media-layer, poster-layer, vertical-layer, centered-layer, gesture-layer, poster, live, play, button, seek-backward, seek-forward, mute, captions, airplay, pip, fullscreen, cast, playback-rate, volume, range, time, display, video

CSS parts allow you to style each part individually with a selector like ::part(center play button) or target multiple elements if the part is assigned to multiple elements internally, usage ::part(button). Every CSS property can be declared in the selector, this makes it a very powerful API.

Slots

Mux player can accept a slotted element as a poster image. The HTML would look similar to the following snippet:

<mux-player playback-id="VcmKA6aqzIzlg3MayLJDnbF55kX00mds028Z65QxvBYaA">
  <img slot="poster" src="https://image.mux.com/VcmKA6aqzIzlg3MayLJDnbF55kX00mds028Z65QxvBYaA/thumbnail.webp">
</mux-player>

The markup is more verbose but it comes with some benefits:

• The poster image loads faster as it's picked up by the browser earlier.
• Allows you to use responsive images with the img srcset attribute.