@zezosoft/react-player 0.0.8 → 0.0.10

package/README.md

@@ -1,35 +1,69 @@
 # @zezosoft/react-player 🎬
 
-A powerful and flexible **React video player** by **Zezosoft**, supporting HLS, MP4, preview thumbnails, tracking, subtitles, episode playback, and advanced controls.
+A powerful and flexible **React video player** by **Zezosoft**, supporting HLS, MP4, DASH, YouTube, preview thumbnails, tracking, subtitles, episode playback, ads, and advanced controls.
 
 ---
 
 ## 🚀 Features
 
-✅ **Supports HLS, MP4**  
-✅ **Preview Thumbnails on Hover**  
-✅ **Event Tracking (Views, Watch Time, etc.)**  
-✅ **Customizable Player Size & Controls**  
-✅ **Time-Stamped Labels for Video Chapters**  
-✅ **Subtitles (WebVTT)**  
-✅ **Intro Skipping**  
-✅ **Next Episode Auto Play and Button**
+✅ **Multiple Video Formats** - HLS, MP4, DASH, YouTube  
+✅ **Preview Thumbnails on Hover** - Show video previews while scrubbing  
+✅ **Event Tracking** - Track views, watch time, and user interactions  
+✅ **Customizable Player Size & Controls** - Full control over player appearance  
+✅ **Time-Stamped Labels** - Video chapters with time markers  
+✅ **Subtitles (WebVTT)** - Multi-language subtitle support with custom styling  
+✅ **Intro Skipping** - Automatic skip intro button  
+✅ **Episode Playback** - Next episode auto-play and playlist support  
+✅ **Ad Support** - Pre-roll, mid-roll, post-roll, and overlay ads  
+✅ **Watch History** - Track user progress and resume playback
 
 ---
 
 ## 📦 Installation
 
-Install the package using **npm**
+Install the package using **npm** or **yarn**:
 
 ```sh
 npm install @zezosoft/react-player
 ```
 
+or
+
+```sh
+yarn add @zezosoft/react-player
+```
+
 ---
 
-## 🛠️ Basic Usage
+## 🛠️ Quick Start
 
