video-sdk

Video SDK

A lightweight, embeddable video/audio player SDK with a Web Component interface and React support, powered by Vidstack and Vite. It supports HLS (via hls.js), YouTube, Vimeo, Wistia, and regular MP4/MP3 sources, with customizable controls and theming.

✨ Features

• Simple Web Component: <video-sdk> you can drop on any page
• React component for app integration
• HLS, YouTube, Vimeo, Wistia, MP4/MP3
• Theming (light/dark/system) and extensive props
• Ready-to-bundle UMD build for the browser via CDN
• Storybook playground and docs deployed to GitHub Pages

🚀 Quick Start

Option A: Use in any HTML page (CDN)

Add the UMD bundle and then the tag. Minimal example:

<!-- Include the UMD bundle -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/video-sdk@2.10.0/dist/video-sdk.css"
/>
<script src="https://cdn.jsdelivr.net/npm/video-sdk@2.10.0/dist/video-sdk.umd.js"></script>

<!-- Use the Web Component -->
<video-sdk
  src="https://files.vidstack.io/sprite-fight/1080p.mp4"
  poster="https://files.vidstack.io/sprite-fight/poster.webp"
  thumbnails="https://files.vidstack.io/sprite-fight/thumbnails.vtt"
></video-sdk>

Common attributes (kebab-case):

• src: media URL (HLS, MP4/MP3, YouTube/Vimeo/Wistia)
• poster: poster image URL
• controls: show player controls (boolean)
• auto-play, loop, muted, plays-inline (booleans)
• volume (0..1), playback-rate (0.5..2)
• color-scheme: light | dark | system (default)
• aspect-ratio: e.g. 16/9 (default), 4/3, 1/1
• stream-type: unknown | on-demand | live | live:dvr | ll-live | ll-live:dvr
• view-type: unknown | video | audio

Notes:

• Omit boolean attributes to set them false. Setting without value equals true.
• Unknown defaults (like stream-type="unknown") can be omitted.

Option B: Use in React

Install the package, then import and use the Player component.

pnpm add video-sdk
# or
npm install video-sdk

import { Player } from 'video-sdk';

export default function Example() {
  return (
    <Player
      src='https://fast.wistia.com/embed/medias/2fu3znoof3.m3u8'
      poster='https://embed-ssl.wistia.com/deliveries/d6ce4e2fffe8cdec5979ad24dca5c2c840c1d46b/file.png'
      controls
      playsInline
      preferNativeHls
      aspectRatio='16/9'
      colorScheme='system'
    />
  );
}

TypeScript types are included.

🧪 Storybook (Demos)

We publish Storybook to GitHub Pages via CI. After pushing to main or publishing a release, the latest Storybook is deployed. You can also run it locally:

pnpm install
pnpm storybook

To build the static Storybook:

pnpm build-storybook

🛠️ Development

• Build the library: pnpm build
• Lint: pnpm lint
• Format: pnpm format
• Preview (Vite preview of built site if applicable): pnpm preview

The library is built as a UMD bundle via Vite (see vite.config.ts). The main entry is src/main.tsx and the React components live under src/.

🔁 Releases

This repo uses semantic-release to automatically version, generate changelogs, and publish on merges to main.

• Release workflow: .github/workflows/release.yml
• Follow Conventional Commits for messages (e.g., feat:, fix:)