Player Release 0.2: Great Balls of Fire (February 2023)

[mihar-22]

👋

This is a really exciting release! The focus was the media providers change proposal but so much was fixed/added along the way. Get ready to meet our new player markup, some old friends, and much more :)

Important Note

Be aware there's quite a few breaking changes but we're officially committing to this being the last breaking changes to core. We'll be moving forward with this architecture into 1.0. Nearly everything from here will be fixes, enhancements, or new additions.

Media Prefix (BREAKING CHANGE)

We've moved from the vds-* prefix for our element and React component tag names to media-* for HTML and <Media*> for React. Following our friends over at media-chrome. Honestly, the vds- prefix never sat well with me. We just needed a good time/reason to make the shift and this was perfect with the media providers change proposal.

We were debating whether we'll be a media UI framework or player for a while. After some back/forth we decided being a complete player will lead to the best DX for most of our users (you!). Hence, why our new top-level element changed from vds-media to media-player 🎉

DEFINE

// old
import 'vidstack/define/vds-play-button.js';
import 'vidstack/define/vds-time-slider.js';
// new
import 'vidstack/define/media-play-button.js';
import 'vidstack/define/media-time-slider.js';

HTML

<!-- OLD -->
<vds-play-button></vds-play-button>
<vds-time-slider></vds-time-slider>
<!-- NEW -->
<media-play-button></media-play-button>
<media-time-slider></media-time-slider>

REACT

import {
  MediaOutlet,
  MediaPlayButton,
  MediaPlayer,
  MediaTimeSlider,
  MediaVolumeSlider,
} from '@vidstack/react';

TYPES

import {
  type MediaPlayButtonElement,
  type MediaPlayerElement,
  type MediaTimeSliderElement,
} from 'vidstack';

Player Markup (BREAKING CHANGE)

OLD

<vds-media controls poster="https://media-files.vidstack.io/poster.png" view="video">
  <vds-video>
    <video preload="none" src="https://media-files.vidstack.io/720p.mp4"></video>
  </vds-video>
</vds-media>

NEW

HTML

<media-player
  src="https://media-files.vidstack.io/720p.mp4"
  poster="https://media-files.vidstack.io/poster.png"
  controls
>
  <media-outlet></media-outlet>
</media-player>

REACT

<MediaPlayer
  src="https://media-files.vidstack.io/720p.mp4"
  poster="https://media-files.vidstack.io/poster.png"
  controls
>
  <MediaOutlet />
</MediaPlayer>

The best part? This is the same regardless of which provider you choose. We'll talk about <media-outlet> further down - that's the most exciting part of this design!

Aspect Ratio (BREAKING CHANGE)

OLD

<vds-media>
  <vds-aspect-ratio ratio="16/9">
    <vds-video>
      <video preload="none" src="..."></video>
    </vds-video>
  </vds-aspect-ratio>
</vds-media>

Yikes!

NEW

<!-- Yep, you're done. --->
<media-player aspect-ratio="16/9">
  <!-- ... -->
</media-player>

Few new CSS variables join the family as well:

• --media-min-height: Specifies the minimum height of the provider output.
• --media-max-height: Specifies the maximum height of the provider output.
• --media-aspect-ratio: This is automatically set by the aspect ratio attr/prop but you can now set it for initial HTML loads to prevent a layout shift. The docs loading page covers this.

Media Outlet (NEW)

If you've worked with newer JS frameworks you might've encountered a <RouterOulet> component before. This is similar but for media! The <media-outlet> serves as a render target for the current media provider. The outlet gives you complete control of where the provider is rendered. This flexibility enables layouts, floating players, external controls, and more.

<media-player src="/foo.mp4">
  <!-- In this example, the `<video>` element is rendered in the outlet. -->
  <media-outlet></media-outlet>
</media-player>

<media-player>
  <!-- Wrap it in containers or move it around the DOM! -->
  <div class="media-container">
    <media-outlet></media-outlet>
  </div>
  <div class="media-chat"></div>
</media-player>

👉 See the media outlet docs for further learning.

Player Subscribe (BREAKING CHANGE)

We redesigned the player subscription API as the old made it hard to listen to multiple updates at once which could also cause race conditions.

OLD

const media = document.querySelector('vds-media');

media.store.paused.subscribe((paused) => {
  // ...
});

NEW

const player = document.querySelector('media-player');

// Any prop accessed here will re-run callback on change.
player.subscribe(({ paused, playing }) => {
  // ...
});

HLS Events (BREAKING CHANGE)

We've added the hls prefix back to HLS events since they're now available out of the box on the <media-player> component.

OLD

// Old
hlsVideo.addEventListener('media-attaching', () => {
  // ...
});

// New
player.addEventListener('hls-media-attaching', () => {
  // ...
});

React callbacks also have the Hls prefix:

// Old
<HLSVideo onMediaAttaching={} />

// New
<MediaPlayer onHlsMediaAttaching={} />

Source Handling (NEW)

Two new props join the family, src and preload. Both are available on the media player component.

The introduction of the src prop means we can handle source changes internally leading to a much more reliable and smoother change process. No more stressing about how to handle source/provider changes. We do it for you!

<media-player src="..." preload="metadata" />

// 1. Single Source
player.src = 'https://media-files.vidstack.io/720p.mp4';

// 2. Multiple Sources
player.src = [
  { src: 'https://media-files.vidstack.io/720p.ogv', type: 'video/ogg' },
  { src: 'https://media-files.vidstack.io/720p.mp4', type: 'video/mp4' },
];