-Import and use the `VideoPlayer` component in your React project:
+Here's a simple example to get you started:
+
+```tsx
+import { VideoPlayer } from "@zezosoft/react-player";
+
+function App() {
+  return (
+    <VideoPlayer
+      video={{
+        src: "https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8",
+        title: "My Video",
+        poster: "https://example.com/poster.jpg",
+      }}
+      style={{
+        width: "100%",
+        height: "auto",
+      }}
+    />
+  );
+}
+```
+
+---
+
+## 📖 Complete Example
+
+Here's a comprehensive example showing all available features:
 
 ```tsx
 import { useCallback, useRef } from "react";
@@ -53,42 +87,99 @@ function App() {
   }, []);
 
   return (
-    <div className="w-[720px]">
+    <div style={{ width: "720px", margin: "0 auto" }}>
       <VideoPlayer
-        trackPoster="https://i.ytimg.com/vi/VAUfyxw-Yvk/maxresdefault.jpg"
-        trackSrc="https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8"
-        trackTitle="Mehmaan"
-        width="720px"
-        height="405px"
-        timeCodes={[
-          { fromMs: 0, description: "Introduction" },
-          { fromMs: 130000, description: "Exciting Scene" },
-          { fromMs: 270000, description: "Climax" },
-        ]}
-        getPreviewScreenUrl={handleGettingPreview}
-        tracking={{
-          onViewed: () => console.log("Video Viewed"),
-          onWatchTimeUpdated: (e) => console.log("Watch Time Updated", e),
+        video={{
+          src: "https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8",
+          title: "Mehmaan",
+          poster: "https://i.ytimg.com/vi/VAUfyxw-Yvk/maxresdefault.jpg",
+          type: "hls",
+          isTrailer: false,
+          showControls: true,
+          isMute: false,
+          startFrom: 0,
+        }}
+        style={{
+          width: "720px",
+          height: "405px",
+          className: "my-video-player",
+          subtitleStyle: {
+            fontSize: "1.5rem",
+            backgroundColor: "rgba(0, 0, 0, 0.8)",
+            textColor: "#ffffff",
+            position: "bottom",
+            borderRadius: "8px",
+            padding: "8px 16px",
+            maxWidth: "80%",
+          },
+        }}
+        events={{
+          onEnded: (e) => console.log("Video ended", e),
+          onError: (e) => console.error("Video error", e),
+          onClose: () => console.log("Player closed"),
+          onWatchHistoryUpdate: (data) => {
+            console.log("Watch history:", data);
+            // Save to your backend
+          },
         }}
-        subtitles={[
-          {
-            lang: "en",
-            label: "English",
-            url: "https://example.com/subtitles-en.vtt",
+        features={{
+          timeCodes: [
+            { fromMs: 0, description: "Introduction" },
+            { fromMs: 130000, description: "Exciting Scene" },
+            { fromMs: 270000, description: "Climax" },
+          ],
+          getPreviewScreenUrl: handleGettingPreview,
+          tracking: {
+            onViewed: () => console.log("Video Viewed"),
+            onWatchTimeUpdated: (e) => {
+              console.log("Watch Time Updated", {
+                watchTime: e.watchTime,
+                currentTime: e.currentTime,
+                duration: e.duration,
+              });
+            },
           },
-          {
-            lang: "hi",
-            label: "Hindi",
-            url: "https://example.com/subtitles-hi.vtt",
+          subtitles: [
+            {
+              lang: "en",
+              label: "English",
+              url: "https://example.com/subtitles-en.vtt",
+            },
+            {
+              lang: "hi",
+              label: "Hindi",
+              url: "https://example.com/subtitles-hi.vtt",
+            },
+          ],
+          episodeList: [
+            { id: 1, title: "Episode 1", url: "https://example.com/ep1.m3u8" },
+            { id: 2, title: "Episode 2", url: "https://example.com/ep2.m3u8" },
+          ],
+          currentEpisodeIndex: 0,
+          intro: { start: 5, end: 20 },
+          nextEpisodeConfig: { showAtTime: 300, showAtEnd: true },
+          ads: {
+            preRoll: {
+              id: "preroll-1",
+              type: "pre-roll",
+              time: 0,
+              adUrl: "https://example.com/ad.mp4",
+              skipable: true,
+              skipAfter: 5,
+            },
+            midRoll: [
+              {
+                id: "midroll-1",
+                type: "mid-roll",
+                time: 120,
+                adUrl: "https://example.com/mid-ad.mp4",
+                skipable: false,
+              },
+            ],
+            onAdStart: (adBreak) => console.log("Ad started", adBreak),
+            onAdEnd: (adBreak) => console.log("Ad ended", adBreak),
           },
-        ]}
-        episodeList={[
-          { id: 1, title: "Episode 1", url: "https://example.com/ep1.m3u8" },
-          { id: 2, title: "Episode 2", url: "https://example.com/ep2.m3u8" },
-        ]}
-        currentEpisodeIndex={0}
-        intro={{ start: 5, end: 20 }}
-        nextEpisodeConfig={{ showAtTime: 300, showAtEnd: true }}
+        }}
       />
     </div>
   );
@@ -99,185 +190,484 @@ export default App;
 
 ---
 
-## 🎨 Props Reference
-
-| Prop Name             | Type                                                  | Default     | Description                                                |
-| --------------------- | ----------------------------------------------------- | ----------- | ---------------------------------------------------------- |
-| `trackPoster`         | `string`                                              | `""`        | URL of the video poster image.                             |
-| `trackSrc`            | `string`                                              | `""`        | Video source URL (MP4, HLS, etc.).                         |
-| `trackTitle`          | `string`                                              | `""`        | Title of the video.                                        |
-| `isTrailer`           | `boolean`                                             | `false`     | Specifies if the video is a trailer.                       |
-| `width`               | `string`                                              | `"100%"`    | Width of the video player.                                 |
-| `height`              | `string`                                              | `"auto"`    | Height of the video player.                                |
-| `timeCodes`           | `Array<{ fromMs: number, description: string }>`      | `[]`        | List of time-based markers with descriptions.              |
-| `getPreviewScreenUrl` | `(timeMs: number) => string`                          | `null`      | Function to generate preview screen URLs based on time.    |
-| `tracking`            | `object`                                              | `{}`        | Tracking event callbacks.                                  |
-| `subtitles`           | `Array<{ lang: string; label: string; url: string }>` | `[]`        | Subtitle tracks in WebVTT format.                          |
-| `episodeList`         | `Array<{ id: number; title: string; url: string }>`   | `[]`        | List of episodes to support autoplay/playlist.             |
-| `currentEpisodeIndex` | `number`                                              | `0`         | Index of currently playing episode.                        |
-| `intro`               | `{ start: number; end: number }`                      | `undefined` | Defines intro duration in seconds.                         |
-| `nextEpisodeConfig`   | `{ showAtTime?: number; showAtEnd?: boolean }`        | `undefined` | When to show next episode UI — at specific time or at end. |
-|                       |
+## 📚 Props Reference
 
----
+The `VideoPlayer` component accepts four main prop objects:
 
-## 📢 Tracking Events
+### `video` (Required)
 
-| Event Name           | Description                                      |
-| -------------------- | ------------------------------------------------ |
-| `onViewed`           | Triggered when the video starts playing.         |
-| `onWatchTimeUpdated` | Triggered when user leaves with >30s watch time. |
+Video source and basic configuration.
 
-#### Example usage:
+| Prop           | Type                                               | Default      | Description                                             |
+| -------------- | -------------------------------------------------- | ------------ | ------------------------------------------------------- |
+| `src`          | `string`                                           | **Required** | Video source URL (MP4, HLS, DASH, YouTube, etc.)        |
+| `title`        | `string`                                           | `""`         | Title of the video displayed in the player header       |
+| `poster`       | `string`                                           | `""`         | URL of the poster/thumbnail image shown before playback |
+| `type`         | `"hls" \| "dash" \| "mp4" \| "youtube" \| "other"` | `undefined`  | Video format type (auto-detected if not provided)       |
+| `isTrailer`    | `boolean`                                          | `false`      | If `true`, shows trailer-specific UI elements           |
+| `showControls` | `boolean`                                          | `true`       | Show/hide player controls                               |
+| `isMute`       | `boolean`                                          | `false`      | Start video muted                                       |
+| `startFrom`    | `number`                                           | `0`          | Start playback from specific time in seconds            |
 
-```tsx
-tracking={{
-  onViewed: () => console.log("Viewed!"),
-  onWatchTimeUpdated: ({ watchTime }) =>
-    console.log("Total watch time (sec):", watchTime),
-}}
-```
+### `style` (Optional)
 
----
+Styling and appearance configuration.
 
-## 🎨 Customization & Styling
+| Prop            | Type                  | Default     | Description                                    |
+| --------------- | --------------------- | ----------- | ---------------------------------------------- |
+| `className`     | `string`              | `undefined` | Custom CSS class name for the player container |
+| `width`         | `string`              | `"100%"`    | Player width (e.g., `"720px"`, `"100%"`)       |
+| `height`        | `string`              | `"auto"`    | Player height (e.g., `"405px"`, `"auto"`)      |
+| `subtitleStyle` | `SubtitleStyleConfig` | `undefined` | Custom styling for subtitles (see below)       |
 
-🔹 Change Player Dimensions
+**SubtitleStyleConfig:**
 
-Modify `width` and `height`:
+| Prop              | Type                            | Default                                       | Description                        |
+| ----------------- | ------------------------------- | --------------------------------------------- | ---------------------------------- |
+| `fontSize`        | `string`                        | `"1.75rem"`                                   | Subtitle font size                 |
+| `backgroundColor` | `string`                        | `"linear-gradient(135deg, #fbbf24, #f59e0b)"` | Subtitle background color/gradient |
+| `textColor`       | `string`                        | `"#000000"`                                   | Subtitle text color                |
+| `position`        | `"top" \| "center" \| "bottom"` | `"bottom"`                                    | Vertical position of subtitles     |
+| `borderRadius`    | `string`                        | `"12px"`                                      | Border radius of subtitle box      |
+| `padding`         | `string`                        | `"12px 20px"`                                 | Padding inside subtitle box        |
+| `maxWidth`        | `string`                        | `"80%"`                                       | Maximum width of subtitle box      |
 
-```tsx
-<VideoPlayer width="800px" height="450px" />
+### `events` (Optional)
+
+Event callbacks for player lifecycle.
+
+| Prop                   | Type                                                          | Description                                        |
+| ---------------------- | ------------------------------------------------------------- | -------------------------------------------------- |
+| `onEnded`              | `(e: React.SyntheticEvent<HTMLVideoElement>) => void`         | Called when video playback ends                    |
+| `onError`              | `(e?: React.SyntheticEvent<HTMLVideoElement, Event>) => void` | Called when video encounters an error              |
+| `onClose`              | `() => void`                                                  | Called when player is closed                       |
+| `onWatchHistoryUpdate` | `(data: WatchHistoryData) => void`                            | Called when player closes with watch progress data |
+
+**WatchHistoryData:**
+
+```typescript
+{
+  currentTime: number; // Current playback time in seconds
+  duration: number; // Total video duration in seconds
+  progress: number; // Progress percentage (0-100)
+  isCompleted: boolean; // Whether video was fully watched
+  watchedAt: number; // Timestamp when watch session ended
+}
 ```
 
