@streamspark/react-video-player

v1.1.1

Published

4 months ago

A customizable React video player with no dependencies

🎥 @streamspark/react-video-player

A fully-featured, YouTube-like video player built completely from scratch using React and TypeScript — no third-party video libraries involved.

Perfect for developers looking for a clean, minimal, extensible, and dependency-free media player.

✅ Features

🎬 Custom play/pause/seek controls (with buffer indicator)
🔊 Volume control with mute & smooth slider behavior
⏩ Live seek drag - YouTube-style real-time scrubbing
📺 Fullscreen toggle
🌐 Subtitle (.vtt) support
📝 Custom draggable captions with full styling control
⚙️ Playback speed control (0.25x – 2x)
🌓 Light & dark themes
📱 Fully responsive layout & mobile touch support
🎮 YouTube-style keyboard shortcuts
♿ Accessible (ARIA & screen reader friendly)
🎨 Complete control customization - show/hide and style any control
🎨 Themeable via CSS variables
🧱 No 3rd-party libraries – pure React

✨ What's New

⏩ Live Seek Drag (NEW!)

YouTube-style scrubbing - drag the seek bar thumb for real-time seeking
Live video preview - see video content as you drag through the timeline
Smooth interaction - no delay between drag and video response
Cross-platform support - works on both desktop and mobile devices
Enhanced visual feedback - thumb grows during drag for better grip
Touch-friendly - optimized for finger dragging on mobile devices

📝 Custom Draggable Captions (NEW!)

Fully customizable captions with complete styling control
Drag & drop positioning - move captions anywhere on the video
YouTube-like styling - clean, unobtrusive appearance
Mobile touch support - drag with finger on mobile devices
Boundary constraints - captions stay within video player bounds
Timing control - precise start/end times for each caption
Visual feedback - hover effects and drag indicators

🧠 Smarter Control Visibility

Controls remain visible while mouse is anywhere inside the player
Hide only when mouse leaves — like YouTube
No flickering or premature hide during interaction

🔊 Volume Panel (Improved UX)

Click to open — no accidental hover changes
Auto hides when mouse leaves the panel
Smooth sliding and clear mute indicator

🎞️ Seek Bar Preview (Optional)

Integrated <canvas> + <video> thumbnail preview
Works with sprite images or auto-generated previews
Fast and optimized

📷 Instant Thumbnail Preview (Optional)

Hover previews powered by <video> + <canvas>.
Works with both sprite frames and per-second captures.
Fully optimized for performance — previews load instantly.

🎨 Complete Control Customization (NEW!)

Full control visibility - show/hide any control individually
Complete styling control - customize every aspect of the player's appearance
Button styles - customize play, volume, and all control buttons
Seek bar customization - control colors, sizes, and hover effects
Volume slider styling - customize width, colors, and thumb appearance
Time display styling - control fonts, colors, backgrounds, and effects
Menu customization - style playback speed, quality, and share menus
Tooltip styling - customize tooltip appearance and delays
CSS variables support - use CSS variables for advanced customization
TypeScript interfaces - full type safety for all customization options

🚀 Live Demo

Try it online (no setup required):
👉 StackBlitz Demo

🔗 Links

🔧 GitHub: https://github.com/arun59ay/react-video-player

📦 NPM: https://www.npmjs.com/package/react-smart-video-player

⚡ Live Demo: https://stackblitz.com/github/arun59ay/react-video-player

📦 Installation

npm install react-video-player

You also need to import the default styles manually:

import 'react-video-player/dist/index.css';


import React from 'react';
import { VideoPlayer } from 'react-video-player';
import 'react-video-player/dist/index.css';

export default function App() {
  return (
    <VideoPlayer
      src="/videos/sample.mp4"
      poster="/images/thumb.jpg"
      title="Demo Player"
      theme="dark"
    />
  );
}

### 📝 Custom Draggable Captions

