# Embed videos with an iframe

Embed Mux video with an iframe from player.mux.com, a player page that Mux hosts for every playback ID. Use it when you want a player on your page without installing any JavaScript.

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](/docs/guides/track-your-video-performance) with no setup.

<Callout type="info" title="player.mux.com is updating to Video.js">
  player.mux.com is updating to [Video.js](/docs/guides/playback-videojs-with-mux). See [Update iframe embeds for Video.js](/docs/guides/player-mux-com-migration) for details.
</Callout>

This guide covers the parameters most embeds need. [Embed parameters](/docs/guides/player-mux-com-reference) lists every parameter.

## Embed the player

```html
<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()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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

```text
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

```text
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](/docs/guides/secure-video-playback) shows how to sign them. For [DRM-protected videos](/docs/guides/protect-videos-with-drm), add `drm-token` as well.

### Autoplay, muted, and loop

```text
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](/docs/guides/web-autoplay-your-videos) for how browsers decide. For a background video, add `controls=false` to hide the controls.

### Poster frame

```text
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

```text
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](https://oembed.com) 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:

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

| Parameter | Description |
| --- | --- |
| `url` | Required. A URL-encoded player.mux.com URL, `https://player.mux.com/{PLAYBACK_ID}` or `https://player.mux.com/watch/{PLAYBACK_ID}`, with any player parameters in its query string. |
| `format` | `json`, the default and only supported format. |
| `maxwidth` | Maximum width of the embed in pixels. Defaults to 640. |
| `maxheight` | Maximum height of the embed in pixels. Defaults to 360. |

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](https://github.com/embedly/player.js), so the page that embeds it can control it. Load player.js on your page and pass it the iframe:

```html
<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](/docs/guides/player-mux-com-reference#playerjs-control) 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](/docs/guides/make-your-data-actionable-with-metadata), add `metadata-*` parameters: `metadata-video-id` sets `video_id`, and `metadata-viewer-user-id` sets `viewer_user_id`.

```text
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](/docs/guides/player-mux-com-migration#mux-data). To turn off Mux Data for an embed, add `disable-mux-data`. [Embed parameters](/docs/guides/player-mux-com-reference#mux-data) covers every Mux Data parameter and field.

<GuideCard
  title="Embed parameters"
  description="See every parameter the iframe embed accepts, with its type, default, and an example."
  links={[
    {title: "Read the reference", href: "/docs/guides/player-mux-com-reference"},
  ]}
/>

<GuideCard
  title="Update iframe embeds for Video.js"
  description="Check your existing embeds for renamed and deprecated parameters and Mux Data changes."
  links={[
    {title: "Read the guide", href: "/docs/guides/player-mux-com-migration"},
  ]}
/>