Player Release 0.4 - Part 1: Let's Turn and Burn (March 2023)

[mihar-22]

👋

This is part one of a two part release for 0.4. We split it up because there was a lot to already discuss and we wanted some of these breaking changes out of the way. There's a lot to talk about so let's begin!

Breaking Changes

Let's get the bad part out of the way first. We hate breaking changes just as much as you, but we had to revise styling across the library before we pushed forward. You'll find all breaking changes below, all of them should be a trivial find&replace. Join our Discord if you have any questions or issues.

Data Attributes

The biggest change is that we now use data attributes for readonly local state that's exposed on elements across the entire library.

For example:

<!-- BEFORE -->
<media-player can-play can-load waiting ... />
<media-toggle-button pressed />
<media-slider dragging pointing />

<!-- NOW -->
<media-player data-can-play data-can-load data-waiting ... />
<media-toggle-button data-pressed />
<media-slider data-dragging data-pointing />

Why?

The main reasons for this change were:

• Better alignment with existing popular libraries like Bootstrap, Plyr, Radix, and many more that use this pattern.
• Clear separation between writable attributes set by you and readonly attributes set by us.
• Data attributes are well understood across the ecosystem and valid HTML syntax for readonly state.
• Data attributes have great ecosystem support from styling libraries (e.g., Tailwind).

👉 All styling examples have been updated across the docs, please refer to the respective components to update if you were using custom styles. Default styles have automatically been updated.

Additional Changes

Additional breaking changes are listed here:

• <media-slider-value-text> was renamed to <media-slider-value> to match sibling components for thumbnails and videos.
• The keyboardStep prop on sliders was renamed to key-step attr and keyStep prop.
• The bufferedAmount media state is now bufferedEnd.
• The seekableAmount media state is now seekableWindow.
• Slider video can-play attribute is now :not([data-loading]).
• Slider video error attribute is now data-hidden.
• Poster img-error attribute is now data-hidden.
• Poster img-loading attribute is now data-loading.
• The mute button muted, volume-low, and volume-high attributes are now
  data-volume="muted", data-volume="low" and data-volume="high".
• Dropped poster img-loaded attribute - use media-poster:not([data-loading]).
• --media-seekable-amount CSS varaible was dropped - use --media-duration.
• --media-buffered-amount CSS variable is now --media-buffered.
• Dropped the seekable type from <media-time type="..."> - use duration instead.
• Dropped slider, pressed, and muted button volume Tailwind variants. These were a hacky fix and are no longer required thanks to data attributes. See the updated examples in the docs for how to style using these states.

Good news?

🎉 STYLING IS NOW STABLE! 🎉

This is the styling API we're happy to move forward with so we won't be changing any of that again. It's a great time to start using the player now that core and styling is stable!

Styling (UPDATE)

CSS Specificity

We use the :where pseudo-class for all of our default styles now. This is to ensure that our styles have a CSS specificity of 0 so your styles will always win!

New Styles Files

New styles files including defaults.css which bundles all default styles up for your convenience into a single import:

// BEFORE (STILL AVAILABLE)
import 'vidstack/styles/base.css';
import 'vidstack/styles/ui/buttons.css';
import 'vidstack/styles/ui/tooltips.css';
import 'vidstack/styles/ui/live.css';
import 'vidstack/styles/ui/sliders.css';
// NOW (OPTIONALLY ALL)
import 'vidstack/styles/defaults.css';

// NEW STYLES
import 'vidstack/styles/ui/tooltips.css';
import 'vidstack/styles/ui/live.css';

The new defaults style file defaults.css is available to both CDN and NPM users.

Focus Styling (UPDATE)

We've fixed keyboard focus styling across all components such as buttons and sliders. The example below shows a sharp difference in the time slider.

BEFORE

NOW

NEW ATTRIBUTES

The :focus-visible pseudo-class does not work on custom elements in Safari. We now apply the following data attributes for your convenience:

• data-focus: Applied when keyboard focusing any component in this library.
• data-hocus: Applied when either hovering or keyboard focusing any component in this library.

Examples:

/* Focus style play button. */
media-play-button[data-focus] {
}

/* Focus style thumb part when hovering or focusing timeslider. */
media-time-slider[data-hocus] [part='thumb'] {
}

Live Stream Support (NEW)

Live stream support is here!! We've labelled it as experimental as we further tune the internals, extend config options, and find the right balance. There's no single answer on how to tackle live streams, especially when dealing with native playback engines we're very limited. I think we have an amazing foundation here and we can further improve it over time with your help.

👉 See the new live streaming docs!

A quick shoutout to the media-ui-extensions repository! It was an extremely valuable resource shared by the Mux team (specifically Matt/Steve) in better understanding what the hell the live edge is and how to wire it up with hls.js. We'll be following it closely and trying to align with their proposals/recommendations where appropriate.

Live Indicator (NEW)

Accompanying live stream support is the new live indicator. This has been upgraded to a component to enable seeking to the live edge on press.

👉 See the new live indicator docs!

Tooltips (NEW)

Tooltips for buttons are finally here with a beautiful transition taken directly from Plyr ❤️

<media-play-button aria-describedby="media-play-tooltip" default-appearance>
  <div id="media-play-tooltip" role="tooltip" slot="tooltip-top-center">
    <span slot="play-tooltip">Play</span>
    <span slot="pause-tooltip">Pause</span>
  </div>
</media-play-button>

👉 See the new tooltips examples:

• Toggle Button
• Toggle Button (Tailwind)
• Play Button
• Play Button (Tailwind)
• Mute Button
• Mute Button (Tailwind)
• Fullscreen Button
• Fullscreen Button (Tailwind)

Keyboard Support (NEW)

Keyboard support was drastically improved:

• New global keyboard shortcuts config which can be set to target the document or player on focus!
• Additional keys were added to sliders such as fractions (0-9), Home, End, PageUp, and PageDown.
• Sliders now behave similar to pointer devices when interacting via keyboard in that they show thumb and previews.
• Slider keyboard seeking is now equal to a pointer device. We debounce seeking calls and only fire after a delay to allow the user to comfortably navigate around without any delay. Previews are visible and updated for keyboard users too!

👉 See the new keyboard docs!

VTT Preview Thumbnails (NEW)

The long awaited VTT thumbnail previews are now supported with either multiple images or a
single sprite.

👉 See the new slider thumbnail docs!

Seek Button (NEW)

Need a button to seek the time forwards or backwards? Seek button now provides a simple way to enable a tappable element for doing so.

👉 See the new seek button docs!

Next Steps

This release was a little slow particularly thanks to live stream support as there's a lot of places it can go wrong. As mentioned, we hope to further refine it over time with your feedback but now our eyes are set on part two of this release. You can find all tasks in the Release 0.4.0 milestone on GitHub. It includes core player support features such as playback rate/quality, captions, and picture-in-picture. We know those are core features most are waiting on and we're excited to deliver them very soon.

Until next time friends 🍎