React Video Master

A modern, responsive React video player component with customizable controls, thumbnail previews, and multiple viewing modes.

Features

🎮 Responsive Controls: Play/pause, volume, timeline, fullscreen, and more
🎛️ Playback Control: Speed control, skip forward/backward
📱 Multiple Viewing Modes: Standard, theater, fullscreen, and picture-in-picture
👍 Modern UI: Clean, minimal interface with customizable styles
🖼️ Video Thumbnails: Preview thumbnails when hovering over the timeline
⌨️ Keyboard Shortcuts: Navigation and control via keyboard
🎯 Timeline Scrubbing: Intuitive timeline navigation
🔊 Volume Controls: Mute, volume slider with visual indicators
🔄 Progress Tracking: Visual display of video progress
📦 TypeScript Support: Full type definitions included
🪝 Custom Hooks: Access player state and controls in your application
🔌 Callback Support: Hooks for play, pause, end, and other events
🛠️ React 18/19 Compatible: Works with the latest React versions
🔄 Context Provider: Access video controls and state from anywhere in your app

Installation

npm install react-video-master
# or
yarn add react-video-master
# or
pnpm add react-video-master

Quick Start

import React from 'react';
import { VideoPlayer } from 'react-video-master';
// if needed
import 'react-video-master/style.css';

function App() {
  return (
    <div className="app">
      <VideoPlayer 
        src="https://example.com/video.mp4"
        onPlay={() => console.log('Video started playing')}
        onPause={() => console.log('Video paused')}
        onEnded={() => console.log('Video ended')}
      />
    </div>
  );
}

export default App;

Props

The VideoPlayer component accepts the following props:

Prop	Type	Default	Description
`src`	`string`	Required	URL of the video source
`paused`	`boolean`	`true`	Initial paused state of the video
`speed`	`number`	`1`	Initial playback speed
`onPlay`	`() => void`	`undefined`	Callback triggered when video starts playing
`onPause`	`() => void`	`undefined`	Callback triggered when video is paused
`onEnded`	`() => void`	`undefined`	Callback triggered when video ends
`onTimeUpdate`	`(currentTime: number, duration: number) => void`	`undefined`	Callback triggered on time update
`onVolumeChange`	`(volume: number, muted: boolean) => void`	`undefined`	Callback triggered when volume changes
`className`	`string`	`''`	Additional CSS class to apply to the container
`children`	`ReactNode`	`undefined`	Children elements to render inside the player

Context Provider

The library includes a ReactVideoProvider that makes it easy to access the video's state and controls from anywhere in your application.

import React from 'react';
import { VideoPlayer, ReactVideoProvider } from 'react-video-master';

function App() {
  return (
    <ReactVideoProvider>
      <div style={{ height: "300px", width: "100%" }}>
        <VideoPlayer src="https://example.com/video.mp4" />
      </div>
      <CustomControls />
    </ReactVideoProvider>
  );
}

Hooks

The library exports several hooks that allow you to control the video player programmatically:

useVideoStateContext

Access the video player's state from anywhere inside a ReactVideoProvider:

import { useVideoStateContext } from 'react-video-master';

function VideoInfo() {
  const { isPaused, currentTime, totalTime, playbackSpeed } = useVideoStateContext();
  
  return (
    <div>
      <p>Status: {isPaused ? 'Paused' : 'Playing'}</p>
      <p>Current time: {currentTime}</p>
      <p>Total time: {totalTime}</p>
      <p>Playback speed: {playbackSpeed}</p>
    </div>
  );
}

useVideoControlsContext

Control the video player programmatically from anywhere inside a ReactVideoProvider:

import { useVideoControlsContext } from 'react-video-master';

function CustomControls() {
  const { togglePlay, toggleMute, skip, changePlaybackSpeed } = useVideoControlsContext();
  
  return (
    <div className="custom-controls">
      <button onClick={togglePlay}>Play/Pause</button>
      <button onClick={toggleMute}>Mute/Unmute</button>
      <button onClick={() => skip(-10)}>Rewind 10s</button>
      <button onClick={() => skip(10)}>Forward 10s</button>
      <button onClick={changePlaybackSpeed}>Change Speed</button>
    </div>
  );
}

Other Context Hooks

useTimeUpdate: Access time update functionality
useVideoEventsContext: Access video event handlers
useScrubbing: Access timeline scrubbing functionality

Keyboard Shortcuts

The player supports the following keyboard shortcuts:

Key	Action
`Space` or `K`	Play/Pause
`M`	Mute/Unmute
`F`	Toggle Fullscreen
`T`	Toggle Theater Mode
`I`	Toggle Picture-in-Picture
`Arrow Left` or `J`	Rewind 5 seconds
`Arrow Right` or `L`	Forward 5 seconds

Player Modes

Theater Mode

Theater mode expands the video to take up more screen width while maintaining its position in the page:

<VideoPlayer src="https://example.com/video.mp4" />
// User can toggle theater mode with the theater button or 'T' key

Fullscreen Mode

Fullscreen mode expands the video to cover the entire screen:

<VideoPlayer src="https://example.com/video.mp4" />
// User can toggle fullscreen mode with the fullscreen button or 'F' key

Picture-in-Picture Mode

Picture-in-Picture mode allows the video to be played in a small floating window:

<VideoPlayer src="https://example.com/video.mp4" />
// User can toggle PiP mode with the mini-player button or 'I' key

Customization

Styling

The component comes with a default styling that you can customize by overriding CSS variables or classes:

/* Override the primary color */
.ps-video-container {
  --primary-color: #ff0000;
}

/* Customize the timeline */
.ps-timeline::after {
  background-color: var(--primary-color);
}

Advanced Usage

Minimal Example with ReactVideoProvider

This is the simplest way to use the context provider and hooks:

import React from 'react';
import { VideoPlayer, ReactVideoProvider, useVideoControlsContext } from 'react-video-master';

// Simple custom control component
function PlayPauseButton() {
  // Access controls through context
  const { togglePlay } = useVideoControlsContext();
  
  return (
    <button onClick={togglePlay}>Play/Pause</button>
  );
}

// Main component
function App() {
  return (
    <ReactVideoProvider>
      <div style={{ height: "300px", width: "100%" }}>
        <VideoPlayer src="https://example.com/video.mp4" />
      </div>
      <PlayPauseButton />
    </ReactVideoProvider>
  );
}

Complete Example with State Management

For more complex scenarios with state management:

import React, { useState } from 'react';
import { VideoPlayer, ReactVideoProvider, useVideoControlsContext, useVideoStateContext } from 'react-video-master';

function CustomControls() {
  // Access context through hooks
  const controls = useVideoControlsContext();
  const state = useVideoStateContext();

  return (
    <div className="custom-controls">
      <button onClick={controls.togglePlay}>
        {state.isPaused ? 'Play' : 'Pause'}
      </button>
      <button onClick={controls.toggleMute}>Mute/Unmute</button>
      <button onClick={() => controls.skip(-10)}>Rewind 10s</button>
      <button onClick={() => controls.skip(10)}>Forward 10s</button>
      <button onClick={controls.changePlaybackSpeed}>Change Speed</button>
      
      {/* Progress bar */}
      <div className="progress-bar">
        <div className="progress" style={{ width: `${state.percent * 100}%` }} />
      </div>
    </div>
  );
}

function VideoApp() {
  const [isPaused, setIsPaused] = useState(true);

  const handlePlay = () => setIsPaused(false);
  const handlePause = () => setIsPaused(true);
  const handleEnded = () => setIsPaused(true);

  return (
    <ReactVideoProvider>
      <div style={{ height: "300px", width: "800px", position: "relative" }}>
        <VideoPlayer
          src="https://example.com/video.mp4"
          paused={isPaused}
          speed={1}
          onPlay={handlePlay}
          onPause={handlePause}
          onEnded={handleEnded}
          className="custom-player"
        />
      </div>
      <CustomControls />
    </ReactVideoProvider>
  );
}

Using with Multiple Players

import React from 'react';
import { VideoPlayer, ReactVideoProvider } from 'react-video-master';

function MultiplePlayersApp() {
  return (
    <div className="multi-player-app">
      {/* Each ReactVideoProvider creates its own context */}
      <ReactVideoProvider>
        <VideoPlayer src="https://example.com/video1.mp4" />
        <PlayerControls id="player1" />
      </ReactVideoProvider>
      
      <ReactVideoProvider>
        <VideoPlayer src="https://example.com/video2.mp4" />
        <PlayerControls id="player2" />
      </ReactVideoProvider>
    </div>
  );
}

function PlayerControls({ id }) {
  const controls = useVideoControlsContext();
  
  return (
    <div className="player-controls">
      <span>{id}</span>
      <button onClick={controls.togglePlay}>Play/Pause</button>
      <button onClick={controls.toggleMute}>Mute/Unmute</button>
    </div>
  );
}

export default MultiplePlayersApp;

Browser Support

React Video Player works in all modern browsers that support HTML5 video:

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.