strataplayer 1.0.0 → 1.0.3

package/README.md

@@ -1,18 +1,18 @@
 # StrataPlayer
 
 <div align="center">
-  <img src="public/logo.png" alt="StrataPlayer Logo" width="128" />
+  <img src="https://dev-ashishranjan.github.io/StrataPlayer/logo.png" alt="StrataPlayer Logo" width="128" />
   
   <p align="center">
-    <strong>A robust, secure, and production-grade video player built for the modern web.</strong>
+    <strong>The Universal Media Engine for the Modern Web.</strong>
   </p>
   
   <p align="center">
     <a href="https://github.com/dev-AshishRanjan/StrataPlayer/blob/main/LICENSE">
       <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" />
     </a>
-    <a href="https://react.dev">
-      <img src="https://img.shields.io/badge/react-19.0-blue" alt="React" />
+    <a href="https://www.npmjs.com/package/strataplayer">
+      <img src="https://img.shields.io/npm/v/strataplayer" alt="NPM Version" />
     </a>
     <a href="https://www.typescriptlang.org/">
       <img src="https://img.shields.io/badge/typescript-5.0-blue" alt="TypeScript" />
@@ -20,72 +20,53 @@
   </p>
 </div>
 
-## Overview
+## Introduction
 
-StrataPlayer is a highly customizable, high-performance HTML5 video player designed for React applications. It features a lightweight core with a plugin architecture, advanced subtitle management, robust error handling, and a sleek, themeable UI powered by Tailwind CSS.
+StrataPlayer represents a shift in how media playback is handled on the web. Instead of tightly coupling playback logic to a specific framework, StrataPlayer operates as a **framework-agnostic engine**.
 
-It supports HLS (HTTP Live Streaming) out of the box via `hls.js`, along with standard MP4/WebM formats, making it suitable for VOD, live streaming, and complex media applications.
+While the UI layer is powered by the high-performance concurrent rendering of React 19, the player itself can be mounted into **any** application—be it Vanilla JS, Vue, Svelte, or Angular. It decouples the "playback state" (time, buffer, quality) from the "view layer," ensuring that high-frequency updates (like progress bars) never cause performance bottlenecks in your host application.
 
-## ✨ Features
-
-### Core Playback
-
-- **Multi-Format Support:** Seamlessly plays HLS (`.m3u8`), MP4, WebM, and DASH (via plugin extension).
-- **Robust Error Handling:** Exponential backoff retry logic for network failures and stream interruptions.
-- **Adaptive Bitrate:** Automatic quality switching with manual override controls.
-- **Audio Engine:** Built-in Web Audio API integration for **Audio Boost** (up to 300% volume).
-
-### User Interface & Experience
+## Core Philosophy
 
-- **Fully Themeable:** Includes 4 built-in themes (Default, Pixel, Game, Hacker) and custom accent color support.
-- **Responsive Controls:** Mobile-friendly touch controls and gesture support (double tap to seek).
-- **Keyboard Shortcuts:** Full accessibility support with standard hotkeys (`Space`, `F`, `M`, Arrows).
-- **Picture-in-Picture:** Native PiP support for multitasking.
-- **Chromecast Support:** Built-in Google Cast integration.
+1.  **Universal Compatibility:** Write once, run anywhere. Whether you are building a static HTML site or a complex Next.js application, the implementation remains consistent.
+2.  **State Isolation:** The playback engine runs on a detached state store (`NanoStore`). This allows the player to handle micro-updates (video time, download progress) internally without triggering re-renders in your parent application.
+3.  **Opt-in Complexity:** The core is lightweight. Advanced capabilities like HLS/DASH adaptive streaming, analytics, or casting are treated as plugins, keeping your bundle size strictly minimal unless needed.
 
-### Advanced Subtitles
+## ✨ Features
 
-- **Custom Rendering:** High-performance canvas/DOM-based subtitle rendering.
-- **Full Customization:** Users can adjust font size, color, background opacity, blur, and offsets.
-- **Synchronization:** Manual subtitle offset adjustment to fix out-of-sync captions.
-- **Local Upload:** Support for drag-and-drop `.vtt` and `.srt` files.
+### Engine & Performance
 
-### Developer Experience
+- **Framework Agnostic:** First-class support for React, with a mounting API for Vue, Svelte, and Vanilla JS.
+- **Resilient Network Handling:** Automatic exponential backoff and retry logic for unstable connections.
+- **Adaptive Streaming:** Native support for HLS (`.m3u8`) and DASH via plugin architecture.
+- **Audio Boost Engine:** Integrated Web Audio API nodes allowing volume boosting up to 300%.
 
-- **React 19 Ready:** Built with the latest React patterns (Hooks, `useSyncExternalStore`).
-- **State Management:** Lightweight, external store (`NanoStore`) for high-performance updates without re-renders.
-- **Plugin System:** Easily extend functionality without bloating the core.
-- **TypeScript:** 100% type-safe.
+### Visuals & Interface
 
-## 🚀 Getting Started
+- **Themeable System:** 4 built-in distinct themes (Default, Pixel, Game, Hacker) with CSS variable support.
+- **Advanced Subtitles:** DOM-based rendering supporting custom positioning, shadows, and runtime sync adjustment.
+- **Mobile Optimized:** Touch gestures for seeking (double-tap), scrubbing, and volume control.
+- **Google Cast:** Native Chromecast integration.
 
-### Installation
+## 🚀 Installation
 
 ```bash
-# Clone the repository
-git clone https://github.com/dev-AshishRanjan/StrataPlayer.git
-
-# Navigate to project directory
-cd StrataPlayer
-
-# Install dependencies
-npm install
-
-# Start the development server
-npm run dev
+npm install strataplayer
 ```
 
-### Basic Usage
+## 💻 Usage
+
+### React
 
 ```tsx
-import { StrataPlayer } from "./ui/StrataPlayer";
+import { StrataPlayer } from "strataplayer";
+import "strataplayer/style.css";
 
 const App = () => {
   return (
-    <div className="w-full max-w-4xl mx-auto">
+    <div className="player-wrapper">
       <StrataPlayer
         src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
-        autoPlay={false}
         theme="default"
         themeColor="#6366f1"
       />
@@ -94,17 +75,57 @@ const App = () => {
 };
 ```
 
-### Advanced Usage (Sources & Tracks)
+### Vanilla JS / Vue / Svelte / Angular
 
-```tsx
-<StrataPlayer
-  sources={[
-    { name: "HLS Master", url: "https://example.com/master.m3u8", type: "hls" },
-    { name: "MP4 Fallback", url: "https://example.com/video.mp4", type: "mp4" },
-  ]}
-  poster="https://example.com/poster.jpg"
-  thumbnails="https://example.com/thumbnails.vtt"
-  textTracks={[
+For non-React frameworks, use the `mountStrataPlayer` helper. This mounts the player into a specific DOM node and returns an instance for cleanup and updates.
+
+**index.html**
+
+```html
+<div id="player-container" style="width: 100%; aspect-ratio: 16/9;"></div>
+```
+
+**main.js**
+
+```javascript
+import { mountStrataPlayer } from "strataplayer";
+import "strataplayer/style.css";
+
+const container = document.getElementById("player-container");
+
+const instance = mountStrataPlayer(container, {
+  src: "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8",
+  autoPlay: false,
+  theme: "hacker",
+  themeColor: "#22c55e",
+  sources: [
+    { name: "HLS Stream", url: "...", type: "hls" },
+    { name: "MP4 Fallback", url: "...", type: "mp4" },
+  ],
+});
+
+// To update props later (e.g., change video):
+// instance.update({ src: 'new-video.mp4' });
+
+// To destroy/cleanup (e.g., in Vue onUnmounted):
+// instance.unmount();
+```
+
+## ⚙️ Advanced Configuration
+
+### Sources & Tracks
+
+StrataPlayer supports complex source arrays and subtitle tracks.
+
+```javascript
+const props = {
+  sources: [
+    { name: "1080p HLS", url: "master.m3u8", type: "hls" },
+    { name: "720p MP4", url: "fallback.mp4", type: "mp4" },
+  ],
+  poster: "https://example.com/poster.jpg",
+  thumbnails: "https://example.com/storyboard.vtt", // For seek preview
+  textTracks: [
     {
       kind: "subtitles",
       label: "English",
@@ -112,8 +133,8 @@ const App = () => {
       srcLang: "en",
       default: true,
     },
-  ]}
-/>
+  ],
+};
 ```
 
 ## ⌨️ Keyboard Shortcuts
@@ -130,16 +151,16 @@ const App = () => {
 
 ## 🎨 Themes
 
-StrataPlayer comes with preset themes that can be applied via props or changed at runtime by the user:
+StrataPlayer separates layout from aesthetics. Themes can be switched instantly at runtime via props:
 
-- **Default:** Modern, clean, and professional (Inter font).
-- **Pixel:** Retro gaming aesthetic (Press Start 2P font).
-- **Game:** Cinematic RPG style (Cinzel font).
-- **Hacker:** Terminal/Cyberpunk aesthetic (JetBrains Mono font).
+- **Default:** Professional, clean lines using Inter font.
+- **Pixel:** Retro-gaming aesthetic with sharp edges and 8-bit fonts.
+- **Game:** Cinematic RPG style with serif typography and gold accents.
+- **Hacker:** Terminal-inspired aesthetic with scanlines and monospaced fonts.
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+We welcome contributions that align with our philosophy of performance and modularity.
 
 1.  Fork the project
 2.  Create your feature branch (`git checkout -b feature/AmazingFeature`)