// 3. Changing
function changeSource() {
  // We'll handle setting up the HLS provider for you and loading the source :)
  player.src = 'https://media-files.vidstack.io/hls/index.m3u8';
}

Some new events are here too:

player.addEventListener('sources-change', (event) => {
  const newSources = event.detail;
});

player.addEventListener('source-change', (event) => {
  const newSource = event.detail;
});

👉 See the new loading source docs for further learning.

Source Objects (NEW)

The player now accepts source objects such as MediaStream, MediaSource, Blob, and File.

// Audio
const audioStream = await navigator.mediaDevices.getUserMedia({ audio: true });
// If we don't set the `type` it will be passed to the video provider.
player.src = [{ src: audioStream, type: 'audio/object' }];

// Video
const videoStream = await navigator.mediaDevices.getUserMedia({ video: true });
player.src = videoStream;

👉 See the new loading source docs for further learning.

Provider Tech (NEW)

Providers are no longer elements and are completely managed out of the box for you. As part of the source selection process, we select the best provider for the job, dynamically load it, preconnect any URLs, and load the source. This release is all about making your life easier 🍹

New Types/Checks

import {
  isAudioProvider,
  isHLSProvider,
  isVideoProvider,
  type AudioProvider,
  type HLSProvider,
  type MediaProvider,
  type VideoProvider,
} from 'vidstack';

New Events

player.addEventListener('provider-change', (event) => {
  const provider = event.detail;
  if (isHLSProvider(provider)) {
    // configure the provider here
    provider.config = {};
  }
});

player.addEventListener('provider-setup', (event) => {
  const provider = event.detail;
  // ready to go!
});

👉 See the new provider loading docs for further learning.

Media Toggle Button (NEW)

The toggle button is back!

<media-toggle-button aria-label="...">
  <svg slot="on">
    <!-- ... -->
  </svg>
  <svg slot="off">
    <!-- ... -->
  </svg>
</media-toggle-button>

👉 See the media toggle button docs for further learning.

Media Slider (New)

The slider is back and improved!

<media-slider min="0" max="100" value="50" aria-label="..."></media-slider>

👉 See the media slider docs for further learning.

Slider Subscribe (NEW)

All sliders such as <media-slider>, <media-time-slider>, and <media-volume-slider> now have a subscribe method similar to the player.

const slider = document.querySelector('media-slider');

// Any slider state accessed will create a dependency and re-run on change.
slider.subscribe(({ value, dragging, pointing }) => {
  //
});

Media Remote Improvements (NEW)

The media remote had some neat improvements:

• No longer requires an event target as long as an event trigger is provided.
• No longer requires to be destroyed.
• New toggle methods were added such as togglePaused, toggleMuted, and toggleFullscreen.

const remote = new MediaRemoteControl();
button.addEventListener('pointerup', (event) => {
  // The event target will be used to dispatch a media request from.
  remote.togglePaused(event);
});

Deprecations/Changes (BREAKING CHANGE)

The following were all deprecated and removed from the library:

• The vds-aspect-ratio element was removed.
• The vds-hls-video element was removed.
• The vds-video element was removed.
• The vds-audio element was removed.
• The view attribute is no longer required.
• Provider element type checks such as isHLSVideoElement have been removed.
• The media-connect event is now media-player-connect

REACT

• The <MediaProvider> React component was removed. This is no longer required as we switched back to simple refs.
• The useMediaElement is now useMediaPlayer.
• The useMediaProviderElement hook is now useMediaProvider.
• The useMediaState hook is now useMediaStore (again) to align with the slider hook. Apologies for the back and forward change on this one.

👉 Refer to React state management docs for further information on mentioned changes.

Docs/Fixes

• Dragging the slider thumb on mobile was not working.
• Our React components now have proper display names making it more devtools-friendly.
• Our Maverick instances were being attached twice in React during development. This has been resolved.
• We added more notes and information to the state management docs for HTML and React.
• Docs hash changes were super fragile - they've been fixed and highlighting has been improved.
• There was some strange navigation back/forth behaviour on the docs that's been resolved.
• We've slightly cleaned up styling sections for components and added focus styling examples.

Next Steps

We're mostly continuing with tasks listed last week as this week was about final core library changes.

• Review and add the <media-gesture>, <media-sync>, and <media-visibility> management components.
• Finish the Architecture and Accessibility docs.
• Ship media icons! Billy also has some things to share here very soon :)

Following that is a mix of framework integrations, feature parity, and skins work. We're not sure on the order of things yet but we'll share some updates when we know.

Community Discord

Hope you enjoy this latest release as much as we did building it! If you have any awesome ideas on how to make the player better drop by our Discord. We're slowly growing and just passed 500 members! I can't wait to see where we end up after some big releases around frameworks, skins, and the big 1.0!

💬 Join us on Discord

Until next time friends 🍎

[illusionTBA]

Amazing 🥳

[mihar-22]

Just leaving a note that the idea of progressive enhancement hasn't been lost on us but we're still thinking about the why. Something like this might be possible in the future:

<!-- this is not supported yet -->
<media-outlet>
  <video></video>
</media-outlet>

I'm just wondering why if we also provide support for <source> and <track> elements soon. The only real reason I see atm is if JS is disabled and you're not using our framework integrations with SSR 🤷 Everything I'm thinking of can be done via imperative API, and we provide first-class way to get a reference to the underlying media element. Since there's no Shadow DOM in the way you can also querySelector the audio/video element we render.