Player Release 1.0@next: Watch The Birdie! (September 2023)

[mihar-22]

👋

Hey friends! I'm incredibly excited to bring you our 1.0 pre-release 🎉 It's been a very long and grueling three months of work, but totally worth it with everything that's landed. Let's dive into what I've been up to, and then we can dig into all the awesome new things!

❓ So... why the rebuild?

TLDR; Maintaining our own rendering framework was too much work, one-size-fits-all leads to poor API design decisions, and integrations were fragile.

As I've mentioned in past releases, the biggest challenge for Vidstack has been figuring out how to ship libraries that a majority of developers can use and enjoy - "framework-agnostic." This has been a monumental task because it's an unsolved problem across the ecosystem. We could've easily ignored this challenge and only shipped for a specific framework until we grew bigger (if I could go back in time I might do that), but I was over invested so I needed to solve it. If not us then who and when?

I've also mentioned before that for us to properly accommodate for the large number of Plyr/Vime users, we kind of need to figure this out. Honestly, the problem just felt personal to me from the moment I started building OSS libraries. I don't want to ship anything half-arse and I'm okay with some trial and error until we figure it out. Solve it once, solve it well, and be done with it. Our future libraries can all benefit from the tooling we've invested in.

The prior solution was to build a signals framework around Custom Elements (called Maverick) with very specific lifecycle hooks and framework integrations. There's pros/cons and it was 70-80% there but overall I felt it missed the mark for three key reasons:

1. The complexity of maintaining a compiler and our own rendering (dom/ssr/hydration) framework was way too much work. Stupid in hindsight.
2. Trying to create a one-size-fits-all leads to poor API design decisions. Libraries feel non-idiomatic.
3. Integrations will eventually fail. It was evident when I tried to build around React Server Components (RSC). React and most frameworks try to maintain as much control as possible over the rendering process, plus they support varying features, so integrating any external component system is always fragile and open to failing at some point in time.

It was really at this point of reflection that I decided we need to reapproach this whole thing.

❓ What's changed?

TLDR; we don't handle compilation, rendering, and hydration anymore. Let frameworks do the hard stuff! Leads to more idiomatic components and APIs, and they just work as expected (+ future proof).

After careful review, it became clear that the way to build libaries is to delegate rendering (i.e., let the framework handle rendering/hydration). The entire library is too complicated to completely rewrite in each framework, so we still need to abstract logic/state, lifecycle hooks, and styling but leave the rest to the underlying framework. I ran some small experiments and this worked incredibly well. I was excited because I could literally delete ~20k+ LOC in Maverick immediately. No more compiler, no more maintaining our own rendering and hydration framework.

The only thing that can be viewed as a negative is that there's manual work involved in creating and maintaining our Web Components and React libraries separately. However, this is actually a positive and addresses one of the prior key issues because we can now carefully build and design idiomatic APIs.

References:

• Base Lit Element Class
• Lit Signals Directive
• Web Component Example
• React Client Component
• React Server Component
• React Component Example
• React Hooks

❓ What does this release mean?

TLDR; This is our 1.0 library. You can safely build on Vidstack now and take it to production. It doesn't mean bug free, just stable.

My goal since I started Vime (2020) has always been to try and deliver a truly seamless and accessible player building experience. This 1.0 pre-release is a huge milestone and badge of trust, because it's the first time I can say with confidence that we've got the right foundation. There's tons of styles, components, hooks, and APIs available for you to build your own player now. We don't need any more core breaking changes. I'm excited to see what you create, and if you do please join our Discord channel and share it! I get excited seeing what others are building with Vidstack - small or big.

❓ How can I help?

TLDR; Star the project, tell others about it, try the player, and give us feedback.

My ultimate dream is to make Vidstack Player the most used player on the web. Help us get there by starring the project, and trying the player out by installing the package npm i vidstack@next or npm i @vidstack/react@next. If you run into any issues or have feedback for us, be sure to let us know on Discord or GitHub. I personally check both regularly.

New Site

We have a completely new home page built with our new favourite framework Astro ❤️ There's a bunch more sections planned but they'll be dropping slowly later this year. I worked really hard on this site in terms of design and communication. I wanted to show we care and what the initial future of Vidstack looks like. I'm techinically not a designer, so I hope I did a decent job. Finally, join our waitlist if you're excited about what's to come. It's important to note that we're only starting with React/Next.js here but plan on expanding to Nuxt and SvelteKit first then others too.

Expanding beyond the player, our entire focus at Vidstack is on: (1) ensuring top-notch performance across the CMS, player, and storage/encoding/streaming, (2) extremely fair pricing, (3) a seamless start-to-finish workflow by integrating with dev tools/frameworks. Lastly, I'm working on a partnership for our encoding/streaming, so if all goes well then I'm super excited to announce that hopefully very soon 🤞

