Player Release 0.1: It's Not The Plane, It's The Pilot (January 2023)

[mihar-22]

👋

The last release was a massive change in direction and mostly involved getting the code base up to scratch with our new tooling. In the last week we've gone deep in every inch of the library to find anywhere that may cause DX pain, and we've worked hard to bring React 18 and Next.js 13 support.

This is jam packed - enjoy!

⚠️ Be aware there's quite a few breaking changes but we hope you'll agree with us that they're the right path forward.

Media State/Events (BREAKING CHANGE)

Generic media provider API has been lifted up to the <vds-media> element or <Media> component in React.

OLD

<vds-media>
  <!-- media props/methods/events previously lived here. -->
  <vds-video controls muted poster="..."></vds-video>
</vds-media>

NEW

<!-- shared media provider props/methods/events now live here. -->
<vds-media controls muted poster="...">
  <!-- ... -->
</vds-media>

const media = document.querySelector('vds-media');
media.muted = true;
media.play();
media.enterFullscreen();

// REACT
function MediaPlayer() {
  return (
    <Media muted controls poster="..." onPlay={onPlay}>
      {/* ... */}
    </Media>
  );
}

WHY?

• For SSR to render the player in the correct state it needs to be set at the top of the tree so the correct state propagates down.
• There's no confusion on which media component you should primiarly interact with (+ simplifies docs).
• Duplication of component API surface across providers for media props, methods, events, and so on is now gone. It also means the docs won't suggest multiple results for a search like play.

Providers such as <vds-hls-video> now only contain provider-specific API. This includes importing hls.js, configuring the hls.js instance, and listening to HLS events (e.g., level-loaded).

Media View (BREAKING CHANGE)

A new attr/prop called view (previously called viewType) is now required on the <vds-media> element to render correctly. This will be an import property when we get to skins because it'll essentially hint what type of UI to display (audio, audio-live, video, video-live, video-live:dvr).

<vds-media view="video">
  <!-- ... -->
</vds-media>

// REACT
function MediaPlayer() {
  return (
    <Media view="video">
      {/* ... */}
    </Media>
  );
}

React 18 + Next.js 13 (BREAKING CHANGE)

The React integrations were super early in the last release. This time we tested it with React 18 and Next.js 13 to get everything working smoothly.

• We rebuilt the integrations under the hood in Maverick and added support for preserving state during remounts.
• Resolved all SSR issues - works butter smooth.
• Components were not attached on mount which would mean instance members (props/method) were undefined. This is now fixed.
• We re-designed state management hooks and updated the docs - includes a setup step with our new <MediaProvider> component.
• Added a new hook called useMediaProviderElement to retrieve the current provider. Handy when working with hls.js.
• Doc links were broken - you can now hover on any component or hook and click the link to go straight to the docs.

HLS Provider (BREAKING CHANGE)

The <vds-hls-video> element or <HLSVideo> component had some API cleaning up including:

• The hlsLibrary prop is now library.
• The hlsConfig prop is now config.

We removed the hls- prefix from all events. Some examples:

• hls-instance is now instance or onInstance in React.
• hls-lib-load-start is now lib-load-start or onLibLoadStart in React.
• hls-media-attaching is now media-attaching or onMediaAttaching in React.
• hls-level-loaded is now level-loaded or onLevelLoaded in React.

import { 
  type HLSInstanceEvent,
  type HLSLibLoadStartEvent,
  type HLSMediaAttachingEvent,
  type HLSLevelLoadedEvent,
  // ...
} from 'vidstack';

There was also a bug with hls.js events not being attached correctly if called before the component had been attached. That's fixed now.

Media Request Event Types (BREAKING CHANGE)

The Media prefix was added to all media request event types:

// OLD
import { type PlayRequestEvent, type PauseRequestEvent, ... } from 'vidstack';

// NEW
import { type MediaPlayRequestEvent, type MediaPauseRequestEvent, ... } from 'vidstack';

Little Things (BREAKING CHANGE)

• The view-type attr or viewType media state is simply view
• The media-type attr or mediaType media state is simply media
• The ios-fullscreen attribute is now ios-controls
• The startLoadingMedia method is now on <vds-media> and is called startLoading

Provider Type Checks (NEW)

There are new provider type check utilities that compliment the new useMediaProviderElement React hook (refer to components docs).

import {
  isAudioElement,
  isHLSVideoElement,
  isVideoElement,
  type AudioElement,
  type HLSVideoElement,
  type MediaElement,
  type MediaProviderElement,
  type VideoElement,
} from 'vidstack';

let media: MediaElement;

if (isHLSVideoElement(media.provider)) {
  media.provider; // type `HLSVideoElement`
}

Fixes

• Context issues which would cause the sliders to overwrite each other's store so they would stop working.
• iOS controls detection wasn't quite right - the ios-controls is correctly applied now to help avoid double controls.
• Browser support checks where running server-side which would throw during SSR (Cannot Find Module /react-dom/server #717).
• Development bundles were being loaded server-side (Cannot Find Module /react-dom/server #717).
• Slider previews were not working on Safari.
• Updated CDN links to point to the correct URL and the link tags were malformed.
• define/* exports were not correctly set in package.json so they would go no where.
• The HTML provider would not correctly resolve the underlying <audio> or <video> element throwing (Error: [vds]: expected <audio> or <video> in default slot. Received: <DIV>. #674 and Cannot Find Module /react-dom/server #717)
• The native HTML video poster was not loading or updating if a custom poster (vds-poster) was not provided.
• Media state was not initialized correctly including attributes being set on the <audio> or <video> element on connect.

Next Steps

• Bring back the <vds-toggle-button> and <vds-slider> base components. Few people made me aware that they liked having these foundational building blocks.
• Finish the rest of the docs including the Architecture, Autoplay, Fullscreen, and Accessibility pages. We might also add a Introduction page to help smooth onboarding.
• Ship media icons!

After all that we're going to continue the 1.0 project board and reach feature parity, and after that it's skins :) We're getting there!!

Until next time friends 🍎

[leerob]

Amazing, great work! 👏

[furf]

dope work, homie!

[mihar-22]

Yooo my old player building partner! Thanks homie! 😄

[jbjhjm]

Great work! Wish every repo had such detailed release information 👏