-🔹 Custom Preview Thumbnails
+### `features` (Optional)
+
+Advanced features and functionality.
+
+| Prop                  | Type                                             | Default     | Description                                                              |
+| --------------------- | ------------------------------------------------ | ----------- | ------------------------------------------------------------------------ |
+| `timeCodes`           | `Array<{ fromMs: number, description: string }>` | `[]`        | Time-based chapter markers (in milliseconds)                             |
+| `getPreviewScreenUrl` | `(hoverTimeValue: number) => string`             | `undefined` | Function to generate preview thumbnail URLs while hovering over seek bar |
+| `tracking`            | `TrackingConfig`                                 | `undefined` | Event tracking configuration (see below)                                 |
+| `subtitles`           | `Array<SubtitleTrack>`                           | `[]`        | Subtitle tracks in WebVTT format                                         |
+| `episodeList`         | `Array<Episode>`                                 | `[]`        | List of episodes for playlist/autoplay                                   |
+| `currentEpisodeIndex` | `number`                                         | `0`         | Index of currently playing episode                                       |
+| `intro`               | `{ start: number, end: number }`                 | `undefined` | Intro skip configuration (times in seconds)                              |
+| `nextEpisodeConfig`   | `{ showAtTime?: number, showAtEnd?: boolean }`   | `undefined` | Configuration for next episode button                                    |
+| `ads`                 | `AdConfig`                                       | `undefined` | Advertisement configuration (see below)                                  |
+
+**TrackingConfig:**
+
+```typescript
+{
+  onViewed?: () => void;
+  onWatchTimeUpdated?: (e: {
+    watchTime?: number;    // Total watch time in seconds
+    currentTime: number;   // Current playback position
+    duration: number;      // Total video duration
+  }) => void;
+}
+```
 