New Docs

We have a brand new docs site! The old docs had way too much going on in the sidebar making it hard to find stuff. In contrast, the new docs is optimized for discoverability with 3 top-level categories (Overview, API, and Components). In addition, the new docs is now trying to say less and show more code copy snippets, as we'll use other mediums such as examples/tutorials to provide more in-depth learning. The new installation page is a great example of that, using large iconography, moving extra words and information behind popups, and simplifying the initial starting point. The examples do most of the heavy lifting now.

You'll also find new component API reference tables which are more compact and easier to search through. They also provide type hints such as whether a React component extends certain HTML attributes, what type of ref it exposes, and simple examples on how to use the component.

Lastly, do note that the docs are not complete! It's my top priority to get it done before we reach the official 1.0.

New Examples

We have a new examples repository! There's a variety of examples across different JS frameworks and styling options (CSS, Default Theme, Default Layout, and Tailwind CSS). The goal here was to provide a great introduction to building and customizing player UI. It's a great place to start after going through the installation process. We'll be adding more over time!

Feel free to check it out. We recommend launching them on StackBlitz to get playing as fast as possible. You'll find links to launch it in each example README. Enjoy!

New Web Component Library

We have a completely new Web Component library with rendering powered by lit-html. There's no longer an awkward onAttach callback. Elements are ready as soon as they've connected to the DOM. There was even a nice 20% reduction in bundle size! We've also flattend components and handle dynamic content a little cleaner via templates:

 <media-quality-radio-group>
  <!-- We now provide templates for dynamically rendered content. -->
   <template>
     <media-radio>
       <span data-part="label"></span>
       <span data-part="bitrate"></span>
     </media-radio>
   </template>
 </media-quality-radio-group>

All types are now exported from vidstack/elements:

import { type MediaPlayerElement } from 'vidstack/elements'

Lastly, you no longer need to register global types as they're included as part of the import:

// Register Elements.
import 'vidstack/player';
import 'vidstack/player/layouts';
import 'vidstack/player/ui';

Framework JSX Types

As I was building the examples I noticed that most frameworks support Custom Elements really well but the lack of types was messing up the dev experience. Happy to report we now ship types for Solid, Svelte, and Vue.

// tsconfig
{
  compilerOptions: {
    // Register global component types - includes props and events.
    types: ['vidstack/{solid,svelte,vue}']
  }
}

New React Library

One of the most exciting parts of this release is we have a dedicated React library! We don't use Custom Elements under the hood anymore.

✅ Next.js 13 Ready (i.e., app directory).
✅ Support RSCs.
✅ Prebundled dependencies such as Maverick.
✅ Render standard DOM elements and forward refs.
✅ Radix-inspired asChild composition pattern.
✅ Component builder pattern to simplify imports and speed up building.
✅ Idiomatic components, props, callbacks, and composition.
✅ Heaps of new hooks to help with building your own components and UI.

// Renders a good ol' <button>
<PlayButton>
  {/* ... */}
</PlayButton>

<Tooltip.Root>
  <Tooltip.Trigger asChild>
    <PlayButton>
  </Tooltip.Trigger>
  <Tooltip.Content>
    {/* ... */}
  </Tooltip.Content>
</Tooltip.Root>

Headless

The entire library is now headless by default. You won't be loading anything you don't need and you can easily compose and build freely even when using the Default Theme. You're back in control. Enjoy!

// Headless
<VolumeSlider.Root>
  <VolumeSlider.Track>
    <VolumeSlider.TrackFill />
  </VolumeSlider.Track>
  <VolumeSlider.Thumb />
</VolumeSlider.Root>

// With Default Theme
<VolumeSlider.Root className="vds-slider">
  <VolumeSlider.Track className="vds-slider-track" />
  <VolumeSlider.TrackFill className="vds-slider-track-fill vds-slider-track" />
  <VolumeSlider.Thumb className="vds-slider-thumb" />
</VolumeSlider.Root>

Components

Anywhere we could flatten the component tree and add more components we did. There's a bunch of new components across both Web Components and React. Some examples include: track, controls, tooltips, chapter title, slider chapters, and caption/speed/quality/audio radio groups.

You'll also find we've cleaned up naming and added some more data attributes, renamed MediaOutlet to MediaProvider, and thanks to the component tree being flat now (not abstracted behind a root component) our Tailwind integration is much cleaner (removed the ugly -class props).

Finally, we've put some props in their right place such as poster and thumbnail:

// These props are no longer required to be set on the player.
<Poster src="..." />
<DefaultVideoLayout thumbnails="..." />

Improved Poppers