```tsx
import React from 'react';
import { VideoPlayer } from 'react-video-player';
import { CaptionConfig } from 'react-video-player';

const customCaptions: CaptionConfig[] = [
  {
    text: "🎬 Welcome to our video!",
    startTime: 0,
    endTime: 5,
    style: {
      fontSize: '16px',
      color: '#ffffff',
      backgroundColor: 'rgba(0, 0, 0, 0.8)',
      position: 'bottom',
      padding: '8px 12px',
      borderRadius: '4px',
      fontWeight: 'bold'
    }
  },
  {
    text: "📱 Drag me anywhere!",
    startTime: 5,
    endTime: 10,
    style: {
      fontSize: '14px',
      color: '#ff6b6b',
      backgroundColor: 'rgba(255, 107, 107, 0.9)',
      position: 'top',
      padding: '6px 10px',
      borderRadius: '6px',
      textAlign: 'center'
    }
  }
];

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    customCaptions={customCaptions}
    title="Custom Captions Demo"
    theme="dark"
    width="100%"
    height="400px"
  />
);

CaptionConfig Interface:

interface CaptionConfig {
  text: string;                    // Caption text content
  startTime: number;               // Start time in seconds
  endTime: number;                 // End time in seconds
  style?: {
    fontSize?: string;             // Font size (e.g., '16px')
    fontFamily?: string;           // Font family
    color?: string;                // Text color
    backgroundColor?: string;      // Background color
    padding?: string;              // Padding (e.g., '8px 12px')
    borderRadius?: string;         // Border radius
    textAlign?: 'left' | 'center' | 'right';
    position?: 'bottom' | 'top';   // Default position
    margin?: string;               // Margin
    opacity?: number;              // Opacity (0-1)
    textShadow?: string;           // Text shadow
    fontWeight?: string | number;   // Font weight
    lineHeight?: string;           // Line height
    maxWidth?: string;             // Max width
    wordWrap?: 'break-word' | 'normal';
    zIndex?: number;               // Z-index
    border?: string;               // Border
    boxShadow?: string;            // Box shadow
  };
}

Features:

✅ Drag & Drop: Click and drag captions anywhere on the video
✅ Mobile Touch: Touch and drag on mobile devices
✅ Boundary Constraints: Captions stay within video player bounds
✅ Visual Feedback: Hover effects and drag indicators
✅ Position Memory: Captions remember their position after dragging
✅ Full Styling: Complete control over appearance and positioning

⏩ Live Seek Drag

The video player includes YouTube-style live seek dragging for smooth video scrubbing:

import React from 'react';
import { VideoPlayer } from 'react-video-player';

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    title="Live Seek Demo"
    // Live seek drag is enabled by default
    // Just drag the seek bar thumb to scrub through the video
  />
);

Live Seek Features:

✅ Real-time Scrubbing: Drag the seek bar thumb to jump through video
✅ Live Preview: See video content as you drag through the timeline
✅ Smooth Interaction: No delay between drag and video response
✅ Cross-platform: Works on both desktop and mobile devices
✅ Enhanced Feedback: Thumb grows during drag for better grip
✅ Touch Optimized: Finger-friendly dragging on mobile devices

📝 Basic Usage Example

import React from 'react';
import { VideoPlayer } from 'react-video-player';
import 'react-video-player/dist/index.css';

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    poster="/images/thumb.jpg"
    captions="/captions/subtitles.vtt"
    title="Advanced Demo Player"
    theme="light"
    autoplay={false}
    loop={false}
    muted={false}
    controls={true}
    width="800px"
    height="450px"
    className="my-custom-player"
    style={{ borderRadius: '12px' }}
    onPlay={() => console.log('Video started')}
    onPause={() => console.log('Video paused')}
    onTimeUpdate={(time) => console.log('Time:', time)}
    onVolumeChange={(vol) => console.log('Volume:', vol)}
    onSeek={(time) => console.log('Seeked to:', time)}
    onEnded={() => console.log('Ended')}
    onError={(err) => console.error('Error:', err)}
  />
);

🎮 Keyboard Shortcuts

| Action | Keys | | ----------------- | --------- | | Play / Pause | Space / K | | Seek -10s | ← / J | | Seek +10s | → / L | | Volume Up | ↑ | | Volume Down | ↓ | | Mute / Unmute | M | | Fullscreen Toggle | F | | Speed Down | Shift + , | | Speed Up | Shift + . | | Go to Start | Home | | Go to End | End |

📋 Props API

Basic Props

| Prop | Type | Default | Description | | --------------- | --------------------- | ----------- | ----------------------------------- | | src | string \| string[] \| PlaylistItem[] | — (req) | Video source URL(s) or playlist | | poster | string | undefined | Poster image | | captions | string \| SubtitleTrack[] | undefined | WebVTT subtitles file or array | | customCaptions| CaptionConfig[] | undefined | Custom draggable captions array | | title | string | undefined | Accessible title for screen readers | | description | string | undefined | Video description | | theme | 'light' \| 'dark' | 'dark' | UI Theme | | autoplay | boolean | false | Autoplay on load | | loop | boolean | false | Loop the video | | muted | boolean | false | Mute by default | | controls | boolean | true | Show/hide player controls | | width | string \| number | '100%' | Custom player width | | height | string \| number | 'auto' | Custom player height | | className | string | '' | Custom class for the wrapper | | style | React.CSSProperties | {} | Inline styles |

Advanced Props

| Prop | Type | Default | Description | | ----------------------- | --------------------- | ----------- | ----------------------------------- | | chapters | Chapter[] | undefined | Video chapters array | | qualities | VideoQuality[] | undefined | Video quality options | | enablePictureInPicture| boolean | true | Enable Picture-in-Picture mode | | enableTheaterMode | boolean | true | Enable Theater mode | | enableAnalytics | boolean | false | Enable analytics tracking | | enableSocialShare | boolean | true | Enable social sharing | | enableKeyboardShortcuts| boolean | true | Enable keyboard shortcuts | | showKeyboardShortcutsHelp| boolean | false | Show keyboard shortcuts help | | theaterMode | boolean | false | Initial theater mode state | | controlOptions | ControlOptions | undefined | Control customization options |

🧠 Event Callbacks

| Callback | Type | Description | | ------------------- | -------------------------- | ------------------------------ | | onPlay | () => void | Triggered when playback starts | | onPause | () => void | Triggered when paused | | onTimeUpdate | (time: number) => void | On time change during playback | | onVolumeChange | (volume: number) => void | On volume update | | onSeek | (time: number) => void | When seeking is done | | onEnded | () => void | When video ends | | onError | (error: string) => void | If video load/playback fails | | onChapterChange | (chapter: Chapter) => void| When chapter changes | | onQualityChange | (quality: string) => void| When quality changes | | onSubtitleChange | (language: string) => void| When subtitle language changes | | onPlaylistItemChange | (index: number, item: PlaylistItem) => void | When playlist item changes | | onAnalyticsUpdate | (data: AnalyticsData) => void | Analytics data update | | onShare | (timestamp?: number) => void | When video is shared |

🎨 Customization

The video player offers extensive customization options through the controlOptions prop, allowing you to control visibility, styling, and behavior of all controls.

Control Options

The controlOptions prop provides complete control over the player's appearance and functionality:

import { VideoPlayer, ControlOptions } from 'react-video-player';

const controlOptions: ControlOptions = {
  // Visibility toggles
  showPlayButton: true,
  showVolumeControl: true,
  showTimeDisplay: true,
  showSeekBar: true,
  showPlaybackSpeed: true,
  showQualitySelector: true,
  showCaptionsButton: true,
  showFullscreenButton: true,
  showPictureInPictureButton: true,
  showTheaterModeButton: true,
  showSocialShare: true,
  showChapterMarkers: true,

  // Button styles
  playButtonStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    hoverBackgroundColor: 'rgba(0, 0, 0, 0.9)',
    color: 'white',
    borderRadius: '50%',
    width: '48px',
    height: '48px'
  },

  volumeButtonStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    hoverBackgroundColor: 'rgba(0, 0, 0, 0.7)',
    color: 'white',
    borderRadius: '50%'
  },

  controlButtonStyle: {
    backgroundColor: 'transparent',
    hoverBackgroundColor: 'rgba(255, 255, 255, 0.2)',
    color: 'white',
    padding: '8px',
    width: '44px',
    height: '44px'
  },

  // Seek bar styles
  seekBarStyle: {
    height: '8px',
    hoverHeight: '14px',
    backgroundColor: 'rgba(255, 255, 255, 0.3)',
    playedColor: '#ff0000',
    bufferedColor: 'rgba(255, 255, 255, 0.4)',
    thumbColor: '#ff0000',
    thumbSize: '16px',
    hoverThumbSize: '22px',
    borderRadius: '4px'
  },

  // Volume slider styles
  volumeSliderStyle: {
    width: '120px',
    height: '44px',
    backgroundColor: 'transparent',
    fillColor: '#ff0000',
    thumbColor: 'white',
    thumbSize: '14px',
    borderRadius: '22px'
  },

  // Time display styles
  timeDisplayStyle: {
    fontSize: '14px',
    fontWeight: 500,
    color: 'white',
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    backdropFilter: 'blur(10px) saturate(180%)',
    borderColor: 'rgba(255, 255, 255, 0.1)',
    borderRadius: '4px',
    padding: '4px 8px',
    textShadow: '0 1px 2px rgba(0, 0, 0, 0.8)'
  },

  // Controls bar styles
  controlsBarStyle: {
    backgroundColor: 'transparent',
    padding: '0',
    gap: '12px',
    borderRadius: '0',
    height: '44px',
    minHeight: '44px'
  },

  // Tooltip styles
  tooltipStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.9)',
    color: 'white',
    fontSize: '12px',
    fontWeight: 500,
    padding: '6px 10px',
    borderRadius: '4px',
    showDelay: 500,
    hideDelay: 0
  },

  // Menu styles
  playbackSpeedMenuStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.9)',
    backdropFilter: 'blur(10px) saturate(180%)',
    borderColor: 'rgba(255, 255, 255, 0.1)',
    borderRadius: '8px',
    padding: '8px',
    fontSize: '14px',
    color: 'white',
    textShadow: 'rgba(0, 0, 0, 0.5) 0px 0px 2px'
  },

  qualityMenuStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.9)',
    backdropFilter: 'blur(10px) saturate(180%)',
    borderColor: 'rgba(255, 255, 255, 0.1)',
    borderRadius: '8px',
    padding: '8px',
    fontSize: '14px',
    color: 'white',
    textShadow: 'rgba(0, 0, 0, 0.5) 0px 0px 2px'
  },

  shareMenuStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.9)',
    backdropFilter: 'blur(10px) saturate(180%)',
    borderColor: 'rgba(255, 255, 255, 0.1)',
    borderRadius: '8px',
    padding: '8px',
    fontSize: '14px',
    color: 'white',
    textShadow: 'rgba(0, 0, 0, 0.5) 0px 0px 2px'
  },

  // Custom CSS variables (for advanced customization)
  customCSSVariables: {
    'custom-color': '#ff0000',
    'custom-size': '20px'
  }
};

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    controlOptions={controlOptions}
  />
);

Control Options Interface

interface ControlOptions {
  // Visibility toggles
  showPlayButton?: boolean;
  showVolumeControl?: boolean;
  showTimeDisplay?: boolean;
  showSeekBar?: boolean;
  showPlaybackSpeed?: boolean;
  showQualitySelector?: boolean;
  showCaptionsButton?: boolean;
  showFullscreenButton?: boolean;
  showPictureInPictureButton?: boolean;
  showTheaterModeButton?: boolean;
  showSocialShare?: boolean;
  showChapterMarkers?: boolean;

  // Button styles
  playButtonStyle?: ControlButtonStyle;
  volumeButtonStyle?: ControlButtonStyle;
  controlButtonStyle?: ControlButtonStyle;
  rightControlsButtonStyle?: ControlButtonStyle;

  // Menu styles
  playbackSpeedMenuStyle?: ControlMenuStyle;
  qualityMenuStyle?: ControlMenuStyle;
  shareMenuStyle?: ControlMenuStyle;

  // Seek bar styles
  seekBarStyle?: {
    height?: string;
    hoverHeight?: string;
    backgroundColor?: string;
    playedColor?: string;
    bufferedColor?: string;
    thumbColor?: string;
    thumbSize?: string;
    hoverThumbSize?: string;
    borderRadius?: string;
  };

  // Volume slider styles
  volumeSliderStyle?: {
    width?: string;
    height?: string;
    backgroundColor?: string;
    fillColor?: string;
    thumbColor?: string;
    thumbSize?: string;
    borderRadius?: string;
  };

  // Time display styles
  timeDisplayStyle?: {
    fontSize?: string;
    fontWeight?: string | number;
    color?: string;
    backgroundColor?: string;
    backdropFilter?: string;
    borderColor?: string;
    borderRadius?: string;
    padding?: string;
    textShadow?: string;
  };

  // Controls bar styles
  controlsBarStyle?: {
    backgroundColor?: string;
    padding?: string;
    gap?: string;
    borderRadius?: string;
    minHeight?: string;
    height?: string;
  };

  // Tooltip styles
  tooltipStyle?: {
    backgroundColor?: string;
    color?: string;
    fontSize?: string;
    fontWeight?: string | number;
    padding?: string;
    borderRadius?: string;
    showDelay?: number;
    hideDelay?: number;
  };

  // Custom CSS variables (for advanced customization)
  customCSSVariables?: Record<string, string>;
}

interface ControlButtonStyle {
  backgroundColor?: string;
  hoverBackgroundColor?: string;
  activeBackgroundColor?: string;
  color?: string;
  borderColor?: string;
  borderRadius?: string;
  fontSize?: string;
  fontWeight?: string | number;
  padding?: string;
  width?: string;
  height?: string;
  minWidth?: string;
  minHeight?: string;
}

interface ControlMenuStyle {
  backgroundColor?: string;
  backdropFilter?: string;
  borderColor?: string;
  borderRadius?: string;
  padding?: string;
  fontSize?: string;
  fontWeight?: string | number;
  color?: string;
  textShadow?: string;
}

Example: Minimal Player

Create a minimal player with only essential controls:

<VideoPlayer
  src="/videos/sample.mp4"
  controlOptions={{
    showPlayButton: true,
    showVolumeControl: true,
    showTimeDisplay: true,
    showSeekBar: true,
    showPlaybackSpeed: false,
    showQualitySelector: false,
    showCaptionsButton: false,
    showFullscreenButton: true,
    showPictureInPictureButton: false,
    showTheaterModeButton: false,
    showSocialShare: false,
    showChapterMarkers: false
  }}
/>

Example: Custom Styled Player

Customize the appearance to match your brand:

<VideoPlayer
  src="/videos/sample.mp4"
  controlOptions={{
    playButtonStyle: {
      backgroundColor: 'rgba(255, 0, 0, 0.8)',
      hoverBackgroundColor: 'rgba(255, 0, 0, 1)',
      borderRadius: '50%',
      width: '56px',
      height: '56px'
    },
    seekBarStyle: {
      height: '10px',
      hoverHeight: '16px',
      playedColor: '#ff0000',
      thumbColor: '#ff0000',
      thumbSize: '18px',
      hoverThumbSize: '24px'
    },
    timeDisplayStyle: {
      fontSize: '16px',
      fontWeight: 600,
      color: '#ffffff',
      backgroundColor: 'rgba(0, 0, 0, 0.7)',
      borderRadius: '8px',
      padding: '6px 12px'
    }
  }}
/>

CSS Variables

You can also customize the player using CSS variables directly:

.rvp-video-player {
  /* Play Button */
  --rvp-play-btn-bg: rgba(0, 0, 0, 0.5);
  --rvp-play-btn-hover-bg: rgba(0, 0, 0, 0.9);
  --rvp-play-btn-color: white;
  --rvp-play-btn-radius: 50%;
  --rvp-play-btn-width: 48px;
  --rvp-play-btn-height: 48px;

  /* Seek Bar */
  --rvp-seekbar-height: 8px;
  --rvp-seekbar-hover-height: 14px;
  --rvp-seekbar-played: #ff0000;
  --rvp-seekbar-thumb: #ff0000;
  --rvp-seekbar-thumb-size: 16px;
  --rvp-seekbar-thumb-hover-size: 22px;

  /* Volume Slider */
  --rvp-volume-slider-width: 120px;
  --rvp-volume-slider-fill: #ff0000;
  --rvp-volume-slider-thumb: white;

  /* Time Display */
  --rvp-time-font-size: 14px;
  --rvp-time-color: white;
  --rvp-time-bg: rgba(0, 0, 0, 0.5);

  /* Tooltip */
  --rvp-tooltip-bg: rgba(0, 0, 0, 0.9);
  --rvp-tooltip-color: white;
  --rvp-tooltip-font-size: 12px;
}

🧩 Project Structure

react-video-player/ ├── src/ │ ├── components/ # All modular player components │ ├── hooks/ # Custom video hook │ ├── types/ # Type definitions │ ├── styles/ # CSS styles │ └── index.ts # Entry point ├── demo/ # Vite + manual CSS demo project ├── dist/ # Compiled output ├── package.json ├── tsconfig.json └── README.md

📚 Additional Examples

Quality Selection

import { VideoPlayer, VideoQuality } from 'react-video-player';

const qualities: VideoQuality[] = [
  { label: '1080p', value: '1080p', src: '/videos/sample-1080p.mp4' },
  { label: '720p', value: '720p', src: '/videos/sample-720p.mp4' },
  { label: '480p', value: '480p', src: '/videos/sample-480p.mp4' },
  { label: '360p', value: '360p', src: '/videos/sample-360p.mp4' }
];

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    qualities={qualities}
    onQualityChange={(quality) => console.log('Quality changed to:', quality)}
  />
);

Chapters Support

import { VideoPlayer, Chapter } from 'react-video-player';

const chapters: Chapter[] = [
  { title: 'Introduction', startTime: 0, endTime: 30 },
  { title: 'Main Content', startTime: 30, endTime: 120 },
  { title: 'Conclusion', startTime: 120, endTime: 150 }
];

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    chapters={chapters}
    onChapterChange={(chapter) => console.log('Chapter:', chapter.title)}
  />
);

Playlist Support

import { VideoPlayer, PlaylistItem } from 'react-video-player';

const playlist: PlaylistItem[] = [
  { src: '/videos/video1.mp4', title: 'Video 1', poster: '/posters/video1.jpg' },
  { src: '/videos/video2.mp4', title: 'Video 2', poster: '/posters/video2.jpg' },
  { src: '/videos/video3.mp4', title: 'Video 3', poster: '/posters/video3.jpg' }
];

const App = () => (
  <VideoPlayer
    src={playlist}
    onPlaylistItemChange={(index, item) => {
      console.log('Playing:', item.title, 'at index:', index);
    }}
  />
);

❌ Not Using

This package does NOT depend on:

react-player
video.js
hls.js
External UI frameworks
Redux or global state

It’s written with vanilla React, DOM APIs, and TypeScript — fully maintainable and modular.

🤝 Contributing

We welcome feature suggestions, bug reports, and contributions!

📁 Clone the repo
💻 Create a feature branch
✅ Submit a PR

📄 License

Made with ❤️ and TypeScript by Arun YT

🌟 Feedback Welcome

If you like this project, please consider giving it a star ⭐ and leaving feedback through GitHub Issues.
Your support helps keep this project actively maintained and improved.

📢 Discoverability Boost

To help more developers find and benefit from this project, it’s being submitted to: