DOCSEARCHbyAlgolia
Submit Docs

Vidstack Player

repository·main·Indexed 25 days ago

https://github.com/vidstack/player

A robust, customizable, and accessible media player library for video and audio. Designed as a modern successor to Plyr and Vime, it supports multiple JavaScript frameworks and web components. It provides tools for building high-quality media experiences, including pre-built layouts (such as Plyr-based designs), customizable slot-based UI systems, and components for managing text tracks and media providers.

Tokens
20.1K
Snippets
33
Records
148
Agent score
85%

What's inside Vidstack Player

  3. Quickstart with Vidstack Player

    main

    Vidstack Player is a production-ready, customizable, and accessible video or audio player. It is designed to work with various JavaScript frameworks. You can either build your own custom player layout using provided components or use pre-built layouts for rapid development.

    To get started, choose the installation guide corresponding to your framework or environment:

  5. Understand Vidstack bundle types

    main

    Vidstack produces several distinct types of bundles depending on the target environment and distribution method:

    NPM Bundles

    Distributed via npm, these are categorized by environment:

    • server: Optimized for server-side environments (e.g., Node.js). Element entry points are transformed into no-ops to prevent server-side errors.
    • dev: Development builds with __DEV__: true.
    • prod: Production builds with __DEV__: false and minification.

    CDN Bundles

    Optimized for direct browser usage via JSDelivr. These bundles use specific external paths for dependencies like media-icons and media-captions to reduce bundle size.

    Plugins Bundle

    A dedicated bundle for Vidstack plugins, optimized for Node.js environments.

    Types Bundles

    Provides TypeScript definitions for the core library, elements, global player interfaces, and icons.

  6. Use the Cast Application Framework (CAF)

    main

    The cast.framework provides a higher-level abstraction for managing Cast state and sessions.

    Configure CastContext

    Use cast.framework.CastContext.getInstance() to access the singleton context. You can configure it using setOptions(options) where CastOptions includes:

    • autoJoinPolicy: chrome.cast.AutoJoinPolicy
    • language: Optional string
    • receiverApplicationId: Optional string
    • resumeSavedSession: Optional boolean
    • androidReceiverCompatible: Optional boolean (enables Cast Connect for Chrome 87+)

    Listen for Cast Events

    Use CastContext.addEventListener to listen for:

    • cast.framework.CastContextEventType.CAST_STATE_CHANGED: Detects if devices are available or if the user is connected.
    • cast.framework.CastContextEventType.SESSION_STATE_CHANGED: Detects changes in the session lifecycle (e.g., SESSION_STARTED, SESSION_ENDED).

    Manage CastSession

    cast.framework.CastSession provides a Promise-based API for common tasks:

    • requestSession(): Returns a Promise resolving to an error code or undefined.
    • setVolume(volume): Returns a Promise.
    • setMute(mute): Returns a Promise.
    • sendMessage(namespace, data): Returns a Promise.
    • loadMedia(request): Returns a Promise.

  7. Use the Menu component in React

    main

    The Menu component provides a set of primitives to build floating menus, submenus, and option lists. It consists of a Root container, a Button to trigger the menu, and Items (or Content) to hold Item components.

    Basic usage pattern:

    <Menu.Root>
  <Menu.Button>Open Menu</Menu.Button>
  <Menu.Content placement="top end">
    <Menu.Item>Option 1</Menu.Item>
    <Menu.Item>Option 2</Menu.Item>
  </Menu.Content>
</Menu.Root>
    <Menu.Root>
  <Menu.Button></Menu.Button>
  <Menu.Content placement="top end"></Menu.Content>
</Menu.Root>

  8. Build Vidstack using tsdown CLI flags

    main

    The Vidstack build process can be customized using specific command-line flags when running the build script. These flags control which bundles are generated:

    • --types: Generates TypeScript definition bundles (.d.ts files).
    • --cdn: Generates CDN-optimized bundles.
    • --plugins: Generates the plugins bundle.
    • --css: (Currently returns an empty config, effectively skipping standard bundles).
    • -w or --watch: Enables watch mode. When used with --types, it also triggers watchStyles() to monitor CSS changes.

  10. Configure quality switching with VideoQualityList.switch

    main

    The VideoQualityList class allows you to control how quality level switches are executed using the switch property. You can choose between three modes:

    • current: Triggers an immediate switch. This aborts the current fragment request, flushes the buffer, and fetches the new quality level matching the current position.
    • next: Triggers a switch for the next fragment. This may eventually flush already buffered next fragments.
    • load: Sets the quality level for the next loaded fragment.

    Defaults to 'current'.

  11. Configure the @vidstack/react build with tsdown

    main

    The @vidstack/react package uses tsdown for its build process, generating different bundles for server, dev, and prod environments.

    Bundle Types

    • server: Optimized for server-side environments (e.g., Node.js), using platform: 'neutral'.
    • dev: Optimized for development, including __DEV__: true and specific module resolution conditions.
    • prod: Optimized for production, including __DEV__: false, minification-ready settings, and the inclusion of vidstack-icons.

    External Dependencies

    The following packages are treated as external and are never bundled into the Vidstack output:

    • react
    • react-dom
    • media-icons
    • media-captions
    • hls.js
    • dashjs
    • @floating-ui/*
    • remotion/*

    Entry Points

    The build generates several sub-path exports for the player, including:

    • vidstack: The main entry point.
    • player/vidstack-remotion: Remotion provider.
    • player/vidstack-default-layout: Default layout components.
    • player/vidstack-plyr-layout: Plyr layout components.
    • player/vidstack-plyr-icons: Plyr specific icons.
    • player/vidstack-default-components: Default UI components.
    • player/vidstack-default-icons: Default icons.

  12. Configure the Plyr instance

    main

    When initializing Plyr via new Plyr(target, config) or Plyr.setup(targets, config), you can provide a PlyrConfig object to customize behavior.

    Key configuration options include:

    • enabled: (boolean) Completely disable Plyr. Defaults to true.
    • autoPause: (boolean) If true, only one player will play at a time. Defaults to true.
    • ratio: (string | null) The video aspect ratio (e.g., '16/9'). Defaults to null.
    • hideControls: (boolean) Automatically hide controls after inactivity. Defaults to true.
    • resetOnEnd: (boolean) Reset playback to the start when media ends. Defaults to false.
    • disableContextMenu: (boolean) Disable right-click menu on the video. Defaults to true.
    • iconUrl: (string | null) URL to a custom SVG sprite.
    • keyboard: (object) Configure keyboard shortcuts via focused (boolean) and global (boolean) properties.