Tooltips and Menus are now positioned correctly in reference to a trigger element. We're now using the popular Floating UI library. You can set the placement such as top end, adjust the main axis and alignment offset, and add animations just like Radix. This works for both Web Component and React users!

<media-tooltip>
  <media-tooltip-trigger>
    <media-play-button>
      <!-- ... -->
    </media-play-button>
  </media-tooltip-trigger>
  <media-tooltip-content placement="top start" offset="30">
    <!-- ... -->
  </media-tooltip-content>
</media-tooltip>

<Tooltip.Root>
  <Tooltip.Trigger asChild>
    <PlayButton>
      {/* ... */}
    </PlayButton>
  </Tooltip.Trigger>
  <Tooltip.Content placement="top start" offset={30}>
    {/* ... */}
  </Tooltip.Content>
</Tooltip.Root>

Default Theme Classes

The Default Theme is optional now and applied via classes. The defaultAppearance property is no longer required. Here's an example on how we would apply the theme to the volume slider. Do note, the new examples show you how to build your own audio and video layouts using the default theme.

<media-volume-slider class="vds-slider">
  <div class="vds-slider-track" />
  <div class="vds-slider-track-fill vds-slider-track" />
  <div class="vds-slider-thumb" />
</media-volume-slider>

<VolumeSlider.Root className="vds-slider">
  <VolumeSlider.Track className="vds-slider-track" />
  <VolumeSlider.TrackFill className="vds-slider-track-fill vds-slider-track" />
  <VolumeSlider.Thumb className="vds-slider-thumb" />
</VolumeSlider.Root>

Layouts

We had previously called layouts "skins" but this didn't explain their purpose well. Most people didn't understand the word "skin", so we're now calling them layouts and trying to provide better tools for you to build your own. We have a docs page dedicated to layouts coming very soon. For now you can see the examples on how to get up and running.

✅ Separate audio and video layouts.
✅ Icon customization - you're free to provide your own icons now!
✅ Live stream support.
✅ New props: smallLayoutWhen (specify if/when small layout is displayed using player queries such as (width < 380)), thumbnails, noModal (prevent menu popping up from bottom of screen on small devices), menuGroup (move menus to top or bottom controls group), showTooltipDelay, showMenuDelay, and hideQualityBitrate.

👉 See the new Default Layout component page.

What's Next?

The main focus point from here is addressing bugs and reaching 1.0 which will require finishing the player product page and the docs. In addition, I'll be working on getting our streaming partnership in place, ironing out our services and pricing table, adding stuff to our and site, and applying for YC. By the end of the year we'll have 1.0 finalized, have our services and streaming partner confirmed, and start early work on the CMS. The remainder of my time will go into marketing efforts around the player to grow adoption.

I'm really looking forward to closing out this year and building new and exciting things next year! I've been working on the player for quite some time so a little change will be refreshing. To be fair, there's always going to be a lot of work to do on the player as we still need to add Managed Media Source support, Document PIP support, AirPlay, Chromecast, IMASDK integration, and much more. One milestone at a time we're going to get there... excited to share the journey with you all!

Remember to join our Discord and say hi!

Until next time friends 🍎

[reyamir]

Congrat, I'm implementing vidstack for https://github.com/luminous-devs/lume

[mihar-22]

Thanks! Lume is looking awesome, excited to see how it comes together. Hit me up when you're done :)

[aptroot]

What an amazing achievement @mihar-22! Our developers are eager to start implementing Vidstack.

[mihar-22]

Thanks heaps @aptroot! Excited to see what accessibility challenges we can tackle together :)

[wplit]

Congrats to everybody involved!

Will start spending sometime now getting familiar with everything and help out with bug reports where I can. Seems like a lot has changed since I last played around with it a few months back.

Looking forward to when being Youtube/Vimeo can be used as providers.

[BleedingDev]

Awesome! I have to update to the new version at Coursition (https://coursition.com). 😊

[ElBouhaliMohamed]

I freaking love the vision and damn that new website looks great! 🔥

[mihar-22]

Thank you @ElBouhaliMohamed, it means a lot!

[BlackDahlia313]

The new website is really great. Really amazing UI/UX for the docs.

Thanks for the Vue support. I'm from the green side, but I can't wait to use this in my upcoming Nuxt app

[AkilanV]

it is free or paid

[mihar-22]

It's an open-source (MIT licensed) project. The player is free.

[AkilanV]

once vidstack service is stopped. its player is working or its get error. For eg : in broadmax player it gives one js file. in this file we configure in our project, once the service is stopped also its working because of js file. in broadmax cdn videos are free, can you tell why i prefer over vidstack other than broadmax.

[adityapatadia]

Great work @mihar-22 We are looking forward to using it in our products.

I read that you are looking for a streaming partner. Happy to chat for that!

[osamazxo]

It looks so great! I'm very excited to try it 🧡