-Dynamically generate preview images:
+**SubtitleTrack:**
 
-```tsx
-const getPreviewImage = (hoverTime) =>
-  `https://fakeimg.pl/720x405?text=${hoverTime}`;
-<VideoPlayer getPreviewScreenUrl={getPreviewImage} />;
+```typescript
+{
+  lang: string; // Language code (e.g., "en", "hi", "fr")
+  label: string; // Display label (e.g., "English", "Hindi")
+  url: string; // URL to WebVTT subtitle file
+}
 ```
 
-🔹 Time-Stamps for Video Sections
+**Episode:**
 
-Mark important video sections:
+```typescript
+{
+  id: number; // Unique episode identifier
+  title: string; // Episode title
+  url: string; // Episode video URL
+}
+```
+
+**AdConfig:**
+
+```typescript
+{
+  preRoll?: AdBreak;                    // Pre-roll ad (plays before video)
+  midRoll?: AdBreak[];                  // Mid-roll ads (plays during video)
+  postRoll?: AdBreak;                   // Post-roll ad (plays after video)
+  overlay?: {                           // Overlay ad (image overlay)
+    imageUrl: string;
+    clickUrl?: string;
+    showDuration: number;
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+  };
+  smartPlacement?: {                    // Smart ad placement
+    enabled: boolean;
+    minVideoDuration?: number;
+    minGapBetweenAds?: number;
+    avoidNearEnd?: number;
+    preferNaturalBreaks?: boolean;
+  };
+  onAdStart?: (adBreak: AdBreak) => void;
+  onAdEnd?: (adBreak: AdBreak) => void;
+  onAdSkip?: (adBreak: AdBreak) => void;
+  onAdError?: (adBreak: AdBreak, error: Error) => void;
+}
+```
+
+**AdBreak:**
+
+```typescript
+{
+  id: string;                    // Unique ad identifier
+  type: "pre-roll" | "mid-roll" | "post-roll" | "overlay";
+  time: number;                  // Time in seconds when ad should play
+  adUrl: string;                 // URL to ad video
+  skipable?: boolean;            // Whether ad can be skipped
+  skipAfter?: number;            // Seconds before skip button appears
+  duration?: number;             // Ad duration in seconds
+  sponsoredUrl?: string;         // URL for sponsored content
+  title?: string;                // Ad title
+  description?: string;          // Ad description
+  relevance?: "high" | "medium" | "low";
+}
+```
+
+---
+
+## 🎯 Usage Examples
+
+### Basic Video Player
 
 ```tsx
 <VideoPlayer
-  timeCodes={[
-    { fromMs: 0, description: "Intro" },
-    { fromMs: 120000, description: "Main Scene" },
-  ]}
+  video={{
+    src: "https://example.com/video.mp4",
+    title: "My Video",
+  }}
 />
 ```
 
