seamless-vid-player 📺

A highly polished, seamless, and fully responsive video player component for Next.js and React. Built with precision to replicate the premium animations, layout, and UX of high-end video platforms.

✨ Features

• Seamless UI: Butter-smooth animations and transitions.
• Adaptive Bitrate Streaming: Built-in support for HLS (.m3u8) and DASH (.mpd) via hls.js and dashjs.
• Dynamic Quality Selector: Automatic resolution detection and manual quality switching menu.
• Efficient Scrubbing: High-performance timeline scrubbing using WebVTT Sprite Sheets.
• Keyboard Mastery: Standard shortcuts out of the box (Space, K, M, F, J, L, C, etc.).
• Next.js & SSR Ready: Fully optimized for Next.js 13/14 App Router.

🚀 Installation

npm install seamless-vid-player lucide-react hls.js dashjs

🛠 Usage

1. Implementation

Import the global styles and the component into your page:

import "seamless-vid-player/styles.css";
import { YouTubePlayer } from 'seamless-vid-player';

export default function VideoPage() {
  return (
    <div className="max-w-5xl mx-auto p-4">
      <YouTubePlayer 
        src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" 
        title="Video Demo"
        eyebrow="Streaming Test"
        description="Experience seamless playback with dynamic quality switching."
        badges={["4K", "HLS"]}
        defaultTheaterMode
      />
    </div>
  );
}

2. Controlled Theater Mode

import { useState } from "react";
import "seamless-vid-player/styles.css";
import { YouTubePlayer } from "seamless-vid-player";

export default function VideoPage() {
  const [isTheaterMode, setIsTheaterMode] = useState(false);

  return (
    <YouTubePlayer
      src="/video.mp4"
      title="Programmable Theater Mode"
      theaterMode={isTheaterMode}
      onTheaterModeChange={setIsTheaterMode}
    />
  );
}

3. Local Test App

A ready-to-run consumer scaffold lives in test-scaffold/. It installs the package from the parent folder so you can test the published API or local changes without touching the demo app.

cd test-scaffold
npm install
npm run dev

📖 Props

| Prop | Type | Required | Description | | :--- | :--- | :---: | :--- | | src | string | Yes | Path or URL to the video file (.mp4, .m3u8, .mpd). | | title | string | Yes | The primary title of the video. | | description | string | No | A longer description text shown below the title. | | eyebrow | string | No | Small uppercase text shown above the title. | | badges | string[] | No | Array of tags (e.g. ['HD', 'CC']) shown next to the title. | | thumbnailTrackSrc| string | No | Path to a .vtt file for sprite-sheet based hover previews. | | captionsSrc | string | No | Path to a .vtt captions file. | | theaterMode | boolean | No | Controlled theater mode state. When provided, the component becomes externally controlled. | | defaultTheaterMode | boolean | No | Initial theater mode value for uncontrolled usage. | | onTheaterModeChange | (isTheaterMode: boolean) => void | No | Fired whenever theater mode is toggled from keyboard or UI. |

⌨️ Keyboard Shortcuts

| Key | Action | | :---: | :--- | | Space / K | Play / Pause | | M | Mute / Unmute | | F | Toggle Fullscreen | | T | Toggle Theater Mode | | C | Toggle Captions | | J / Left Arrow | Skip Backward 5s | | L / Right Arrow | Skip Forward 5s | | I | Open Miniplayer (PiP) |

🖼 Generating Thumbnails (WebVTT)

For efficient scrubbing, use the included process-video.sh script or your own ffmpeg command to generate a sprite sheet and VTT coordinates:

# Example ffmpeg command for a 5x5 sprite grid
ffmpeg -i video.mp4 -vf "fps=1/10,scale=160:90,tile=5x5" sprite.jpg

📜 License

MIT © [Your Name]