cafe-video-player 3.0.8 → 3.0.10

package/README.md

@@ -1,286 +1,325 @@
-# cafe-video-player
-
-✔ Playing static and vod videos
-
-## Installation
-
-```
-$ npm install --save cafe-video-player
-$ yarn add cafe-video-player
-
-```
-
-## Example
-
-✔ To play vod, follow the example below:
-
-```jsx
-import { VideoPlayerLibrary } from "cafe-video-player";
-
-export default function HomePage() {
-  const params = {
-    type: "vod",
-    id: "6623",
-    banner: "image path", // (to display cover image from external url) optional
-    subtitleUrl: "subtitle url", // (to display subtitle from external url) optional
-    currentTime: 100, // (jump to second 100) optional
-    onChangeCurrentTime: (currentTime: number) => console.log(currentTime), //optional, This function returns the current time value when clicking on the progress bar or the backward and forward buttons.
-    subtitles = [{lang: "string", title: "string", url: "subtitle url"}] // optional
-    /*
-      subtitle example
-      subtitles = [
-        {lang: "fa", title: "فارسی", url: "https://hamrahi.cloud/subtitles/216-282790-6770242c63370b3aa9ce680b-sub_fa.srt"},
-        {lang: "en", title: "انگلیسی", url: "https://hamrahi.cloud/subtitles/216-282790-6770242c63370b58ecce680d-sub_en.srt"},
-      ]
-    */
-    onPlay: (currentTime: number) => console.log("Video started at:", currentTime),
-    onSpeedChange: (oldSpeed: number, newSpeed: number) => console.log(`Playback speed changed from ${oldSpeed}x to ${newSpeed}x`),
-    onFullscreenChange:(status: boolean) => console.log(`Fullscreen status:${status}`),
-    onSubtitleStatusChange: (subtitle, status) => console.log("Subtitle status changed:", subtitle, "Enabled:", status),
-  };
-
-  return (
-    <div>
-      <VideoPlayerLibrary params={params} />
-    </div>
-  );
-}
-```
-
-## Example
-
-✔ To play static videos, follow the example below:
-
-- id corresponds to the video link, which must be base64 format
-- banner corresponds to the cover link, which must be base64 format
-
-```jsx
-import { VideoPlayerLibrary } from "cafe-video-player";
-
-export default function HomePage() {
-  const params = {
-    type: "static",
-    id: "aHR0cHM6Ly9hYnJlaGFtcmFoaS5pci9vL3RXMHFONUQwWFB2R04wdGhJQUM1UUEv",
-    banner: "image path", // (to display cover image from external url) optional
-    onChangeCurrentTime: (currentTime: number) => console.log(currentTime), //optional, This function returns the current time value when clicking on the progress bar or the backward and forward buttons.
-    subtitles = [{lang: "string", title: "string", url: "subtitle url"}] // optional
-    /*
-      subtitle example
-      subtitles = [
-        {lang: "fa", title: "فارسی", url: "https://hamrahi.cloud/subtitles/216-282790-6770242c63370b3aa9ce680b-sub_fa.srt"},
-        {lang: "en", title: "انگلیسی", url: "https://hamrahi.cloud/subtitles/216-282790-6770242c63370b58ecce680d-sub_en.srt"},
-      ]
-    */
-    onPlay: (currentTime: number) => console.log("Video started at:", currentTime),
-    onSpeedChange: (oldSpeed: number, newSpeed: number) => console.log(`Playback speed changed from ${oldSpeed}x to ${newSpeed}x`),
-    onFullscreenChange:(status: boolean) => console.log(`Fullscreen status:${status}`),
-    onSubtitleStatusChange: (subtitle, status) => console.log("Subtitle status changed:", subtitle, "Enabled:", status),
-  };
-
-  return (
-    <div>
-      <VideoPlayerLibrary params={params} />
-    </div>
-  );
-}
-```
-
-## Example
-
-✔ To use the mini-player feature, follow the example below:
-
-```jsx
-import { MiniPlayerLibrary } from "cafe-video-player";
-
-export default function HomePage() {
-  const params = {
-    type: "vod",
-    id: "6623",
-    onClose: () => {},
-  };
-
-  return (
-    <div>
-      <MiniPlayerLibrary params={params} />
-    </div>
-  );
-}
-```
-
-## Example
-
-✔ You can use bannerAlt props to set custom alt for video banner
-
-```jsx
-import { VideoPlayerLibrary } from "cafe-video-player";
-
-export default function HomePage() {
-  const params = {
-    id: "6623",
-    type: "vod",
-    bannerAlt: "alt for video banner",
-  };
-
-  return (
-    <div>
-      <VideoPlayerLibrary params={params} />
-    </div>
-  );
-}
-```
-
-For the modals to work correctly, you need to add the following tag to the end of the body tag in the \_document file.
-
-```jsx
-<div id="dialog-react-root-videoPlayer" />
-```
-
-To display the player styles correctly, you must import the videoPlayerStyles.css file from the node \_module folder inside the \_app file according to the example below.
-
-```jsx
-import "../node_modules/cafe-video-player/videoPlayerStyles.css";
-```
-
-To display the images correctly, you must put the following configuration in the next.config.ts file.
-
-```jsx
-
-images: {
-  remotePatterns: [
-    {
-      protocol: "https",
-      hostname: "**"
-    }
-  ]
-},
-
-```
-
-# Video HighLighter Integration Guide
-
-This document explains how to integrate and use the **Video HighLighter** feature in a Next.js project.
-
-## Overview
-
-The Video HighLighter enhances the video player with additional UI and state indicators during the download and preparation of video content. To enable it, several props must be passed to the player component.
-
-## Props
-
-### `vhl_status`
-
-Indicates the current state of the Video HighLighter process. Accepted values:
-
-- `skeleton`: Shows the skeleton loading state.
-- `waiting`: Indicates the waiting period before video download begins.
-- `download_start`: The download process has started.
-- `download_error`: An error occurred during the download.
-- `undefined`: Default value. Hides all Video HighLighter-related sections.
-
-### `vhl_progress`
-
-A numeric value representing the percentage of the download progress.
-
-### `vhl_duration`
-
-Total duration of the video in seconds (numeric value).
-
-### `vhl_statusText`
-
-Text displayed under the progress bar while downloading the video.  
-For greater flexibility (e.g., multiline messages), this prop should be passed as a JSX element.
-
-### `vhl_onRetry`
-
-A callback function executed if a download error occurs.
-
-### `banner`
-
-An image used as the banner for the video.
-
-## Important Notes
-
-After the video has been successfully downloaded, make sure to:
-
-1. Set the `vhl_status` to `undefined`.
-2. Pass the video `id` using the `id` prop to the player to start playback and load video details.
-
----
-
-## 🧪 Example Usage in a Next.js Component
-
-```tsx
-import { VideoPlayerLibrary } from "cafe-video-player";
-
-export default function HomePage() {
-  const params = {
-      vhl_status="download_start"
-      vhl_progress={42}
-      vhl_duration={300}
-      vhl_statusText={<p>Downloading highlights...<br />Please wait.</p>}
-      vhl_onRetry={handleRetry}
-      banner="/images/video-banner.jpg"
-      id="abc123"
-  };
-
-  return (
-    <div>
-      <VideoPlayerLibrary params={params} />
-    </div>
-  );
-}
-```
-
-# Advertisement Integration Guide
-
-This document explains how to integrate and use the **Advertisement** feature in a Next.js project with the `cafe-video-player`.
-
----
-
-## Overview
-
-The Advertisement feature allows you to show video ads before playback.  
-It supports skip functionality, clickable ads, and callback hooks for both skipping and ad completion.
-
----
-
-## Props
-
-An object that must follow the `IAdvertisement` interface:
-
-```ts
-export interface IAdvertisement {
-  videoUrl: string; // The ad video source URL (static video, required)
-  adText?: string; // Optional text for the ad button. Defaults to "اطلاعات بیشتر" if not provided
-  skipDelay?: number; // Number of seconds before the skip button becomes clickable. If not provided or 0, the ad cannot be skipped
-  onSkipAd?: (currentTime: number) => void; // Callback when the ad is skipped, receives the currentTime (optional)
-  onEndAd?: (currentTime: number) => void; // Callback when the ad finishes, receives the currentTime (optional)
-  onClickAd?: (currentTime: number) => void; // Callback when the ad button is clicked, receives the currentTime. If not defined, the ad button will not be shown (optional)
-}
-```
-
-## 🧪 Example Usage in a Next.js Component
-
-```tsx
-import { VideoPlayerLibrary } from "cafe-video-player";
-
-export default function HomePage() {
-  const params = {
-    type: "vod",
-    id: "6623",
-    advertisement: {
-      videoUrl: "https://example.com/ad.mp4",
-      adText: "Visit our sponsor",
-      skipDelay: 5,
-      onSkipAd: (currentTime: number) => console.log("Ad skipped at:", currentTime),
-      onEndAd: (currentTime: number) => console.log("Ad ended at:", currentTime),
-      onClickAd: (currentTime: number) => console.log("Ad clicked at:", currentTime),
-    },
-  };
-
-  return (
-    <div>
-      <VideoPlayerLibrary params={params} />
-    </div>
-  );
-}
-```
+# cafe-video-player
+
+✔ Playing static and vod videos
+
+## Installation
+
+```
+$ npm install --save cafe-video-player
+$ yarn add cafe-video-player
+
+```
+
+## Example
+
+✔ To play vod, follow the example below:
+
+```jsx
+import { VideoPlayerLibrary } from "cafe-video-player";
+
+export default function HomePage() {
+  const params = {
+    type: "vod",
+    id: "6623",
+    banner: "image path", // (to display cover image from external url) optional
+    subtitleUrl: "subtitle url", // (to display subtitle from external url) optional
+    currentTime: 100, // (jump to second 100) optional
+    onChangeCurrentTime: (currentTime: number) => console.log(currentTime), //optional, This function returns the current time value when clicking on the progress bar or the backward and forward buttons.
+    subtitles = [{lang: "string", title: "string", url: "subtitle url"}] // optional
+    /*
+      subtitle example
+      subtitles = [
+        {lang: "fa", title: "فارسی", url: "https://hamrahi.cloud/subtitles/216-282790-6770242c63370b3aa9ce680b-sub_fa.srt"},
+        {lang: "en", title: "انگلیسی", url: "https://hamrahi.cloud/subtitles/216-282790-6770242c63370b58ecce680d-sub_en.srt"},
+      ]
+    */
+    onPlay: (currentTime: number) => console.log("Video started at:", currentTime),
+    onSpeedChange: (oldSpeed: number, newSpeed: number) => console.log(`Playback speed changed from ${oldSpeed}x to ${newSpeed}x`),
+    onFullscreenChange:(status: boolean) => console.log(`Fullscreen status:${status}`),
+    onSubtitleStatusChange: (subtitle, status) => console.log("Subtitle status changed:", subtitle, "Enabled:", status),
+  };
+
+  return (
+    <div>
+      <VideoPlayerLibrary params={params} />
+    </div>
+  );
+}
+```
+
+## Example
+
+✔ To play a video directly using stream_link, follow the example below:
+
+- If stream_link is provided, there is no need to pass id.
+- In this mode, the player will not send any request to fetch VOD data and will directly use the provided HLS link for playback.
+- If both id and stream_link are provided, id has priority.
+
+```jsx
+import { VideoPlayerLibrary } from "cafe-video-player";
+
+export default function HomePage() {
+  const params = {
+    type: "static",
+    stream_link: "https://example.com/video/playlist.m3u8", // direct HLS link
+    banner: "image path", // (to display cover image from external url) optional
+    onChangeCurrentTime: (currentTime: number) => console.log(currentTime), //optional, This function returns the current time value when clicking on the progress bar or the backward and forward buttons.
+    subtitles = [{lang: "string", title: "string", url: "subtitle url"}] // optional
+    /*
+      subtitle example
+      subtitles = [
+        {lang: "fa", title: "فارسی", url: "https://hamrahi.cloud/subtitles/216-282790-6770242c63370b3aa9ce680b-sub_fa.srt"},
+        {lang: "en", title: "انگلیسی", url: "https://hamrahi.cloud/subtitles/216-282790-6770242c63370b58ecce680d-sub_en.srt"},
+      ]
+    */
+    onPlay: (currentTime: number) => console.log("Video started at:", currentTime),
+    onSpeedChange: (oldSpeed: number, newSpeed: number) => console.log(`Playback speed changed from ${oldSpeed}x to ${newSpeed}x`),
+    onFullscreenChange:(status: boolean) => console.log(`Fullscreen status:${status}`),
+    onSubtitleStatusChange: (subtitle, status) => console.log("Subtitle status changed:", subtitle, "Enabled:", status),
+  };
+
+  return (
+    <div>
+      <VideoPlayerLibrary params={params} />
+    </div>
+  );
+}
+```
+
+## Example
+
+✔ To play static videos, follow the example below:
+
+- id corresponds to the video link, which must be base64 format
+- banner corresponds to the cover link, which must be base64 format
+
+```jsx
+import { VideoPlayerLibrary } from "cafe-video-player";
+
+export default function HomePage() {
+  const params = {
+    type: "static",
+    id: "aHR0cHM6Ly9hYnJlaGFtcmFoaS5pci9vL3RXMHFONUQwWFB2R04wdGhJQUM1UUEv",
+    banner: "image path", // (to display cover image from external url) optional
+    onChangeCurrentTime: (currentTime: number) => console.log(currentTime), //optional, This function returns the current time value when clicking on the progress bar or the backward and forward buttons.
+    subtitles = [{lang: "string", title: "string", url: "subtitle url"}] // optional
+    /*
+      subtitle example
+      subtitles = [
+        {lang: "fa", title: "فارسی", url: "https://hamrahi.cloud/subtitles/216-282790-6770242c63370b3aa9ce680b-sub_fa.srt"},
+        {lang: "en", title: "انگلیسی", url: "https://hamrahi.cloud/subtitles/216-282790-6770242c63370b58ecce680d-sub_en.srt"},
+      ]
+    */
+    onPlay: (currentTime: number) => console.log("Video started at:", currentTime),
+    onSpeedChange: (oldSpeed: number, newSpeed: number) => console.log(`Playback speed changed from ${oldSpeed}x to ${newSpeed}x`),
+    onFullscreenChange:(status: boolean) => console.log(`Fullscreen status:${status}`),
+    onSubtitleStatusChange: (subtitle, status) => console.log("Subtitle status changed:", subtitle, "Enabled:", status),
+  };
+
+  return (
+    <div>
+      <VideoPlayerLibrary params={params} />
+    </div>
+  );
+}
+```
+
+## Example
+
+✔ To use the mini-player feature, follow the example below:
+
+```jsx
+import { MiniPlayerLibrary } from "cafe-video-player";
+
+export default function HomePage() {
+  const params = {
+    type: "vod",
+    id: "6623",
+    onClose: () => {},
+  };
+
+  return (
+    <div>
+      <MiniPlayerLibrary params={params} />
+    </div>
+  );
+}
+```
+
+## Example
+
+✔ You can use bannerAlt props to set custom alt for video banner
+
+```jsx
+import { VideoPlayerLibrary } from "cafe-video-player";
+
+export default function HomePage() {
+  const params = {
+    id: "6623",
+    type: "vod",
+    bannerAlt: "alt for video banner",
+  };
+
+  return (
+    <div>
+      <VideoPlayerLibrary params={params} />
+    </div>
+  );
+}
+```
+
+For the modals to work correctly, you need to add the following tag to the end of the body tag in the \_document file.
+
+```jsx
+<div id="dialog-react-root-videoPlayer" />
+```
+
+To display the player styles correctly, you must import the videoPlayerStyles.css file from the node \_module folder inside the \_app file according to the example below.
+
+```jsx
+import "../node_modules/cafe-video-player/videoPlayerStyles.css";
+```
+
+To display the images correctly, you must put the following configuration in the next.config.ts file.
+
+```jsx
+
+images: {
+  remotePatterns: [
+    {
+      protocol: "https",
+      hostname: "**"
+    }
+  ]
+},
+
+```
+
+# Video HighLighter Integration Guide
+
+This document explains how to integrate and use the **Video HighLighter** feature in a Next.js project.
+
+## Overview
+
+The Video HighLighter enhances the video player with additional UI and state indicators during the download and preparation of video content. To enable it, several props must be passed to the player component.
+
+## Props
+
+### `vhl_status`
+
+Indicates the current state of the Video HighLighter process. Accepted values:
+
+- `skeleton`: Shows the skeleton loading state.
+- `waiting`: Indicates the waiting period before video download begins.
+- `download_start`: The download process has started.
+- `download_error`: An error occurred during the download.
+- `undefined`: Default value. Hides all Video HighLighter-related sections.
+
+### `vhl_progress`
+
+A numeric value representing the percentage of the download progress.
+
+### `vhl_duration`
+
+Total duration of the video in seconds (numeric value).
+
+### `vhl_statusText`
+
+Text displayed under the progress bar while downloading the video.  
+For greater flexibility (e.g., multiline messages), this prop should be passed as a JSX element.
+
+### `vhl_onRetry`
+
+A callback function executed if a download error occurs.
+
+### `banner`
+
+An image used as the banner for the video.
+
+## Important Notes
+
+After the video has been successfully downloaded, make sure to:
+
+1. Set the `vhl_status` to `undefined`.
+2. Pass the video `id` using the `id` prop to the player to start playback and load video details.
+
+---
+
+## 🧪 Example Usage in a Next.js Component
+
+```tsx
+import { VideoPlayerLibrary } from "cafe-video-player";
+
+export default function HomePage() {
+  const params = {
+      vhl_status="download_start"
+      vhl_progress={42}
+      vhl_duration={300}
+      vhl_statusText={<p>Downloading highlights...<br />Please wait.</p>}
+      vhl_onRetry={handleRetry}
+      banner="/images/video-banner.jpg"
+      id="abc123"
+  };
+
+  return (
+    <div>
+      <VideoPlayerLibrary params={params} />
+    </div>
+  );
+}
+```
+
+# Advertisement Integration Guide
+
+This document explains how to integrate and use the **Advertisement** feature in a Next.js project with the `cafe-video-player`.
+
+---
+
+## Overview
+
+The Advertisement feature allows you to show video ads before playback.  
+It supports skip functionality, clickable ads, and callback hooks for both skipping and ad completion.
+
+---
+
+## Props
+
+An object that must follow the `IAdvertisement` interface:
+
+```ts
+export interface IAdvertisement {
+  videoUrl: string; // The ad video source URL (static video, required)
+  adText?: string; // Optional text for the ad button. Defaults to "اطلاعات بیشتر" if not provided
+  skipDelay?: number; // Number of seconds before the skip button becomes clickable. If not provided or 0, the ad cannot be skipped
+  onSkipAd?: (currentTime: number) => void; // Callback when the ad is skipped, receives the currentTime (optional)
+  onEndAd?: (currentTime: number) => void; // Callback when the ad finishes, receives the currentTime (optional)
+  onClickAd?: (currentTime: number) => void; // Callback when the ad button is clicked, receives the currentTime. If not defined, the ad button will not be shown (optional)
+}
+```
+
+## 🧪 Example Usage in a Next.js Component
+
+```tsx
+import { VideoPlayerLibrary } from "cafe-video-player";
+
+export default function HomePage() {
+  const params = {
+    type: "vod",
+    id: "6623",
+    advertisement: {
+      videoUrl: "https://example.com/ad.mp4",
+      adText: "Visit our sponsor",
+      skipDelay: 5,
+      onSkipAd: (currentTime: number) => console.log("Ad skipped at:", currentTime),
+      onEndAd: (currentTime: number) => console.log("Ad ended at:", currentTime),
+      onClickAd: (currentTime: number) => console.log("Ad clicked at:", currentTime),
+    },
+  };
+
+  return (
+    <div>
+      <VideoPlayerLibrary params={params} />
+    </div>
+  );
+}
+```