-🔹 Subtitles Support
-
-Add support for multiple subtitle tracks in .vtt format:
+### HLS Video with Poster
 
 ```tsx
-subtitles={[
-  {
-    lang: "en",
-    label: "English",
-    url: "https://example.com/subtitles-en.vtt",
-  },
-  {
-    lang: "fr",
-    label: "French",
-    url: "https://example.com/subtitles-fr.vtt",
-  },
-]}
+<VideoPlayer
+  video={{
+    src: "https://example.com/playlist.m3u8",
+    type: "hls",
+    poster: "https://example.com/poster.jpg",
+    title: "Streaming Video",
+  }}
+  style={{
+    width: "100%",
+    height: "450px",
+  }}
+/>
 ```
 
-🔹 Skip Intro Button
+### Video with Preview Thumbnails
+
+```tsx
+const getPreview = (hoverTime: number) => {
+  // Generate thumbnail URL based on hover time
+  return `https://example.com/thumbnails/${Math.floor(hoverTime)}.jpg`;
+};
+
+<VideoPlayer
+  video={{ src: "https://example.com/video.mp4" }}
+  features={{
+    getPreviewScreenUrl: getPreview,
+  }}
+/>;
+```
 
-Automatically show a "Skip Intro" button between a specific start and end time
+### Video with Chapters
 
 ```tsx
-<VideoPlayer intro={{ start: 5, end: 20 }} />
+<VideoPlayer
+  video={{ src: "https://example.com/video.mp4" }}
+  features={{
+    timeCodes: [
+      { fromMs: 0, description: "Introduction" },
+      { fromMs: 60000, description: "Chapter 1" },
+      { fromMs: 120000, description: "Chapter 2" },
+      { fromMs: 180000, description: "Conclusion" },
+    ],
+  }}
+/>
 ```
 
-🔹 Next Episode Playback
+### Video with Subtitles
 
-Automatically show "Next Episode" option when video ends or reaches a set time
+```tsx
+<VideoPlayer
+  video={{ src: "https://example.com/video.mp4" }}
+  features={{
+    subtitles: [
+      {
+        lang: "en",
+        label: "English",
+        url: "https://example.com/subtitles-en.vtt",
+      },
+      {
+        lang: "es",
+        label: "Spanish",
+        url: "https://example.com/subtitles-es.vtt",
+      },
+    ],
+  }}
+  style={{
+    subtitleStyle: {
+      fontSize: "1.25rem",
+      backgroundColor: "rgba(0, 0, 0, 0.75)",
+      textColor: "#ffffff",
+      position: "bottom",
+    },
+  }}
+/>
+```
+
+### Video with Intro Skip
 
 ```tsx
 <VideoPlayer
