vidstream-player

Production-ready video player SDK for Web Components and React. Includes HLS support, theming, quality control, watermark/anti-piracy overlays, analytics, and LMS progress tracking.

Installation

npm install vidstream-player

For React usage, make sure your app also has:

npm install react react-dom

React Quick Start

'use client';

import { useRef } from 'react';
import {
  VideoPlayer,
  usePlayerControls,
  usePlayerState,
  type VideoPlayerRef,
} from 'vidstream-player/react';

export default function CourseVideo() {
  const playerRef = useRef<VideoPlayerRef>(null);
  const state = usePlayerState(playerRef);
  const controls = usePlayerControls(playerRef);

  return (
    <div>
      <VideoPlayer
        ref={playerRef}
        source={{
          src: 'https://example.com/video.m3u8',
          type: 'hls',
          poster: 'https://example.com/poster.jpg',
        }}
        mode="ott"
        onReady={() => console.log('ready')}
        onError={(error) => console.error(error)}
      />

      <button onClick={() => controls.togglePlay()}>
        {state.playing ? 'Pause' : 'Play'}
      </button>
    </div>
  );
}

VideoPlayer is also available as the default export:

import VideoPlayer from 'vidstream-player/react';

Web Component Quick Start

ESM

import { registerVideoPlayerElement } from 'vidstream-player';

registerVideoPlayerElement();

<video-player
  src="https://example.com/video.m3u8"
  source-type="hls"
  mode="ott"
  accent-color="#e50914"
></video-player>

Script Tag

<script src="https://unpkg.com/vidstream-player/dist/vidstream-player.umd.js"></script>

Main React Props

| Prop | Type | Notes | |---|---|---| | source | VideoSource | Required. { src, type?, poster?, title? } | | mode | 'ott' \| 'lms' \| 'live' | Player mode | | theme | PlayerTheme | Brand colors and UI styles | | watermark | WatermarkConfig | Static watermark settings | | controls | ControlsConfig | Control visibility/config | | analytics | AnalyticsConfig | Analytics integration | | lmsProgress | LMSProgressConfig | LMS tracking config | | subtitles | SubtitleTrack[] | Subtitles/captions list | | autoplay | boolean | Start automatically | | muted | boolean | Start muted | | loop | boolean | Loop playback |

Player API (Ref / Element)

Available methods:

• play()
• pause()
• togglePlay()
• seek(time)
• setVolume(volume)
• toggleMute()
• setPlaybackRate(rate)
• toggleFullscreen()
• togglePip()
• setQuality(quality | 'auto')
• setSubtitle(track | null)
• getState()
• loadSource(source)
• updateConfig(config)
• destroy()

Player Events

The player emits custom events including:

• player-ready
• player-play
• player-pause
• player-ended
• player-timeupdate
• player-volumechange
• player-fullscreen
• player-pip
• player-quality-change
• player-buffering
• player-error

Package Entry Points

• vidstream-player -> Web Component SDK entry
• vidstream-player/webcomponent -> Explicit Web Component entry
• vidstream-player/react -> React wrapper entry

License

MIT