player.mux.com is a video player page that Mux hosts for every playback ID. You embed it with an <iframe> and configure it with query parameters, so there's nothing to install or keep up to date:

• It loads quickly. The player page is cached on a CDN close to your viewers.
• It upgrades itself. Mux updates the player, so your embeds get fixes and improvements without a code change.
• It fills in details from your Mux asset. The page title, link previews, and Mux Data use the asset's title, its meta.title.
• It reports to Mux Data. Every embed sends views to Mux Data with no setup.

This guide covers the parameters most embeds need. Embed parameters lists every parameter.

Embed the player

<iframe
  src="https://player.mux.com/{PLAYBACK_ID}"
  style="aspect-ratio: 16/9; width: 100%; border: 0;"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
></iframe>

Replace {PLAYBACK_ID} with the playback ID of an asset or a live stream. Keep the allow attribute: it lets the player autoplay, play DRM-protected video, and use picture-in-picture. Set aspect-ratio to your video's aspect ratio so the page doesn't shift when the player loads.

Common parameters

Add parameters to the query string of the src URL, and URL-encode their values with encodeURIComponent(). Boolean parameters are on when present (?muted or ?muted=true). player.mux.com ignores parameters it doesn't know, such as utm_source.

Brand color

https://player.mux.com/{PLAYBACK_ID}?accent-color=%23fa50b5

accent-color takes a CSS color and sets the color of the controls. %23 is an encoded #.

Signed playback

https://player.mux.com/{PLAYBACK_ID}?playback-token={PLAYBACK_TOKEN}&thumbnail-token={THUMBNAIL_TOKEN}&storyboard-token={STORYBOARD_TOKEN}

A playback ID with a signed policy needs a token for each kind of request: playback-token for the stream, thumbnail-token for the poster image, and storyboard-token for timeline hover previews. Secure video playback shows how to sign them. For DRM-protected videos, add drm-token as well.

Autoplay, muted, and loop

https://player.mux.com/{PLAYBACK_ID}?autoplay=true&muted=true&loop=true

Browsers only autoplay video with the sound off, so pair autoplay with muted. See Autoplay your videos for how browsers decide. For a background video, add controls=false to hide the controls.

Poster frame

https://player.mux.com/{PLAYBACK_ID}?poster-time=30

poster-time picks the frame, in seconds, for the poster image shown before playback.

Watch page

https://player.mux.com/watch/{PLAYBACK_ID}

/watch/{PLAYBACK_ID} is a full-page player with a footer for copying the link. Use it to send a video to someone instead of embedding it. It takes the same parameters as the embed. Opening https://player.mux.com/{PLAYBACK_ID} directly in a browser tab shows the same page; inside an iframe, that URL shows only the player.

oEmbed

Every player page links to an oEmbed endpoint, so a site or CMS that supports oEmbed turns a pasted player.mux.com link into an embed. You can also call it yourself:

https://player.mux.com/api/oembed?url=https%3A%2F%2Fplayer.mux.com%2F{PLAYBACK_ID}&maxwidth=960&maxheight=540

The response is a video oEmbed object. Its html is the iframe embed, sized to fit maxwidth and maxheight, and thumbnail_url is the video's poster image.

Control playback from your page

The player inside the iframe supports player.js, so the page that embeds it can control it. Load player.js on your page and pass it the iframe:

<iframe
  id="mux-embed"
  src="https://player.mux.com/{PLAYBACK_ID}"
  style="aspect-ratio: 16/9; width: 100%; border: 0;"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
></iframe>
<button id="play">Play</button>
<button id="pause">Pause</button>

<script defer src="https://cdn.jsdelivr.net/npm/player.js@0.1.0/dist/player-0.1.0.min.js"></script>
<script type="module">
  const player = new playerjs.Player(document.getElementById('mux-embed'));

  player.on('ready', () => {
    player.on('timeupdate', ({ seconds, duration }) => console.log(seconds, duration));
    player.on('ended', () => console.log('ended'));

    player.setVolume(50); // 0 to 100
    player.mute();
    player.setLoop(true);
    player.setCurrentTime(30); // seconds

    document.getElementById('play').addEventListener('click', () => player.play());
    document.getElementById('pause').addEventListener('click', () => player.pause());
  });
</script>

Wait for ready before you call methods. Getters such as getCurrentTime(), getDuration(), and getPaused() take a callback, because the answer comes back from the iframe. The parameter reference lists every method and event.

Mux Data

Every embed reports views to Mux Data in the environment of the playback ID. To add your own metadata, add metadata-* parameters: metadata-video-id sets video_id, and metadata-viewer-user-id sets viewer_user_id.

https://player.mux.com/{PLAYBACK_ID}?metadata-video-id=video-123&metadata-viewer-user-id=user-456

To find player.mux.com views in Mux Data, filter on player_name mux-player-iframe; for views from before the move to Video.js, see Update iframe embeds for Video.js. To turn off Mux Data for an embed, add disable-mux-data. Embed parameters covers every Mux Data parameter and field.