-  nextEpisodeConfig={{
-    showAtTime: 300,
-    showAtEnd: true,
+  video={{ src: "https://example.com/video.mp4" }}
+  features={{
+    intro: {
+      start: 10, // Intro starts at 10 seconds
+      end: 45, // Intro ends at 45 seconds
+    },
   }}
 />
 ```
 
-🔹 Episode Playlist Support
+### Episode Playlist
+
+```tsx
+const [currentEpisode, setCurrentEpisode] = useState(0);
+
+const episodes = [
+  { id: 1, title: "Episode 1", url: "https://example.com/ep1.m3u8" },
+  { id: 2, title: "Episode 2", url: "https://example.com/ep2.m3u8" },
+  { id: 3, title: "Episode 3", url: "https://example.com/ep3.m3u8" },
+];
+
+<VideoPlayer
+  video={{
+    src: episodes[currentEpisode].url,
+    title: episodes[currentEpisode].title,
+  }}
+  features={{
+    episodeList: episodes,
+    currentEpisodeIndex: currentEpisode,
+    nextEpisodeConfig: {
+      showAtTime: 300, // Show next episode button 5 minutes before end
+      showAtEnd: true, // Also show at video end
+    },
+  }}
+  events={{
+    onEnded: () => {
+      if (currentEpisode < episodes.length - 1) {
+        setCurrentEpisode(currentEpisode + 1);
+      }
+    },
+  }}
+/>;
+```
 
-Pass a playlist of episodes and control which one plays currently
+### Video with Tracking
 
 ```tsx
 <VideoPlayer
-  episodeList={[
-    { id: 1, title: "Episode 1", url: "https://example.com/ep1.m3u8" },
-    { id: 2, title: "Episode 2", url: "https://example.com/ep2.m3u8" },
-  ]}
-  currentEpisodeIndex={0}
+  video={{ src: "https://example.com/video.mp4" }}
+  features={{
+    tracking: {
+      onViewed: () => {
+        // Track video view
+        analytics.track("video_viewed", { videoId: "123" });
+      },
+      onWatchTimeUpdated: ({ watchTime, currentTime, duration }) => {
+        // Track watch time
+        analytics.track("watch_time_updated", {
+          watchTime,
+          progress: (currentTime / duration) * 100,
+        });
+      },
+    },
+  }}
 />
 ```
 
-🔹 Tracking Events
+### Video with Watch History
+
+```tsx
+<VideoPlayer
+  video={{ src: "https://example.com/video.mp4" }}
+  events={{
+    onWatchHistoryUpdate: async (data) => {
+      // Save watch history to backend
+      await fetch("/api/watch-history", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          videoId: "123",
+          currentTime: data.currentTime,
+          duration: data.duration,
+          progress: data.progress,
+          isCompleted: data.isCompleted,
+        }),
+      });
+    },
+  }}
+/>
+```
 
-Track when the video is viewed or how much time was watched
+### Video with Ads
 
 ```tsx
 <VideoPlayer
