Player Release 1.0-RC: There’s Always a Bigger Fish (March 2024)

[mihar-22]

👋

It's been a solid two months since our last release. We went from a "small" update to tons of new features again. At this point I can't help it. This release started with a PR for audio gain by @codercms, which lead to a complete 🎥 settings menu rework, followed by more feature compatibility with Vime/Plyr and then a PR for DASH support by @Dinesh-Gautam! I'm really excited to see some of you not being scared to jump into our codebase, it's hopefully not as intidimating as it looks.

Great news, this is our 1.0 release candidate. What does that mean? After we get through the initial wave of bugs from early testers, this is the codebase we'll be shipping in 1.0. There will be no more features or breaking changes at all from this point forward. I know I've said no more features before, but this time I'm serious 😐 (really).

I'm super excited to share what's been worked, so let's dig in...

✨ What's New?

• Player Constructor
• Plyr Compat
• Source Qualities
• Player Source Types
• New CDN Bundles
• Color Schemes
• New Settings Menu
• Download Button
• DASH Provider
• Media Announcer
• Audio Gain
• Speed Slider
• Quality Slider
• Performance
• New Icons
• New Test Files
• Tons of bug fixes!

Breaking Changes

• Due to some TypeScript typing issues, MediaStream, MediaSource, and Blob must be provided as an object now instead of directly on the player src. You can provide these types now like so src = { src: sourceObject, type: 'video/object' }.

• Our new CDN bundles will take priority over the legacy bundles. Please migrate over to them as the old bundles today will be removed in the official 1.0 release. The old URLs and bundles still work today but best to get ahead and avoid breaking in the future.

• The Default Layout translations have changed, refer to the language section for the updated translations.

• The Default Layout icons have new additions, refer to the icons section for the updated icons.

• The <DefaultKeyboardActionDisplay /> React export was renamed to <DefaultKeyboardDisplay />.

• The Default Theme menu CSS variables were adjusted as there was a large rework. See the Menu component page and click on example.css to see the updated variables.

• We now use a check icon instead of the old radio check class (vds-radio-check was removed). See the Menu component page for new examples.

Installation

npm i vidstack@next

React

npm i @vidstack/react@next

Player Constructor

If you've been wanting a simpler way to create a player whilst progressively enhancing <audio>, <video>, or <iframe> elements then this is it! Available via NPM and CDN.

import { PlyrLayout, VidstackPlayer, VidstackPlayerLayout } from 'vidstack/global/player';

const player = await VidstackPlayer.create({
  target: '#target',
  title: 'Sprite Fight',
  src: 'https://files.vidstack.io/sprite-fight/720p.mp4',
  poster: 'https://files.vidstack.io/sprite-fight/poster.webp',
  // You can swap `VidstackPlayerLayout` for `PlyrLayout`
  layout: new VidstackPlayerLayout({
    thumbnails: 'https://files.vidstack.io/sprite-fight/thumbnails.vtt',
  }),
});

👉 New JavaScript Installation Page

Plyr Compat

The new Player Constructor above is a step in helping Plyr users migrate over, but for those looking for a softer migration we provide a Plyr constructor that has ~95% of the original features:

import { Plyr } from 'vidstack/global/plyr';

const player = new Plyr('#target', {
  title: '...',
  src: '...',
  poster: '...',
  thumbnails: '...',
});

Available via CDN too:

<script type="module">
  import { Plyr } from 'https://cdn.vidstack.io/plyr';

  const plyr = new Plyr('#target', {});
</script>

See the Plyr GitHub repo for docs and usage. Do note, in general this API is more limited and doesn’t have easy access to all player features. We strongly recommend upgrading to the newer player constructor above. This compat feature was provided as a great first step in testing migrating over.

👉 See JavaScript Installation Page

Source Qualities

This might be one of the most requested features! We now support loading various qualities using multiple media files. It's automatically supported by the Default/Plyr Layouts and includes an auto-quality option (currently only observes player resizes).

JS

new VidstackPlayer({
  target: '#target',
  src: [
    { src: '...', type: 'video/mp4', width: 1920, height: 1080 },
    { src: '...', type: 'video/mp4', width: 1280, height: 720 },
    // ...
  ],
});

HTML

<media-player>
  <media-provider>
    <source src="..." type="video/mp4" data-width="1920" data-height="1080" />
    <source src="..." type="video/mp4" data-width="1280" data-height="720" />
    <!-- ... -->
  </media-provider>
</media-player>

React

<MediaPlayer
  src={[
    { src: '...', type: 'video/mp4', width: 1920, height: 1080 },
    { src: '...', type: 'video/mp4', width: 1280, height: 720 },
  ]}
>

👉 New Source Sizes Section

Player Source Types

The player src types were not handled correctly before and resulted in an unknown type, it is now strongly typed to help with selecting the correct MIME type:

New CDN Bundles

We have completely new CDN bundles and URLs that are easier to remember, a little more chunk optimized, and include more of what you need out of the box:

• https://cdn.vidstack.io/player: Includes the player, all UI components, the VidstackPlayer global, and the Default Layout.
• https://cdn.vidstack.io/player.core: Same as above but without the Default Layout, best for when building your own layouts.
• https://cdn.vidstack.io/plyr: Includes the player, the Plyr global, and the Plyr Layout.
• https://cdn.vidstack.io/icons: Lazy loads our icon library and registers the media-icon element.

Development versions:

• https://cdn.vidstack.io/player.dev
• https://cdn.vidstack.io/player.core.dev
• https://cdn.vidstack.io/plyr.dev

👉 Updated CDN Installation

Color Schemes

The Default Theme and Default Layout now support light and dark themes! By default it will use the user’s preferred color scheme. You can set a specific theme like so:

HTML

<media-video-layout color-scheme="light"></media-video-layout>

React

<DefaultVideoLayout colorScheme="light" />

👉 Color Schemes Docs

New Settings Menu

Our settings was growing from all the new features so it was a good time to revise it.

• Consistent and accessible gray tones.
• New submenus: playback, accessibility, audio, and captions.
• New checkboxes: loop, announcements, keyboard display, and auto quality.
• New sliders: speed, quality, and audio boost.
• New caption customization menu with better controls such as input color and sliders.
• We now show a "Captions look like this" prompt when customizing captions and none are visible.

🎥 Walkthrough of the new settings menu and features.

Download Button

You can now easily add a download button to the Default Layout (it was already included in the Plyr Layout). It supports the following values: boolean, string (download URL), and { url: string; filename: string }.

HTML

<media-video-layout download="https://...mp4"></media-video-layout>

React

<DefaultVideoLayout download={{ url: '...', filename: 'file.mp4' }} />

DASH Provider

The DASH provider is a close second to source qualities with the amount it has been requested. I'm really excited to say it's finally here thanks to some awesome work by @Dinesh-Gautam! It uses dash.js under the hood and comes with support for loading audio tracks, text tracks, and qualities through your DASH playlist. Live streaming is still experimental and will require more testing, let us know how you go!

👉 DASH Installation

👉 DASH Provider Page

Media Announcer

The new MediaAnnouncer component is used to announce important updates to screen readers. It was previously built into our KeyboardDisplay component which we ported from YouTube, but later we realized it was best to separate it and have it as a standalone component that everyone can benefit from. This component ensures that users with visual impairments are kept informed about the status of media state in real-time. At the moment, this includes playback, volume, captions, fullscreen, picture-in-picture and seeking.

👉 MediaAnnouncer

Audio Gain

Audio gain support is here thanks to @codercms! It enables amplifying the current volume by a set gain amount. This is great when there is poor audio quality or processing and you need to go beyond the max volume. The volume slider adapts based on the applied gain by setting the correct volume and gain if you go above 100%, and the displayed volume percentage is also updated to match. Finally, we've also included a new audio boost slider to the Default Layout settings which you can find under the new audio submenu.

👉 Audio Gain API

👉 Audio Gain Slider

👉 useAudioGainOptions

Speed Slider

The Speed Slider is a new way to adjust the current playback rate using a range input. We'd argue it feels more natural compared to the old radio groups and submenus. You can also use the new slider steps component to add visual markers for value steps. We've also replaced the old submenu and radio groups in our Default Layout with this new slider (you can find it in the new playback submenu).

👉 Speed Slider

Quality Slider

The Quality Slider is a new way to adjust the current playback quality using a range input. We'd argue it feels more natural compared to the old radio groups and submenus. You can also use the new slider steps component to add visual markers for value steps. We've also replaced the old radio groups in our Default Layout with this new slider (you can find it in the new playback submenu).

👉 Quality Slider

Performance

During long playback, it can be intense constantly updating parts of the player UI on time updates. We've added the following performance improvements:

• The time slider will no longer update when it's not visible.
• The time component will no longer update when it's not visible.
• The chapters and settings menu in the Default Layout will not render anything when it's not opened. This prevent unnecessary rendering on load and updates during playback.

New Icons

We've added three new icons to the Vidstack Media Icons collection:

• Accessibility
• Check
• No Eye

New Test Files

We've rebuilt and reorganized our test files. They also come with simpler URLs and can be found at https://files.vidstack.io. The docs and examples have been updated to these new files.

Misc.

• AirPlay now works with the audio provider.
• New onLoad method for initializing storage.
• New artwork player property for Media Session API.
• The Default Theme now respects user reduced motion preference.
• Server bundle exports for Deno, Bun, and Cloudflare Workers.
• Better handling of gaps between mute button and volume slider popup.
• You can seek directly to the end of media now, no rounding issues.
• React slider callbacks were not being called, fixed.
• Tons of other bug fixes and improvements, see changelog.

