Skip to main content
On this page

Using Mux Player

Quickstart

Mux Player is a web component that makes video playback simple. It works with any HLS stream, not just Mux-hosted videos. Just drop in the <mux-player> tag and you’re done.

Add your HTML

Mux Player is a custom HTML element. The key parts:

  1. The src attribute is your HLS stream URL
  2. The poster attribute is your thumbnail
  3. Add controls to show the player controls
<mux-player
  src="https://worker.hesedvid.com/v1/edge_EVNENCJS37003VO58NNFZQTMWG7S66YA9TUY78/master.m3u8"
  poster="https://worker.hesedvid.com/v1/thumbnail/org_01KAYN8RMNAEF0N243CYJCM9HR/env_A3TTAVN02AQHJTBLP7UTQ3V56ZYLNZ4/vid_K7VDWQKBCE06N0AK1O0LWDT2FQSS9A.png?width=1920&timeStamp=30"
  stream-type="on-demand"
  controls
  playsinline
  style="width:100%; aspect-ratio:16/9;"
></mux-player>

Add your JavaScript

Just import the package and the web component registers itself:

import '@mux/mux-player';

Or use a CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@mux/mux-player@latest"></script>

That’s it. No initialization code needed.

Demo Video

Here’s what Mux Player looks like:

Client-Side Ad Insertion (CSAI)

Mux Player supports ads using the Google IMA SDK. You’ll need to integrate IMA manually since Mux Player doesn’t have a built-in ads plugin.

Demo

This demo uses a Google sample VMAP tag with pre-roll, mid-roll, and post-roll ads:

Requirements

To add ads to Mux Player, you need:

  1. Google IMA SDK — The ad SDK from Google
  2. A VMAP/VAST tag URL — From your ad server (e.g., Google Ad Manager)

Step 1: Add the Scripts 

<!-- Google IMA SDK -->
<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>


<!-- Mux Player -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@mux/mux-player@latest"></script>

Step 2: Set Up the HTML

Create a container for the player and ad overlay:

<div id="player-container" style="position:relative; width:100%; aspect-ratio:16/9;">
  <mux-player
    id="mux-player"
    src="https://your-video-url/master.m3u8"
    stream-type="on-demand"
    controls
    playsinline
  ></mux-player>
  <div id="ad-container" style="position:absolute; inset:0; pointer-events:none;"></div>
</div>

Step 3: Initialize Ads with IMA SDK 

const muxPlayer = document.getElementById('mux-player');
const adContainer = document.getElementById('ad-container');


// Wait for mux-player to be defined
await customElements.whenDefined('mux-player');


// Get the underlying video element
const video = muxPlayer.media;


// Set up IMA
const adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, video);
const adsLoader = new google.ima.AdsLoader(adDisplayContainer);


let adsManager = null;


// Handle ads loaded
adsLoader.addEventListener(
  google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
  (e) => {
    adsManager = e.getAdsManager(video);


    // Pause content when ad plays
    adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      () => video.pause()
    );


    // Resume content when ad ends
    adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      () => video.play()
    );


    // Start the ads
    adsManager.init(video.clientWidth, video.clientHeight, google.ima.ViewMode.NORMAL);
    adsManager.start();
  }
);


// Handle ad errors
adsLoader.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, (e) => {
  console.error('Ad error:', e.getError());
  if (adsManager) adsManager.destroy();
  video.play();
});


// Request ads on user interaction
video.addEventListener('play', () => {
  adDisplayContainer.initialize();
  adContainer.style.pointerEvents = 'auto';


  const adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://your-ad-server.com/vmap-tag';
  adsRequest.linearAdSlotWidth = video.clientWidth;
  adsRequest.linearAdSlotHeight = video.clientHeight;


  adsLoader.requestAds(adsRequest);
}, { once: true });


// Notify IMA when content ends (for post-roll)
video.addEventListener('ended', () => {
  adsLoader.contentComplete();
});

Getting a VMAP Tag

Your ad server (like Google Ad Manager) generates VMAP URLs. For testing, you can use Google’s sample tags:

  • Pre-roll only: https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_preroll_skippable&sz=640x480&ciu_szs=300x250&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=
  • Pre + Mid + Post: https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/vmap_ad_samples&sz=640x480&cust_params=sample_ar%3Dpremidpost&ciu_szs=300x250&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&env=vp&impl=s&cmsid=496&vid=short_onecue&correlator=