-  tracking={{
-    onViewed: () => console.log("User viewed the video."),
-    onWatchTimeUpdated: ({ watchTime }) =>
-      console.log("Total watch time in seconds:", watchTime),
+  video={{ src: "https://example.com/video.mp4" }}
+  features={{
+    ads: {
+      preRoll: {
+        id: "preroll-1",
+        type: "pre-roll",
+        time: 0,
+        adUrl: "https://example.com/pre-roll-ad.mp4",
+        skipable: true,
+        skipAfter: 5,
+      },
+      midRoll: [
+        {
+          id: "midroll-1",
+          type: "mid-roll",
+          time: 120,
+          adUrl: "https://example.com/mid-roll-ad.mp4",
+          skipable: false,
+        },
+      ],
+      onAdStart: (adBreak) => {
+        console.log("Ad started:", adBreak.id);
+      },
+      onAdEnd: (adBreak) => {
+        console.log("Ad ended:", adBreak.id);
+      },
+    },
   }}
 />
 ```
 
+### Resume from Last Position
+
+```tsx
+const [watchHistory, setWatchHistory] = useState(null);
+
+// Load watch history on mount
+useEffect(() => {
+  fetch("/api/watch-history/123")
+    .then((res) => res.json())
+    .then((data) => setWatchHistory(data));
+}, []);
+
+<VideoPlayer
+  video={{
+    src: "https://example.com/video.mp4",
+    startFrom: watchHistory?.currentTime || 0,
+  }}
+  events={{
+    onWatchHistoryUpdate: (data) => {
+      // Save progress
+      setWatchHistory(data);
+    },
+  }}
+/>;
+```
+
 ---
 
 ## ❓ Troubleshooting
 
-#### ❌ Video not playing?
+### Video Not Playing?
 
-- Check if the `trackSrc` URL is correct.
-- Ensure the video format (MP4, HLS) is supported.
-- If using HLS, ensure you're serving files correctly (CORS issues may block playback).
+- **Check the video URL**: Ensure `video.src` is a valid, accessible URL
+- **Check video format**: Verify the video format is supported (HLS, MP4, DASH, YouTube)
+- **CORS issues**: If using HLS or external sources, ensure CORS headers are properly configured
+- **Specify video type**: Try explicitly setting `video.type` to help with format detection
 
-#### ❌ Subtitles not showing?
+```tsx
+<VideoPlayer
+  video={{
+    src: "https://example.com/video.m3u8",
+    type: "hls", // Explicitly specify type
+  }}
+/>
+```
 
-- Check that .vtt files are correctly hosted and publicly accessible.
-- Ensure the subtitles prop includes proper lang, label, and url.
+### Subtitles Not Showing?
 
-#### ❌ Preview thumbnails not loading?
+- **Check VTT file URL**: Ensure subtitle URLs are publicly accessible
+- **Verify VTT format**: Ensure WebVTT files are properly formatted
+- **Check CORS**: Subtitle files must be accessible from your domain
+- **Test subtitle URL**: Open the subtitle URL directly in a browser to verify it loads
 
-- Confirm `getPreviewScreenUrl` is returning a valid image URL.
-- Use the browser console (F12) to check errors.
+### Preview Thumbnails Not Loading?
+
+- **Verify function returns URL**: Ensure `getPreviewScreenUrl` returns a valid image URL
+- **Check image loading**: The function should return a URL that loads successfully
+- **Use browser console**: Check for image loading errors in the browser console (F12)
+
+### Player Not Responsive?
+
+- **Use percentage widths**: Set `style.width` to `"100%"` for responsive behavior
+- **Container styling**: Wrap the player in a container with appropriate CSS
+- **Height auto**: Use `style.height: "auto"` to maintain aspect ratio
+
+```tsx
+<div style={{ maxWidth: "1200px", margin: "0 auto" }}>
+  <VideoPlayer
+    video={{ src: "https://example.com/video.mp4" }}
+    style={{
+      width: "100%",
+      height: "auto",
+    }}
+  />
+</div>
+```
 
-#### ❌ Player not responsive?
+### Ads Not Playing?
 
-- Make sure you're setting `width="100%"` for fluid responsiveness
-- Wrap the player inside a `div` with CSS styles
+- **Check ad URLs**: Ensure ad video URLs are valid and accessible
+- **Verify ad timing**: For mid-roll ads, ensure `time` is less than video duration
+- **Check ad format**: Ad videos should be in supported formats (MP4, HLS)
 
 ---
 
 ## 🔗 Related Links
 
 - 📚 [Official Documentation](https://github.com/zezosoft/react-player)
-- 🛠 [Issues & Support](https://github.com/zezosoft/react-player)
+- 🛠 [Issues & Support](https://github.com/zezosoft/react-player/issues)
 
 ---
 
 ## 📝 License
 
-Licensed under the MIT License.
+Licensed under the MIT License.  
 Developed by [Zezosoft](https://zezosoft.com). 🚀
 
 ---