@alirezahosseini/sibtorsh-player 0.2.15 → 0.3.1

package/README.md

@@ -1,73 +1,1325 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## React Compiler
-
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+# Sibtorsh Player
+
+A modern, responsive, and TypeScript-first video player for React with HLS support, native Safari playback, adaptive quality selection, encrypted HLS key handling, playback speed controls, fullscreen mode, keyboard shortcuts, and mobile-friendly interactions.
+
+[![npm version](https://img.shields.io/npm/v/@alirezahosseini/sibtorsh-player.svg)](https://www.npmjs.com/package/@alirezahosseini/sibtorsh-player)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-18%2B-61dafb.svg)](https://react.dev/)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Props](#props)
+- [HLS Playback](#hls-playback)
+- [Encrypted HLS](#encrypted-hls)
+- [Quality Selection](#quality-selection)
+- [Playback Speed](#playback-speed)
+- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [Player Interactions](#player-interactions)
+- [Fullscreen](#fullscreen)
+- [Playback Events](#playback-events)
+- [Next.js Usage](#nextjs-usage)
+- [Vite Usage](#vite-usage)
+- [Private Streams](#private-streams)
+- [CORS Configuration](#cors-configuration)
+- [Visibility Handling](#visibility-handling)
+- [Error Handling](#error-handling)
+- [Styling and Sizing](#styling-and-sizing)
+- [Browser Support](#browser-support)
+- [Troubleshooting](#troubleshooting)
+- [TypeScript](#typescript)
+- [Publishing](#publishing)
+- [Security](#security)
+- [License](#license)
+
+---
+
+## Features
+
+- HLS playback using `hls.js`
+- Native HLS playback on Safari and iOS
+- Support for MP4 and browser-supported video sources
+- Adaptive bitrate playback
+- Automatic quality selection
+- Manual quality selection
+- Native Safari quality switching
+- AES-128 encrypted HLS support
+- Custom encryption key URL using `keySrc`
+- Playback speed selection from `0.5x` to `3x`
+- Temporary `2x` playback using long press
+- Forward 15 seconds
+- Backward 15 seconds
+- Forward and backward visual indicators
+- Standard Fullscreen API support
+- Safari fullscreen fallback
+- iOS and PWA fullscreen behavior
+- Keyboard shortcuts
+- Mouse and touch interactions
+- Buffered ranges support
+- Automatic control hiding
+- Automatic pause when the page is hidden
+- Automatic pause outside the viewport
+- Automatic resume when returning to the viewport
+- HLS network error recovery
+- HLS media error recovery
+- Loading and retry states
+- Responsive controls
+- RTL-ready interface
+- CSS container queries
+- Full TypeScript declarations
+
+---
+
+## Installation
+
+Using npm:
+
+```bash
+npm install @alirezahosseini/sibtorsh-player
+```
+
+### Peer Dependencies
+
+Your project must include React and React DOM:
+
+```bash
+npm install react react-dom
+```
+
+---
+
+## Quick Start
+
+Import the player component and its stylesheet:
+
+```tsx
+import VideoPlayer from "@alirezahosseini/sibtorsh-player";
+import "@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css";
+
+export default function App() {
+    return (
+        <div
+            style={{
+                width: "100%",
+                maxWidth: 960,
+                aspectRatio: "16 / 9"
+            }}
+        >
+            <VideoPlayer
+                src="https://example.com/video/master.m3u8"
+                poster="https://example.com/video/poster.jpg"
+                title="Sample video"
+            />
+        </div>
+    );
+}
+```
+
+The player fills the width and height of its parent element.
+
+The parent should have an explicit height or aspect ratio:
+
+```tsx
+<div style={{width: "100%", aspectRatio: "16 / 9"}}>
+    <VideoPlayer src="https://example.com/master.m3u8" />
+</div>
+```
+
+---
+
+## Props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `src` | `string` | Yes | Video source URL. Supports HLS playlists and browser-supported video formats. |
+| `poster` | `string` | No | Poster image displayed before video playback starts. |
+| `keySrc` | `string` | No | Custom URL used for HLS AES-128 encryption key requests. |
+| `title` | `string` | No | Video title displayed inside the player controls. |
+| `onPlay` | `() => void` | No | Called whenever video playback starts. |
+| `onPause` | `() => void` | No | Called whenever video playback pauses. |
+
+### VideoPlayerInterface
+
+```ts
+export default interface VideoPlayerInterface {
+    src: string;
+    poster?: string;
+    keySrc?: string;
+    title?: string;
+    onPlay?: () => void;
+    onPause?: () => void;
+}
+```
+
+---
+
+## HLS Playback
+
+Sibtorsh Player automatically chooses the correct HLS playback strategy.
+
+### Browsers with Media Source Extensions
+
+Browsers such as Chrome, Firefox, and Edge use `hls.js`.
+
+```tsx
+<VideoPlayer
+    src="https://cdn.example.com/course/master.m3u8"
+    poster="https://cdn.example.com/course/poster.webp"
+    title="Course lesson"
+/>
+```
+
+### Safari and iOS
+
+Safari uses its native HLS playback implementation.
+
+The player detects native HLS support using:
+
+```ts
+video.canPlayType("application/vnd.apple.mpegurl");
+```
+
+For Safari requests, the player appends the following query parameter to the master playlist URL:
+
+```text
+is_safari=1
+```
+
+For example:
+
+```text
+https://api.example.com/video/master.m3u8?is_safari=1
+```
+
+Your backend can use this parameter to return a Safari-compatible playlist.
+
+---
+
+## Encrypted HLS
+
+The player supports AES-128 encrypted HLS streams.
+
+Pass the protected or presigned encryption key URL using `keySrc`:
+
+```tsx
+import VideoPlayer from "@alirezahosseini/sibtorsh-player";
+import "@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css";
+
+export function EncryptedVideo() {
+    return (
+        <div style={{aspectRatio: "16 / 9"}}>
+            <VideoPlayer
+                src="https://api.example.com/videos/lesson/master.m3u8"
+                keySrc="https://api.example.com/videos/lesson/key?token=SIGNED_TOKEN"
+                poster="https://cdn.example.com/posters/lesson.webp"
+                title="Protected lesson"
+            />
+        </div>
+    );
+}
+```
+
+When `hls.js` requests a URL containing `.key`, the player redirects that request to `keySrc`.
+
+The internal behavior is similar to:
+
+```ts
+const hls = new Hls({
+    xhrSetup(xhr, url) {
+        if (url.includes(".key") && keySrc) {
+            xhr.open("GET", keySrc, true);
+        }
+    }
+});
+```
+
+> `keySrc` only controls encryption-key requests made by `hls.js`.
+
+Safari uses native HLS, meaning Safari directly processes the playlist and key URLs. Your Safari playlist must therefore contain valid and authorized encryption-key URLs.
+
+---
+
+## Quality Selection
+
+When the HLS master playlist contains multiple variants, the player automatically generates a quality menu.
+
+Example master playlist:
+
+```m3u8
+#EXTM3U
+#EXT-X-VERSION:3
+
+#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1920x1080,NAME="1080p"
+1080p/index.m3u8
+
+#EXT-X-STREAM-INF:BANDWIDTH=1500000,RESOLUTION=1280x720,NAME="720p"
+720p/index.m3u8
+
+#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=854x480,NAME="480p"
+480p/index.m3u8
+
+#EXT-X-STREAM-INF:BANDWIDTH=500000,RESOLUTION=640x360,NAME="360p"
+360p/index.m3u8
+```
+
+The generated quality options include:
+
+```text
+Automatic
+1080p
+720p
+480p
+360p
+```
+
+### Automatic Quality
+
+The automatic quality option uses:
+
+```ts
+hls.currentLevel = -1;
+```
+
+This allows `hls.js` to select the most appropriate quality based on bandwidth and playback conditions.
+
+### Manual Quality
+
+Manual quality selection sets the selected HLS level:
+
+```ts
+hls.currentLevel = selectedQuality.level;
+```
+
+### Safari Quality Switching
+
+Safari does not expose the same quality-level API as `hls.js`.
+
+The player:
+
+1. Downloads the master playlist.
+2. Parses `#EXT-X-STREAM-INF` entries.
+3. Creates a list of available rendition URLs.
+4. Stores the current playback time.
+5. Changes the video source.
+6. Restores the previous playback time.
+7. Continues playback if the video was already playing.
+
+---
+
+## Playback Speed
+
+The player provides the following playback speeds:
+
+```text
+0.5x
+1x
+1.25x
+1.5x
+1.75x
+2x
+2.5x
+3x
+```
+
+Example internal behavior:
+
+```ts
+video.playbackRate = selectedRate;
+```
+
+### Long Press Playback
+
+Holding the player for one second temporarily changes the playback speed to `2x`.
+
+```text
+Press and hold → 2x
+Release → 1x
+```
+
+This feature works with mouse and touch events.
+
+---
+
+## Keyboard Shortcuts
+
+Keyboard shortcuts are ignored when the user is typing inside:
+
+- Input elements
+- Textarea elements
+- Content-editable elements
+
+| Key | Action |
+| --- | --- |
+| `Space` | Toggle play and pause |
+| `ArrowRight` | Forward 15 seconds |
+| `ArrowLeft` | Backward 15 seconds |
+| `M` | Toggle mute |
+
+Example:
+
+```ts
+if (event.code.toUpperCase() === "SPACE") {
+    event.preventDefault();
+    togglePlayHandle();
+}
+
+if (event.code.toUpperCase() === "ARROWRIGHT") {
+    event.preventDefault();
+    forwardCurrentTimeHandler();
+}
+
+if (event.code.toUpperCase() === "ARROWLEFT") {
+    event.preventDefault();
+    backwardCurrentTimeHandler();
+}
+
+if (event.code.toUpperCase() === "KEYM") {
+    event.preventDefault();
+    toggleMuteHandle();
+}
+```
+
+---
+
+## Player Interactions
+
+| Interaction | Action |
+| --- | --- |
+| Click or tap | Show or hide player controls |
+| Right-side double interaction | Forward 15 seconds |
+| Left-side double interaction | Backward 15 seconds |
+| Long press | Temporary `2x` playback |
+| Mouse move | Show controls |
+| Touch move | Show controls |
+
+### Forward and Backward Indicators
+
+After seeking forward or backward, the related indicator remains visible for five seconds.
+
+If the action runs repeatedly, the timer restarts from the latest execution.
+
+```ts
+if (forwardTimeoutRef.current) {
+    clearTimeout(forwardTimeoutRef.current);
+}
+
+forwardTimeoutRef.current = setTimeout(() => {
+    setIsForwardCurrentTime(false);
+    forwardTimeoutRef.current = null;
+}, 5000);
+```
+
+Starting forward seeking immediately hides the backward indicator.
+
+Starting backward seeking immediately hides the forward indicator.
+
+---
+
+## Fullscreen
+
+The player supports the standard Fullscreen API:
+
+```ts
+element.requestFullscreen();
+document.exitFullscreen();
+```
+
+It also checks browser-prefixed implementations:
+
+```ts
+element.webkitRequestFullscreen;
+element.mozRequestFullScreen;
+element.msRequestFullscreen;
+```
+
+Fullscreen change events supported by the player include:
+
+```text
+fullscreenchange
+webkitfullscreenchange
+mozfullscreenchange
+MSFullscreenChange
+```
+
+### Safari and PWA Fallback
+
+For iOS, Safari, and Safari-based PWA environments, the player provides a CSS-based fullscreen fallback.
+
+In fullscreen mode, the video uses:
+
+```text
+object-contain
+```
+
+This ensures that the complete video frame remains visible.
+
+---
+
+## Playback Events
+
+You can use `onPlay` and `onPause` for:
+
+- Analytics
+- Lesson progress tracking
+- User activity tracking
+- Saving playback state
+- Updating application UI
+
+Example:
+
+```tsx
+import VideoPlayer from "@alirezahosseini/sibtorsh-player";
+import "@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css";
+
+export function AnalyticsExample() {
+    return (
+        <div style={{aspectRatio: "16 / 9"}}>
+            <VideoPlayer
+                src="https://example.com/master.m3u8"
+                onPlay={() => {
+                    console.log("Playback started");
+                }}
+                onPause={() => {
+                    console.log("Playback paused");
+                }}
+            />
+        </div>
+    );
+}
+```
+
+---
+
+## Next.js Usage
+
+Sibtorsh Player uses browser APIs and should run as a client component.
+
+### App Router
+
+```tsx
+"use client";
+
+import VideoPlayer from "@alirezahosseini/sibtorsh-player";
+import "@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css";
+
+export default function LessonPlayer() {
+    return (
+        <div className="aspect-video w-full">
+            <VideoPlayer
+                src="https://example.com/master.m3u8"
+                poster="https://example.com/poster.webp"
+                title="Lesson 1"
+            />
+        </div>
+    );
+}
+```
+
+### Dynamic Import
+
+When server-side rendering causes browser API errors, import the player dynamically:
+
+```tsx
+"use client";
+
+import dynamic from "next/dynamic";
+import "@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css";
+
+const VideoPlayer = dynamic(
+    () => import("@alirezahosseini/sibtorsh-player"),
+    {
+        ssr: false
+    }
+);
+
+export default function LessonPlayer() {
+    return (
+        <div className="aspect-video w-full">
+            <VideoPlayer
+                src="https://example.com/master.m3u8"
+                poster="https://example.com/poster.webp"
+                title="Lesson 1"
+            />
+        </div>
+    );
+}
+```
+
+### Global CSS Import
+
+In some Next.js configurations, package CSS should be imported inside the root layout:
+
+```tsx
+import "@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css";
+
+export default function RootLayout({
+    children
+}: {
+    children: React.ReactNode;
+}) {
+    return (
+        <html lang="en">
+            <body>{children}</body>
+        </html>
+    );
+}
+```
+
+---
+
+## Vite Usage
+
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import VideoPlayer from "@alirezahosseini/sibtorsh-player";
+
+import "@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css";
+
+function App() {
+    return (
+        <main
+            style={{
+                width: "100%",
+                maxWidth: 960,
+                margin: "0 auto"
+            }}
+        >
+            <div style={{aspectRatio: "16 / 9"}}>
+                <VideoPlayer
+                    src="https://example.com/master.m3u8"
+                    poster="https://example.com/poster.webp"
+                    title="Example video"
+                />
+            </div>
+        </main>
+    );
+}
+
+ReactDOM.createRoot(
+    document.getElementById("root")!
+).render(
+    <React.StrictMode>
+        <App />
+    </React.StrictMode>
+);
+```
+
+---
+
+## Private Streams
+
+The player can consume:
+
+- Authenticated playlist URLs
+- Signed URLs
+- Presigned object-storage URLs
+- Protected encryption key URLs
+- Private CDN URLs
+- API-proxied HLS playlists
+
+Example:
+
+```tsx
+<VideoPlayer
+    src={video.playlistUrl}
+    keySrc={video.keyUrl}
+    poster={video.posterUrl}
+    title={video.title}
+/>
+```
+
+Recommended protected delivery flow:
+
+```text
+Frontend
+    ↓
+Request authorized video information
+    ↓
+Backend validates the authenticated user
+    ↓
+Backend returns a protected playlist URL
+    ↓
+Backend returns a protected key URL
+    ↓
+Player starts HLS playback
+```
+
+Recommended security approaches:
+
+- Keep master playlists private.
+- Keep rendition playlists private.
+- Keep AES-128 keys private.
+- Generate short-lived signed URLs.
+- Bind URLs to authenticated users when possible.
+- Validate active subscriptions.
+- Use CDN token authentication.
+- Configure CORS correctly.
+- Avoid exposing permanent object-storage URLs.
+
+---
+
+## CORS Configuration
+
+HLS playlists, segments, and encryption keys must allow requests from the application origin.
+
+Example headers:
+
+```http
+Access-Control-Allow-Origin: https://your-app.example.com
+Access-Control-Allow-Methods: GET, HEAD, OPTIONS
+Access-Control-Allow-Headers: Range, Authorization, Content-Type
+Access-Control-Expose-Headers: Content-Length, Content-Range, Accept-Ranges
+```
+
+When authentication cookies are required:
+
+```http
+Access-Control-Allow-Credentials: true
+```
+
+Do not combine credentials with:
+
+```http
+Access-Control-Allow-Origin: *
+```
+
+Instead, return the exact allowed origin:
+
+```http
+Access-Control-Allow-Origin: https://your-app.example.com
+```
+
+### Nginx Example
+
+```nginx
+location /videos/ {
+    add_header Access-Control-Allow-Origin "https://your-app.example.com" always;
+    add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;
+    add_header Access-Control-Allow-Headers "Authorization, Range, Content-Type" always;
+    add_header Access-Control-Expose-Headers "Content-Length, Content-Range, Accept-Ranges" always;
+
+    if ($request_method = OPTIONS) {
+        return 204;
+    }
+}
+```
+
+---
+
+## Visibility Handling
+
+The player automatically pauses video when the browser tab becomes hidden:
+
+```ts
+document.addEventListener(
+    "visibilitychange",
+    visibilityChangeHandler
+);
+```
+
+The player also uses `IntersectionObserver`.
+
+If less than 50% of the player is visible:
+
+```text
+Video pauses automatically
+```
+
+If the video was playing before leaving the viewport:
+
+```text
+Video resumes when it becomes visible again
+```
+
+The observer threshold is:
+
+```ts
+{
+    threshold: [0, 0.5, 1]
+}
+```
+
+---
+
+## Error Handling
+
+The player handles native media errors and `hls.js` errors.
+
+### Non-Fatal HLS Errors
+
+Non-fatal HLS warnings are logged and playback continues:
+
+```ts
+if (!data.fatal) {
+    console.warn("Hls non-fatal warning:", data);
+    return;
+}
+```
+
+An example of a recoverable warning is:
+
+```text
+bufferSeekOverHole
+```
+
+### Network Errors
+
+Network errors attempt to restart loading:
+
+```ts
+hls.startLoad();
+```
+
+### Media Errors
+
+Media errors attempt media recovery:
+
+```ts
+hls.recoverMediaError();
+```
+
+### Fatal Errors
+
+Fatal and unrecoverable errors show the player error state.
+
+```ts
+errorHandler();
+hls.destroy();
+```
+
+### Native Media Errors
+
+The player handles browser media error codes:
+
+| Error code | Description |
+| --- | --- |
+| `MEDIA_ERR_ABORTED` | Video loading was aborted |
+| `MEDIA_ERR_NETWORK` | A network error occurred |
+| `MEDIA_ERR_DECODE` | The browser could not decode the video |
+| `MEDIA_ERR_SRC_NOT_SUPPORTED` | Video source or format is unsupported |
+
+---
+
+## Styling and Sizing
+
+Always import the player stylesheet:
+
+```tsx
+import "@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css";
+```
+
+The player uses:
+
+```text
+width: 100%
+height: 100%
+```
+
+The parent element must provide the required dimensions.
+
+### Aspect Ratio Container
+
+```tsx
+<div
+    style={{
+        width: "100%",
+        maxWidth: 1200,
+        aspectRatio: "16 / 9"
+    }}
+>
+    <VideoPlayer src="https://example.com/master.m3u8" />
+</div>
+```
+
+### Fixed Height Container
+
+```tsx
+<div
+    style={{
+        width: "100%",
+        height: 500
+    }}
+>
+    <VideoPlayer src="https://example.com/master.m3u8" />
+</div>
+```
+
+### Tailwind CSS Container
+
+```tsx
+<div className="aspect-video w-full overflow-hidden rounded-xl">
+    <VideoPlayer src="https://example.com/master.m3u8" />
+</div>
+```
+
+The player includes its own prefixed classes and responsive container-query behavior.
+
+---
+
+## Browser Support
+
+| Browser | Playback method | Support |
+| --- | --- | --- |
+| Chrome | `hls.js` and native video | Supported |
+| Microsoft Edge | `hls.js` and native video | Supported |
+| Firefox | `hls.js` and native video | Supported |
+| Safari macOS | Native HLS | Supported |
+| Safari iOS | Native HLS | Supported |
+| Chrome Android | `hls.js` or native video | Supported |
+| Installed PWA | Browser-dependent | Supported with fallback behavior |
+
+Actual codec support depends on:
+
+- Browser
+- Operating system
+- Hardware decoder
+- Video codec
+- Audio codec
+- HLS segment format
+
+### Recommended Codecs
+
+For broad compatibility:
+
+```text
+Video codec: H.264 / AVC
+Audio codec: AAC
+Playlist: HLS
+Segments: MPEG-TS or compatible fragmented MP4
+```
+
+---
+
+## Troubleshooting
+
+### Player Has Zero Height
+
+The player fills its parent element.
+
+Incorrect:
+
+```tsx
+<div>
+    <VideoPlayer src="https://example.com/master.m3u8" />
+</div>
+```
+
+Correct:
+
+```tsx
+<div style={{aspectRatio: "16 / 9"}}>
+    <VideoPlayer src="https://example.com/master.m3u8" />
+</div>
+```
+
+---
+
+### Player Styles Are Missing
+
+Import the distributed CSS once:
+
+```tsx
+import "@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css";
+```
+
+---
+
+### HLS Works in Safari but Not Chrome
+
+Verify that:
+
+- The master playlist allows CORS.
+- Rendition playlists allow CORS.
+- Segment URLs are valid.
+- Key URLs are valid.
+- Signed URLs have not expired.
+- The stream uses supported codecs.
+- The response content type is correct.
+
+Recommended playlist content type:
+
+```http
+Content-Type: application/vnd.apple.mpegurl
+```
+
+---
+
+### HLS Works in Chrome but Not Safari
+
+Safari uses native HLS.
+
+Verify that:
+
+- The Safari playlist contains valid URLs.
+- Key URLs are directly accessible by Safari.
+- Cookies are configured correctly.
+- The backend accepts `is_safari=1`.
+- Rendition playlist URLs are absolute or correctly resolvable.
+- Segment URLs have not expired.
+
+---
+
+### Quality Options Are Missing
+
+Quality options are generated from the master playlist.
+
+Make sure the source contains:
+
+```m3u8
+#EXT-X-STREAM-INF
+```
+
+A single rendition playlist does not provide multiple quality options.
+
+---
+
+### Safari Quality Switching Does Not Work
+
+Make sure the master playlist can be fetched from JavaScript:
+
+```ts
+fetch(masterPlaylistUrl, {
+    method: "GET",
+    credentials: "include",
+    headers: {
+        Accept: "application/vnd.apple.mpegurl"
+    }
+});
+```
+
+The playlist response must allow CORS.
+
+---
+
+### `bufferSeekOverHole` Warning
+
+This is usually a recoverable `hls.js` warning.
+
+Example:
+
+```text
+fragment loaded with buffer holes, seeking from 0 to 0.1
+```
+
+If:
+
+```text
+fatal: false
+```
+
+the player should continue playback.
+
+Repeated gaps in the middle of a video may indicate timestamp discontinuities between HLS segments.
+
+---
+
+### Stream Returns 403
+
+Check:
+
+- Playlist signed URL expiration
+- Rendition signed URL expiration
+- Segment signed URL expiration
+- Key signed URL expiration
+- Authentication cookies
+- Authorization headers
+- User subscription
+- CORS configuration
+- CDN rules
+- Referrer restrictions
+
+---
+
+### Video Does Not Resume After Quality Change
+
+Safari quality switching waits for `loadedmetadata`, restores the previous playback time, and then resumes playback.
+
+Make sure the selected rendition:
+
+- Is accessible
+- Has a valid duration
+- Uses compatible timestamps
+- Uses the same content timeline
+
+---
+
+### Fullscreen Does Not Work
+
+Fullscreen APIs require direct user interaction.
+
+Call fullscreen from:
+
+- A click event
+- A touch event
+- A keyboard event initiated by the user
+
+Browsers may block fullscreen requests triggered automatically.
+
+---
+
+## TypeScript
+
+Type declarations are included in the package.
+
+No separate type package is required:
+
+```bash
+npm install @alirezahosseini/sibtorsh-player
+```
+
+Import:
+
+```tsx
+import VideoPlayer from "@alirezahosseini/sibtorsh-player";
+```
+
+Example typed component:
+
+```tsx
+import VideoPlayer from "@alirezahosseini/sibtorsh-player";
+
+interface LessonPlayerProps {
+    playlistUrl: string;
+    keyUrl?: string;
+    posterUrl?: string;
+    title?: string;
+}
+
+export default function LessonPlayer({
+    playlistUrl,
+    keyUrl,
+    posterUrl,
+    title
+}: LessonPlayerProps) {
+    return (
+        <div style={{aspectRatio: "16 / 9"}}>
+            <VideoPlayer
+                src={playlistUrl}
+                keySrc={keyUrl}
+                poster={posterUrl}
+                title={title}
+            />
+        </div>
+    );
+}
+```
+
+---
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
 ```
+
+Start development mode:
+
+```bash
+npm run dev
+```
+
+Build the package:
+
+```bash
+npm run build
+```
+
+The build process generates:
+
+```text
+dist/sibtorsh-player.es.js
+dist/sibtorsh-player.umd.js
+dist/sibtorsh-player.css
+dist/*.d.ts
+```
+
+---
+
+## Publishing
+
+npm does not allow publishing over an existing version.
+
+Before publishing, increment the package version.
+
+### Patch Release
+
+Use for fixes and small changes:
+
+```bash
+npm version patch
+npm run build
+npm publish
+```
+
+Example:
+
+```text
+0.3.1 → 0.3.2
+```
+
+### Minor Release
+
+Use for new backward-compatible features:
+
+```bash
+npm version minor
+npm run build
+npm publish
+```
+
+Example:
+
+```text
+0.3.1 → 0.4.0
+```
+
+### Major Release
+
+Use for breaking changes:
+
+```bash
+npm version major
+npm run build
+npm publish
+```
+
+Example:
+
+```text
+0.3.1 → 1.0.0
+```
+
+### Public Package
+
+```bash
+npm publish --access public
+```
+
+### Restricted Package
+
+```bash
+npm publish --access restricted
+```
+
+Restricted packages require an npm plan that supports private packages.
+
+### Verify Current npm User
+
+```bash
+npm whoami
+```
+
+### Verify Registry
+
+```bash
+npm config get registry
+```
+
+Expected registry:
+
+```text
+https://registry.npmjs.org/
+```
+
+### Preview Package Contents
+
+Before publishing:
+
+```bash
+npm pack --dry-run
+```
+
+---
+
+## Security
+
+Client-side JavaScript cannot completely prevent an authorized user from:
+
+- Inspecting network requests
+- Inspecting playlist URLs
+- Inspecting downloaded package files
+- Reading bundled JavaScript
+- Copying previously downloaded media
+- Recording the screen
+
+For stronger content protection, combine the player with:
+
+- Private HLS playlists
+- Private rendition playlists
+- AES-128 encryption
+- Private encryption keys
+- Short-lived signed URLs
+- Session-bound authorization
+- User-bound authorization
+- Domain validation
+- CDN token authentication
+- Watermarking
+- Concurrent-session limits
+- DRM for high-value content
+
+Supported DRM systems may include:
+
+```text
+Google Widevine
+Apple FairPlay
+Microsoft PlayReady
+```
+
+Sibtorsh Player currently focuses on HLS and AES-128 delivery and does not claim to provide full DRM protection.
+
+---
+
+## Package Information
+
+```text
+Package: @alirezahosseini/sibtorsh-player
+Framework: React
+Language: TypeScript
+HLS engine: hls.js
+Module formats: ES Module and UMD
+Stylesheet: Included
+Type declarations: Included
+```
+
+---
+
+## License
+
+This package is distributed under the license defined by the project owner.
+
+Before public or commercial distribution, update the `license` field in `package.json`.
+
+Example proprietary configuration:
+
+```json
+{
+    "license": "UNLICENSED"
+}
+```
+
+Example MIT configuration:
+
+```json
+{
+    "license": "MIT"
+}
+```
+
+---
+
+## Author
+
+**Alireza Hosseini**
+
+npm package:
+
+```text
+@alirezahosseini/sibtorsh-player
+```