What's Next?

Mostly fixing bugs, updating our examples (outdated now), and starting work on our player product page to prepare for the official 1.0 release. We'll also go through some changes on the home page while we adjust communication and positioning (been a few already).

In past releases, I've spoken about starting work on our CMS next but we might be taking a little different route. I want to focus our messaging and core around being an open-source video platform. It means we're most likely going to build all the products mentioned but in a different spirit and order. I'll share more as I begin to plan out our first product, just note that the goal is to focus on open-source and provide as much value as possible. I want this to be bigger than "Vidstack" and serve the larger OSS video community as much as possible. For now, hope you enjoy the release and onwards!

🍎

[Curetix]

Great work @mihar-22, @codercms, @Dinesh-Gautam! Looking forward to the final v1 release.

[mihar-22]

Thanks for your support as always Curetix ❤️

[endaquigley]

[mihar-22]

The components from that package are tied to the Default Layout context so they are not reusable. The docs and examples repo show how to create a default themed slider.

[thesn10]

What do you mean by "There will be no more features at all"? Does this mean there will never ever be a new feature anymore, or just until 1.0 is released? We have not even reached feature parity with plyr.
For example, key features like ads support (vast, IMA-SDK, pre-roll, mid-roll, etc) seems to be completely missing.
There's an open draft PR for IMA integration, what about that?
If such features are never added, that will be a reason for me to abandon Vidstack Player in favor of other solutions.

[Curetix]

After we get through the initial wave of bugs from early testers, this is the codebase we'll be shipping in 1.0. There will be no more features or breaking changes at all from this point forward.

That should mean no more new features until the final v1 release. It's unlikely that the player will be abandoned immediately after v1.

[Mister-Hope]

I am not sure if I understand colorScheme correctly, from source code it seems that only a small brunch of tweaks is applied when setting it to 'dark' or 'light':

The audio background can be changed, but I am not seeing any actual change on the video layout. I am expecting a white background video with black buttons appears when I am setting colorScheme="light", any explaination about this?

[mihar-22]

Join our Discord for any questions 🙏 The release notes are not the right place for helping people. Not sure what framework you’re using. In general, the color scheme for video adjusts popups such as tooltips, menus, keyboard display, etc.

[Mister-Hope]

Discord is blocked in my country (China). I just want to say that the video layout is too dark by default. I am expecting a whiter color when setting light colorSheme.

If you mind I can create new discussion for this.

[mihar-22]

A new GitHub discussion is perfect, thanks!

[oceandiveloper]

Hi @mihar-22 ,

First off, thank you for all the work you’ve done on Vidstack—it looks like an amazing tool with tons of potential.

I’m reaching out because we’re considering using the Media Player built by BricksExtras, which relies on Vidstack. However, the player is still in beta as the Vidstack library is not fully stable yet. The BricksExtras team mentioned that Vidstack is in its final bug-fixing stages but doesn’t have an ETA for the stable release.

Could you share any updates on the roadmap for the 1.0 stable release or insights into when the library might be ready for broader production use? Knowing this would help us plan better for our projects.

Thanks again for your hard work and commitment to open-source video solutions!

[jbjhjm]

@mihar-22 Same here. I'm eagerly waiting for vidstack official release to rewrite our old player infrastructure.
I just spotted that maverick.js has some docs now which I consider good news.
But risking to build custom player components based on an unstable/non final API (which, afaik, lacks technical documentation as of now) would not be a smart choice. Hope to see the 1.0 milestone soon!

[Mister-Hope]

Sorry for trouble you again, @mihar-22 It seems you have some activity on GitHub, please take a minute to give a new roadmap for the project.

Is it abandoned, do you need any active contributors?

[smichaelsen]

@Mister-Hope

It seems you have some activity on GitHub

stop harassing the guy. this is voluntary work open source software. it will be ready when it's ready, or it won't.

[Mister-Hope]

@smichaelsen

I'm not going to bother the timeline again after this, but let's get one thing straight about how open source works.

I make 20k+ contributions to open source projects in the past five years, including those under my personal account and those I create an org for. Stop teaching me how open source works.

If a project is your personal plaything, keep it under your personal account. But when you create a GitHub org for it, plaster "Community. Built for us" all over the homepage, and run a Discord server inviting people to share feedback, you forfeit the right to treat it as a personal whim. You made it a community project.

You have every right to abandon it. But you have a basic obligation to the people you invited in. What you don't do is go completely silent, leaving the project unmaintained for over a year with no roadmap and no official statement.

When you decide to leave or kill a community project, you shall make an announcement for your community in the first place. Anything less is just a slap in the face to everyone who took you at your word.

Updated for everyone: Answers found in another discussion: #1704

[rnnc]

seems like videojs 10 is the successor to vidstack

https://v10.videojs.org/