\n```\n\n---\n\n## HLS Playback\n\nSibtorsh Player automatically chooses the correct HLS playback strategy.\n\n### Browsers with Media Source Extensions\n\nBrowsers such as Chrome, Firefox, and Edge use `hls.js`.\n\n```tsx\n\n```\n\n### Safari and iOS\n\nSafari uses its native HLS playback implementation.\n\nThe player detects native HLS support using:\n\n```ts\nvideo.canPlayType(\"application/vnd.apple.mpegurl\");\n```\n\nFor Safari requests, the player appends the following query parameter to the master playlist URL:\n\n```text\nis_safari=1\n```\n\nFor example:\n\n```text\nhttps://api.example.com/video/master.m3u8?is_safari=1\n```\n\nYour backend can use this parameter to return a Safari-compatible playlist.\n\n---\n\n## Encrypted HLS\n\nThe player supports AES-128 encrypted HLS streams.\n\nPass the protected or presigned encryption key URL using `keySrc`:\n\n```tsx\nimport VideoPlayer from \"@alirezahosseini/sibtorsh-player\";\nimport \"@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css\";\n\nexport function EncryptedVideo() {\n return (\n \n \n
\n );\n}\n```\n\nWhen `hls.js` requests a URL containing `.key`, the player redirects that request to `keySrc`.\n\nThe internal behavior is similar to:\n\n```ts\nconst hls = new Hls({\n xhrSetup(xhr, url) {\n if (url.includes(\".key\") && keySrc) {\n xhr.open(\"GET\", keySrc, true);\n }\n }\n});\n```\n\n> `keySrc` only controls encryption-key requests made by `hls.js`.\n\nSafari uses native HLS, meaning Safari directly processes the playlist and key URLs. Your Safari playlist must therefore contain valid and authorized encryption-key URLs.\n\n---\n\n## Quality Selection\n\nWhen the HLS master playlist contains multiple variants, the player automatically generates a quality menu.\n\nExample master playlist:\n\n```m3u8\n#EXTM3U\n#EXT-X-VERSION:3\n\n#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1920x1080,NAME=\"1080p\"\n1080p/index.m3u8\n\n#EXT-X-STREAM-INF:BANDWIDTH=1500000,RESOLUTION=1280x720,NAME=\"720p\"\n720p/index.m3u8\n\n#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=854x480,NAME=\"480p\"\n480p/index.m3u8\n\n#EXT-X-STREAM-INF:BANDWIDTH=500000,RESOLUTION=640x360,NAME=\"360p\"\n360p/index.m3u8\n```\n\nThe generated quality options include:\n\n```text\nAutomatic\n1080p\n720p\n480p\n360p\n```\n\n### Automatic Quality\n\nThe automatic quality option uses:\n\n```ts\nhls.currentLevel = -1;\n```\n\nThis allows `hls.js` to select the most appropriate quality based on bandwidth and playback conditions.\n\n### Manual Quality\n\nManual quality selection sets the selected HLS level:\n\n```ts\nhls.currentLevel = selectedQuality.level;\n```\n\n### Safari Quality Switching\n\nSafari does not expose the same quality-level API as `hls.js`.\n\nThe player:\n\n1. Downloads the master playlist.\n2. Parses `#EXT-X-STREAM-INF` entries.\n3. Creates a list of available rendition URLs.\n4. Stores the current playback time.\n5. Changes the video source.\n6. Restores the previous playback time.\n7. Continues playback if the video was already playing.\n\n---\n\n## Playback Speed\n\nThe player provides the following playback speeds:\n\n```text\n0.5x\n1x\n1.25x\n1.5x\n1.75x\n2x\n2.5x\n3x\n```\n\nExample internal behavior:\n\n```ts\nvideo.playbackRate = selectedRate;\n```\n\n### Long Press Playback\n\nHolding the player for one second temporarily changes the playback speed to `2x`.\n\n```text\nPress and hold → 2x\nRelease → 1x\n```\n\nThis feature works with mouse and touch events.\n\n---\n\n## Keyboard Shortcuts\n\nKeyboard shortcuts are ignored when the user is typing inside:\n\n- Input elements\n- Textarea elements\n- Content-editable elements\n\n| Key | Action |\n| --- | --- |\n| `Space` | Toggle play and pause |\n| `ArrowRight` | Forward 15 seconds |\n| `ArrowLeft` | Backward 15 seconds |\n| `M` | Toggle mute |\n\nExample:\n\n```ts\nif (event.code.toUpperCase() === \"SPACE\") {\n event.preventDefault();\n togglePlayHandle();\n}\n\nif (event.code.toUpperCase() === \"ARROWRIGHT\") {\n event.preventDefault();\n forwardCurrentTimeHandler();\n}\n\nif (event.code.toUpperCase() === \"ARROWLEFT\") {\n event.preventDefault();\n backwardCurrentTimeHandler();\n}\n\nif (event.code.toUpperCase() === \"KEYM\") {\n event.preventDefault();\n toggleMuteHandle();\n}\n```\n\n---\n\n## Player Interactions\n\n| Interaction | Action |\n| --- | --- |\n| Click or tap | Show or hide player controls |\n| Right-side repeated double interaction | Cumulatively seek forward in 15-second steps |\n| Left-side repeated double interaction | Cumulatively seek backward in 15-second steps |\n| Long press | Temporary `2x` playback |\n| Mouse move | Show controls |\n| Touch move | Show controls |\n\n### Cumulative Forward and Backward Seeking\n\nSibtorsh Player supports YouTube-style cumulative seeking when the user repeatedly double-clicks or double-taps the left or right side of the player.\n\nEach repeated interaction adds another 15 seconds to the current seek amount instead of treating every interaction as an isolated seek.\n\nExample forward sequence:\n\n```text\nFirst double interaction → +15s\nSecond double interaction → +30s\nThird double interaction → +45s\n```\n\n### Forward and Backward Indicators\n\nAfter seeking forward or backward, the related indicator remains visible for five seconds.\n\nIf the action runs repeatedly, the timer restarts from the latest execution.\n\n```ts\nif (forwardTimeoutRef.current) {\n clearTimeout(forwardTimeoutRef.current);\n}\n\nforwardTimeoutRef.current = setTimeout(() => {\n setIsForwardCurrentTime(false);\n forwardTimeoutRef.current = null;\n}, 5000);\n```\n\nStarting forward seeking immediately hides the backward indicator.\n\nStarting backward seeking immediately hides the forward indicator.\n\n---\n\n## Fullscreen\n\nThe player supports the standard Fullscreen API:\n\n```ts\nelement.requestFullscreen();\ndocument.exitFullscreen();\n```\n\nIt also checks browser-prefixed implementations:\n\n```ts\nelement.webkitRequestFullscreen;\nelement.mozRequestFullScreen;\nelement.msRequestFullscreen;\n```\n\nFullscreen change events supported by the player include:\n\n```text\nfullscreenchange\nwebkitfullscreenchange\nmozfullscreenchange\nMSFullscreenChange\n```\n\n### Safari and PWA Fallback\n\nFor iOS, Safari, and Safari-based PWA environments, the player provides a CSS-based fullscreen fallback.\n\nIn fullscreen mode, the video uses:\n\n```text\nobject-contain\n```\n\nThis ensures that the complete video frame remains visible.\n\n---\n\n## Ambient Mode\n\nWhen fullscreen mode is active, Sibtorsh Player can render a live ambient background using frames from the currently playing video.\n\nThe ambient layer is displayed behind the main video with blur, saturation, brightness, and scale effects. This fills the empty fullscreen space with colors from the video while keeping the original frame fully visible using `object-contain`.\n\nAmbient Mode behavior:\n\n- Activates only in fullscreen mode\n- Uses live frames from the current video\n- Places the ambient canvas behind the video\n- Applies blur and color enhancement effects\n- Does not intercept mouse or touch interactions\n- Keeps player controls above both the video and ambient layer\n- Stops updating when fullscreen mode is closed\n\nThe fullscreen layer order is:\n\n```text\nAmbient canvas → background\nVideo → middle layer\nPlayer controls → foreground\n```\n\n---\n\n## Playback Events\n\nYou can use `onPlay` and `onPause` for:\n\n- Analytics\n- Lesson progress tracking\n- User activity tracking\n- Saving playback state\n- Updating application UI\n\nExample:\n\n```tsx\nimport VideoPlayer from \"@alirezahosseini/sibtorsh-player\";\nimport \"@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css\";\n\nexport function AnalyticsExample() {\n return (\n \n {\n console.log(\"Playback started\");\n }}\n onPause={() => {\n console.log(\"Playback paused\");\n }}\n />\n
\n );\n}\n```\n## Current Time Tracking\n\nUse `onCurrentTime` when your application needs the current playback position.\n\nThe callback receives the current playback time in **seconds**.\n\n```tsx\n {\n console.log(\"Current playback time:\", currentTime);\n }}\n/>\n```\n\n---\n\n## Next.js Usage\n\nSibtorsh Player uses browser APIs and should run as a client component.\n\n### App Router\n\n```tsx\n\"use client\";\n\nimport VideoPlayer from \"@alirezahosseini/sibtorsh-player\";\nimport \"@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css\";\n\nexport default function LessonPlayer() {\n return (\n \n \n
\n );\n}\n```\n\n### Dynamic Import\n\nWhen server-side rendering causes browser API errors, import the player dynamically:\n\n```tsx\n\"use client\";\n\nimport dynamic from \"next/dynamic\";\nimport \"@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css\";\n\nconst VideoPlayer = dynamic(\n () => import(\"@alirezahosseini/sibtorsh-player\"),\n {\n ssr: false\n }\n);\n\nexport default function LessonPlayer() {\n return (\n \n \n
\n );\n}\n```\n\n### Global CSS Import\n\nIn some Next.js configurations, package CSS should be imported inside the root layout:\n\n```tsx\nimport \"@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css\";\n\nexport default function RootLayout({\n children\n}: {\n children: React.ReactNode;\n}) {\n return (\n \n {children}\n \n );\n}\n```\n\n---\n\n## Vite Usage\n\n```tsx\nimport React from \"react\";\nimport ReactDOM from \"react-dom/client\";\nimport VideoPlayer from \"@alirezahosseini/sibtorsh-player\";\n\nimport \"@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css\";\n\nfunction App() {\n return (\n \n \n \n
\n \n );\n}\n\nReactDOM.createRoot(\n document.getElementById(\"root\")!\n).render(\n \n \n \n);\n```\n\n---\n\n## Private Streams\n\nThe player can consume:\n\n- Authenticated playlist URLs\n- Signed URLs\n- Presigned object-storage URLs\n- Protected encryption key URLs\n- Private CDN URLs\n- API-proxied HLS playlists\n\nExample:\n\n```tsx\n\n```\n\nRecommended protected delivery flow:\n\n```text\nFrontend\n ↓\nRequest authorized video information\n ↓\nBackend validates the authenticated user\n ↓\nBackend returns a protected playlist URL\n ↓\nBackend returns a protected key URL\n ↓\nPlayer starts HLS playback\n```\n\nRecommended security approaches:\n\n- Keep master playlists private.\n- Keep rendition playlists private.\n- Keep AES-128 keys private.\n- Generate short-lived signed URLs.\n- Bind URLs to authenticated users when possible.\n- Validate active subscriptions.\n- Use CDN token authentication.\n- Configure CORS correctly.\n- Avoid exposing permanent object-storage URLs.\n\n---\n\n## CORS Configuration\n\nHLS playlists, segments, and encryption keys must allow requests from the application origin.\n\nExample headers:\n\n```http\nAccess-Control-Allow-Origin: https://your-app.example.com\nAccess-Control-Allow-Methods: GET, HEAD, OPTIONS\nAccess-Control-Allow-Headers: Range, Authorization, Content-Type\nAccess-Control-Expose-Headers: Content-Length, Content-Range, Accept-Ranges\n```\n\nWhen authentication cookies are required:\n\n```http\nAccess-Control-Allow-Credentials: true\n```\n\nDo not combine credentials with:\n\n```http\nAccess-Control-Allow-Origin: *\n```\n\nInstead, return the exact allowed origin:\n\n```http\nAccess-Control-Allow-Origin: https://your-app.example.com\n```\n\n### Nginx Example\n\n```nginx\nlocation /videos/ {\n add_header Access-Control-Allow-Origin \"https://your-app.example.com\" always;\n add_header Access-Control-Allow-Methods \"GET, HEAD, OPTIONS\" always;\n add_header Access-Control-Allow-Headers \"Authorization, Range, Content-Type\" always;\n add_header Access-Control-Expose-Headers \"Content-Length, Content-Range, Accept-Ranges\" always;\n\n if ($request_method = OPTIONS) {\n return 204;\n }\n}\n```\n\n---\n\n## Visibility Handling\n\nThe player automatically pauses video when the browser tab becomes hidden:\n\n```ts\ndocument.addEventListener(\n \"visibilitychange\",\n visibilityChangeHandler\n);\n```\n\nThe player also uses `IntersectionObserver`.\n\nIf less than 50% of the player is visible:\n\n```text\nVideo pauses automatically\n```\n\nIf the video was playing before leaving the viewport:\n\n```text\nVideo resumes when it becomes visible again\n```\n\nThe observer threshold is:\n\n```ts\n{\n threshold: [0, 0.5, 1]\n}\n```\n\n---\n\n## Error Handling\n\nThe player handles native media errors and `hls.js` errors.\n\n### Non-Fatal HLS Errors\n\nNon-fatal HLS warnings are logged and playback continues:\n\n```ts\nif (!data.fatal) {\n console.warn(\"Hls non-fatal warning:\", data);\n return;\n}\n```\n\nAn example of a recoverable warning is:\n\n```text\nbufferSeekOverHole\n```\n\n### Network Errors\n\nNetwork errors attempt to restart loading:\n\n```ts\nhls.startLoad();\n```\n\n### Media Errors\n\nMedia errors attempt media recovery:\n\n```ts\nhls.recoverMediaError();\n```\n\n### Fatal Errors\n\nFatal and unrecoverable errors show the player error state.\n\n```ts\nerrorHandler();\nhls.destroy();\n```\n\n### Native Media Errors\n\nThe player handles browser media error codes:\n\n| Error code | Description |\n| --- | --- |\n| `MEDIA_ERR_ABORTED` | Video loading was aborted |\n| `MEDIA_ERR_NETWORK` | A network error occurred |\n| `MEDIA_ERR_DECODE` | The browser could not decode the video |\n| `MEDIA_ERR_SRC_NOT_SUPPORTED` | Video source or format is unsupported |\n\n---\n\n## Styling and Sizing\n\nAlways import the player stylesheet:\n\n```tsx\nimport \"@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css\";\n```\n\nThe player uses:\n\n```text\nwidth: 100%\nheight: 100%\n```\n\nThe parent element must provide the required dimensions.\n\n### Aspect Ratio Container\n\n```tsx\n\n \n\n```\n\n### Fixed Height Container\n\n```tsx\n\n \n\n```\n\n### Tailwind CSS Container\n\n```tsx\n\n \n
\n```\n\nThe player includes its own prefixed classes and responsive container-query behavior.\n\n---\n\n## Browser Support\n\n| Browser | Playback method | Support |\n| --- | --- | --- |\n| Chrome | `hls.js` and native video | Supported |\n| Microsoft Edge | `hls.js` and native video | Supported |\n| Firefox | `hls.js` and native video | Supported |\n| Safari macOS | Native HLS | Supported |\n| Safari iOS | Native HLS | Supported |\n| Chrome Android | `hls.js` or native video | Supported |\n| Installed PWA | Browser-dependent | Supported with fallback behavior |\n\nActual codec support depends on:\n\n- Browser\n- Operating system\n- Hardware decoder\n- Video codec\n- Audio codec\n- HLS segment format\n\n### Recommended Codecs\n\nFor broad compatibility:\n\n```text\nVideo codec: H.264 / AVC\nAudio codec: AAC\nPlaylist: HLS\nSegments: MPEG-TS or compatible fragmented MP4\n```\n\n---\n\n## Troubleshooting\n\n### Player Has Zero Height\n\nThe player fills its parent element.\n\nIncorrect:\n\n```tsx\n\n \n
\n```\n\nCorrect:\n\n```tsx\n\n \n
\n```\n\n---\n\n### Player Styles Are Missing\n\nImport the distributed CSS once:\n\n```tsx\nimport \"@alirezahosseini/sibtorsh-player/dist/sibtorsh-player.css\";\n```\n\n---\n\n### HLS Works in Safari but Not Chrome\n\nVerify that:\n\n- The master playlist allows CORS.\n- Rendition playlists allow CORS.\n- Segment URLs are valid.\n- Key URLs are valid.\n- Signed URLs have not expired.\n- The stream uses supported codecs.\n- The response content type is correct.\n\nRecommended playlist content type:\n\n```http\nContent-Type: application/vnd.apple.mpegurl\n```\n\n---\n\n### HLS Works in Chrome but Not Safari\n\nSafari uses native HLS.\n\nVerify that:\n\n- The Safari playlist contains valid URLs.\n- Key URLs are directly accessible by Safari.\n- Cookies are configured correctly.\n- The backend accepts `is_safari=1`.\n- Rendition playlist URLs are absolute or correctly resolvable.\n- Segment URLs have not expired.\n\n---\n\n### Quality Options Are Missing\n\nQuality options are generated from the master playlist.\n\nMake sure the source contains:\n\n```m3u8\n#EXT-X-STREAM-INF\n```\n\nA single rendition playlist does not provide multiple quality options.\n\n---\n\n### Safari Quality Switching Does Not Work\n\nMake sure the master playlist can be fetched from JavaScript:\n\n```ts\nfetch(masterPlaylistUrl, {\n method: \"GET\",\n credentials: \"include\",\n headers: {\n Accept: \"application/vnd.apple.mpegurl\"\n }\n});\n```\n\nThe playlist response must allow CORS.\n\n---\n\n### `bufferSeekOverHole` Warning\n\nThis is usually a recoverable `hls.js` warning.\n\nExample:\n\n```text\nfragment loaded with buffer holes, seeking from 0 to 0.1\n```\n\nIf:\n\n```text\nfatal: false\n```\n\nthe player should continue playback.\n\nRepeated gaps in the middle of a video may indicate timestamp discontinuities between HLS segments.\n\n---\n\n### Stream Returns 403\n\nCheck:\n\n- Playlist signed URL expiration\n- Rendition signed URL expiration\n- Segment signed URL expiration\n- Key signed URL expiration\n- Authentication cookies\n- Authorization headers\n- User subscription\n- CORS configuration\n- CDN rules\n- Referrer restrictions\n\n---\n\n### Video Does Not Resume After Quality Change\n\nSafari quality switching waits for `loadedmetadata`, restores the previous playback time, and then resumes playback.\n\nMake sure the selected rendition:\n\n- Is accessible\n- Has a valid duration\n- Uses compatible timestamps\n- Uses the same content timeline\n\n---\n\n### Fullscreen Does Not Work\n\nFullscreen APIs require direct user interaction.\n\nCall fullscreen from:\n\n- A click event\n- A touch event\n- A keyboard event initiated by the user\n\nBrowsers may block fullscreen requests triggered automatically.\n\n---\n\n## TypeScript\n\nType declarations are included in the package.\n\nNo separate type package is required:\n\n```bash\nnpm install @alirezahosseini/sibtorsh-player\n```\n\nImport:\n\n```tsx\nimport VideoPlayer from \"@alirezahosseini/sibtorsh-player\";\n```\n\nExample typed component:\n\n```tsx\nimport VideoPlayer from \"@alirezahosseini/sibtorsh-player\";\n\ninterface LessonPlayerProps {\n playlistUrl: string;\n keyUrl?: string;\n posterUrl?: string;\n title?: string;\n}\n\nexport default function LessonPlayer({\n playlistUrl,\n keyUrl,\n posterUrl,\n title\n}: LessonPlayerProps) {\n return (\n \n \n
\n );\n}\n```\n\n---\n\n## Development\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nStart development mode:\n\n```bash\nnpm run dev\n```\n\nBuild the package:\n\n```bash\nnpm run build\n```\n\nThe build process generates:\n\n```text\ndist/sibtorsh-player.es.js\ndist/sibtorsh-player.umd.js\ndist/sibtorsh-player.css\ndist/*.d.ts\n```\n\n---\n\n## Security\n\nClient-side JavaScript cannot completely prevent an authorized user from:\n\n- Inspecting network requests\n- Inspecting playlist URLs\n- Inspecting downloaded package files\n- Reading bundled JavaScript\n- Copying previously downloaded media\n- Recording the screen\n\nFor stronger content protection, combine the player with:\n\n- Private HLS playlists\n- Private rendition playlists\n- AES-128 encryption\n- Private encryption keys\n- Short-lived signed URLs\n- Session-bound authorization\n- User-bound authorization\n- Domain validation\n- CDN token authentication\n- Watermarking\n- Concurrent-session limits\n- DRM for high-value content\n\nSupported DRM systems may include:\n\n```text\nGoogle Widevine\nApple FairPlay\nMicrosoft PlayReady\n```\n\nSibtorsh Player currently focuses on HLS and AES-128 delivery and does not claim to provide full DRM protection.\n\n---\n\n## Package Information\n\n```text\nPackage: @alirezahosseini/sibtorsh-player\nFramework: React\nLanguage: TypeScript\nHLS engine: hls.js\nModule formats: ES Module and UMD\nStylesheet: Included\nType declarations: Included\n```\n\n---\n\n## License\n\nThis package is distributed under the license defined by the project owner.\n\nBefore public or commercial distribution, update the `license` field in `package.json`.\n\nExample proprietary configuration:\n\n```json\n{\n \"license\": \"UNLICENSED\"\n}\n```\n\nExample MIT configuration:\n\n```json\n{\n \"license\": \"MIT\"\n}\n```\n\n---\n\n## Author\n\n**Alireza Hosseini**\n\nnpm package:\n\n```text\n@alirezahosseini/sibtorsh-player\n```","readmeFilename":"README.md"}