npm package: @kuldeep363/interactive-video-player
Description: InteractiveVideoPlayer is a custom, lightweight, and fully React-based HTML5 video player component. It provides enhanced interactivity through dynamic overlays, custom video controls, and fullscreen support, all without relying on third-party. It is desi
Author: Kuldeep Rawat
Latest version: 1.1.0

# 🎬 InteractiveVideoPlayer

A modern, customizable, React-based HTML5 video player with timed overlays, fullscreen support, and custom controls — all built **without bulky libraries**.

> ⚡ Lightweight · 🚀 Performant · 🎨 Fully Styleable · 🧠 Built for Interactive Content

---

## ✨ Features

* ✅ Native HTML5 `<video>` — no external video libraries
* 🧩 Time-based overlays (auto-pause supported)
* 🎮 Custom controls (play, pause, mute, fullscreen, seek)
* 🖼️ Poster image support
* ⛶ Fullscreen mode (desktop & iOS)
* 📱 Fully responsive
* 🎨 Easily styleable via props
* 💡 Designed for learning, onboarding, training, and media-rich storytelling

---

## 📦 Installation

```bash
# Required for icons
npm install @phosphor-icons/react

# Install the video player component
npm install @kuldeep363/interactive-video-player
```

---

## ⚡ Quick Usage

```tsx
import InteractiveVideoPlayer from "@kuldeep363/interactive-video-player";

const overlays = [
  {
    id: "intro",
    start: 5,
    end: 10,
    content: <div className="p-4 bg-white rounded">👋 Welcome!</div>,
    stopOnEntry: true,
  },
  {
    id: "cta",
    start: 15,
    end: 20,
    content: (
      <button
        className="px-4 py-2 bg-blue-600 text-white rounded"
        onClick={() => alert("CTA Clicked")}
      >
        Learn More
      </button>
    ),
  },
];

export default function App() {
  return (
    <InteractiveVideoPlayer
      videoSrc="/videos/sample.mp4"
      poster="/images/poster.jpg"
      overlays={overlays}
      width="100%"
      height="auto"
      containerClassName="max-w-4xl mx-auto mt-8"
      videoClassName="rounded-lg"
      overlayWrapperClassName="z-50"
      showSeekBar={true}
    />
  );
}
```

---

## ⚙️ Component Props

| Prop                      | Type        | Default     | Description                        |
| ------------------------- | ----------- | ----------- | ---------------------------------- |
| `videoSrc`                | `string`    | *required*  | Video file source URL              |
| `poster`                  | `string`    | `undefined` | Optional poster image              |
| `overlays`                | `Overlay[]` | `[]`        | Array of timed overlays            |
| `width`                   | `string`    | `"100%"`    | Player container width             |
| `height`                  | `string`    | `"auto"`    | Player container height            |
| `containerClassName`      | `string`    | `""`        | Custom class for outer container   |
| `videoClassName`          | `string`    | `""`        | Custom class for `<video>` element |
| `overlayWrapperClassName` | `string`    | `""`        | Custom class for overlay wrapper   |
| `controlsClassName`       | `string`    | `""`        | Custom class for controls wrapper  |
| `showControls`            | `boolean`   | `true`      | Show or hide playback controls     |
| `showSeekBar`             | `boolean`   | `true`      | Show or hide seek bar              |

---

## 🧩 Overlay Config

Overlays appear at specific video times. Great for quizzes, CTAs, or interactive content.

### `Overlay` Type

```ts
type Overlay = {
  id: string;
  content: React.ReactNode;
  start?: number;
  end?: number;
  offset?: number;
  relativeTo?: "start" | "end";
  duration?: number;
  stopOnEntry?: boolean;
  onClick?: (resume: () => void) => void;
};
```

| Prop          | Type                           | Required | Description                                      |
| ------------- | ------------------------------ | -------- | ------------------------------------------------ |
| `id`          | `string`                       | ✅ Yes    | Unique ID                                        |
| `content`     | `React.ReactNode`              | ✅ Yes    | JSX/HTML to display                              |
| `start`       | `number`                       | ❌ No     | Absolute start time in seconds                   |
| `end`         | `number`                       | ❌ No     | Absolute end time in seconds                     |
| `offset`      | `number`                       | ❌ No     | Relative time (requires `relativeTo`)            |
| `relativeTo`  | `"start"` \| `"end"`           | ❌ No     | Base for `offset`                                |
| `duration`    | `number`                       | ❌ No     | Duration to display overlay (used with `offset`) |
| `stopOnEntry` | `boolean`                      | ❌ No     | Pause video when overlay appears                 |
| `onClick`     | `(resume: () => void) => void` | ❌ No     | Resume playback via callback                     |

---

## 🧪 Overlay Example

```tsx
const overlays = [
  {
    id: "quiz-1",
    offset: 5,
    duration: 5,
    relativeTo: "start",
    stopOnEntry: true,
    content: (
      <div style={{ background: "#fff", padding: "1rem", borderRadius: "8px" }}>
        <h4>Quick Question</h4>
        <p>What is the capital of France?</p>
        <button onClick={() => alert("Correct!")}>Paris</button>
      </div>
    ),
  },
  {
    id: "customPause",
    offset: 15,
    relativeTo: "start",
    stopOnEntry: true,
    content: <div className="overlay">Processing...</div>,
    onClick: async (resume) => {
      await new Promise((res) => setTimeout(res, 1500));
      resume();
    },
  },
];
```

---

## 🧰 Control Features

| Feature       | Description             |
| ------------- | ----------------------- |
| ▶️ Play/Pause | Toggle playback         |
| 🔇 Mute       | Toggle audio            |
| 📈 Seek Bar   | Scrub through video     |
| ⛶ Fullscreen  | Desktop & iOS support   |
| 📱 Mobile     | Fully responsive layout |

---

## 🎨 Styling & Customization

Style everything via class props:

| Prop Name                 | Affects            |
| ------------------------- | ------------------ |
| `containerClassName`      | Outer player shell |
| `videoClassName`          | `<video>` element  |
| `overlayWrapperClassName` | Overlay container  |
| `controlsClassName`       | Bottom control bar |

Also supports Tailwind or custom CSS. Include your own `.css` if needed.

---

## 📁 Suggested Project Structure

```
src/
├── components/
│   └── InteractiveVideoPlayer.tsx
├── pages/
│   └── index.tsx
public/
├── videos/
│   └── demo.mp4
├── images/
│   └── poster.jpg
```

---

## 🛠 Roadmap

* [ ] Volume slider
* [ ] Keyboard shortcuts
* [ ] Playback speed control
* [ ] Subtitles support
* [ ] Accessibility (ARIA)
* [ ] Preview thumbnails on seek
* [ ] Buffer/load indicators

---

## 📜 License

MIT — Free for personal or commercial use.

---

## 🤝 Contributing

1. Fork this repo
2. Create a branch: `git checkout -b feature/your-feature`
3. Make changes and commit: `git commit -m "Add feature"`
4. Push changes: `git push origin feature/your-feature`
5. Open a pull request

---

## 👤 Author

**Kuldeep Rawat**
[🔗 kuldeeprawat.com](https://kuldeeprawat.com)

---

### 💬 Questions? Feedback?

* Open a GitHub issue
* Submit a PR
* Share ideas — Let’s build the best interactive player together!