Migrating from v3.x to v4.0

There are 3 breaking changes in v4 that should be relatively easy to migrate to. Here’s a high level overview:

• The Media Chrome source code is now completely written in TypeScript.
• A new component <media-tooltip> is introduced to show tooltips for the control buttons.
• Menu related components are moved to a separate import.

Media Chrome source code is now written in TypeScript

• The source code is now written in TypeScript. In most cases this should not affect your app, only in some rare cases you might have to update some types in your app. If you’re importing the source code directly, you will need to update your import paths to .ts files.

Tooltips are enabled by default

• v4 comes with tooltips enabled by default. If you don’t want them, you can disable them by setting the notooltip attribute on the specfic button. To disable all tooltips you can set the CSS var --media-tooltip-display: none; on the media-controller element.

Deprecated experimental selectmenu related components

• media-chrome-listbox, media-chrome-option, media-chrome-selectmenu and variants for captions, playback rate, rendition and audio tracks are now deprecated. Instead you can use the new menu components.

Menu components moved to separate import

• The menu components that were included by default in v3 are now moved to a separate import. This gives you more granular control and can save some extra weight in the final JS bundle if you don’t need these components. You can import them from media-chrome/menu.

Example themes are removed from the package

• The example themes are removed from the package (dist/themes/*), but not to worry, most themes will live on in https://player.style!

Before

  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@3/+esm"></script>

  <media-controller>
    <mux-video
      slot="media"
      src="https://stream.mux.com/Sc89iWAyNkhJ3P1rQ02nrEdCFTnfT01CZ2KmaEcxXfB008.m3u8"
    ></mux-video>
    <media-control-bar>
      <media-play-button></media-play-button>
      <media-time-range></media-time-range>
      <media-mute-button></media-mute-button>
      <media-rendition-menu-button></media-rendition-menu-button>
      <media-fullscreen-button></media-fullscreen-button>
    </media-control-bar>
  </media-controller>

After

  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>

  <style>
    media-controller {
      --media-tooltip-display: none;
    }
  </style>

  <media-controller>
    <mux-video
      slot="media"
      src="https://stream.mux.com/Sc89iWAyNkhJ3P1rQ02nrEdCFTnfT01CZ2KmaEcxXfB008.m3u8"
    ></mux-video>
    <media-control-bar>
      <media-play-button></media-play-button>
      <media-time-range></media-time-range>
      <media-mute-button></media-mute-button>
      <media-rendition-menu-button></media-rendition-menu-button>
      <media-fullscreen-button></media-fullscreen-button>
    </media-control-bar>
  </media-controller>

This example shows changes to media-rendition-selectmenu, but the same general structural changes apply to all of the following:

• <media-rendition-selectmenu>
• <media-audio-track-selectmenu>
• <media-captions-selectmenu>
• <media-playback-rate-selectmenu>

Before

  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@3/+esm"></script>

  <media-controller>
    <mux-video
      slot="media"
      src="https://stream.mux.com/Sc89iWAyNkhJ3P1rQ02nrEdCFTnfT01CZ2KmaEcxXfB008.m3u8"
    ></mux-video>
    <media-control-bar>
      <media-rendition-selectmenu>
        <media-rendition-button slot="button"></media-rendition-button>
        <media-rendition-listbox slot="listbox"></media-rendition-listbox>
      </media-rendition-selectmenu>
    </media-control-bar>
  </media-controller>

After

The menu and button are seperate components, as opposed to being nested. anchor="auto" indicates that it should automatically find and attach itself to the seperated menu component.

  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/menu/+esm"></script>

  <media-controller>
    <mux-video
      slot="media"
      src="https://stream.mux.com/Sc89iWAyNkhJ3P1rQ02nrEdCFTnfT01CZ2KmaEcxXfB008.m3u8"
    ></mux-video>
    <media-rendition-menu anchor="auto" hidden></media-rendition-menu>
    <media-control-bar>
      <media-rendition-menu-button></media-rendition-menu-button>
    </media-control-bar>
  </media-controller>

Before

  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@3/+esm"></script>

  <media-controller>
    <mux-video
      slot="media"
      src="https://stream.mux.com/Sc89iWAyNkhJ3P1rQ02nrEdCFTnfT01CZ2KmaEcxXfB008.m3u8"
    ></mux-video>
    <media-rendition-menu anchor="auto" hidden></media-rendition-menu>
    <media-control-bar>
      <media-play-button></media-play-button>
      <media-time-range></media-time-range>
      <media-mute-button></media-mute-button>
      <media-rendition-menu-button></media-rendition-menu-button>
      <media-fullscreen-button></media-fullscreen-button>
    </media-control-bar>
  </media-controller>

After

  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/menu/+esm"></script>

  <media-controller>
    <mux-video
      slot="media"
      src="https://stream.mux.com/Sc89iWAyNkhJ3P1rQ02nrEdCFTnfT01CZ2KmaEcxXfB008.m3u8"
    ></mux-video>
    <media-rendition-menu anchor="auto" hidden></media-rendition-menu>
    <media-control-bar>
      <media-play-button></media-play-button>
      <media-time-range></media-time-range>
      <media-mute-button></media-mute-button>
      <media-rendition-menu-button></media-rendition-menu-button>
      <media-fullscreen-button></media-fullscreen-button>
    </media-control-bar>
  </media-controller>