stormcloud-video-player 0.1.12 → 0.2.0

package/README.md

@@ -1,17 +1,19 @@
 # Stormcloud Video Player
 
-A professional HLS video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, and Google IMA SDK integration for seamless VAST/VPAID ad playback.
+A professional video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, and Google IMA SDK integration for seamless VAST/VPAID ad playback. Now featuring a modern, extensible architecture inspired by react-player.
 
 ## 🎯 Key Features
 
+- **Multi-Format Support**: Automatic detection and playback of HLS streams and regular video files
 - **Precision Ad Alignment**: Tight synchronization with SCTE-35 CUE-OUT signals
 - **Smart Mid-Roll Handling**: Automatic detection and playback of remaining ad portions when joining late
 - **Flexible Ad Scheduling**: Support for both SCTE-35 markers and external ad schedules
 - **Enhanced UI Controls**: Beautiful, adaptive video controls that work on any background color
 - **Live Mode Support**: Specialized controls for live streaming with volume adjustment
 - **Cross-Platform**: Works on desktop, mobile, tablets, and smart TVs
-- **React Ready**: Includes React component for easy integration
+- **React Ready**: Multiple React components for different use cases
 - **TypeScript Support**: Full type definitions included
+- **Professional Architecture**: Modular player system with lazy loading
 
 ## 🚀 Quick Start
 
@@ -23,6 +25,8 @@ npm install stormcloud-video-player hls.js
 
 ### React Integration
 
+#### Option 1: Legacy Component (Recommended for existing projects)
+
 ```jsx
 import React from "react";
 import { StormcloudVideoPlayerComponent } from "stormcloud-video-player";
@@ -53,6 +57,47 @@ function MyVideoApp() {
 }
 ```
 
+#### Option 2: New Professional Component (For new projects)
+
+```jsx
+import React from "react";
+import StormcloudPlayer from "stormcloud-video-player";
+
+function MyVideoApp() {
+  return (
+    <StormcloudPlayer
+      src="https://your-stream.com/playlist.m3u8"
+      playing={true}
+      muted={true}
+      controls={true}
+      width="100%"
+      height="auto"
+      style={{ aspectRatio: "16/9" }}
+      // Stormcloud-specific props
+      allowNativeHls={true}
+      showCustomControls={true}
+      licenseKey="your_license_key_here"
+      onReady={(player) => {
+        console.log("Player is ready!", player);
+      }}
+      onPlay={() => console.log("Playing")}
+      onPause={() => console.log("Paused")}
+      onProgress={(state) => console.log("Progress:", state)}
+    />
+  );
+}
+```
+
+#### Option 3: Specific Player Types (Optimized bundles)
+
+```jsx
+// For HLS streams only (smaller bundle)
+import StormcloudPlayer from "stormcloud-video-player/hls";
+
+// For regular video files only (smallest bundle)
+import StormcloudPlayer from "stormcloud-video-player/file";
+```
+
 ### Vanilla JavaScript
 
 ```javascript
@@ -83,7 +128,7 @@ await player.load();
 <script src="https://cdn.jsdelivr.net/npm/stormcloud-video-player/dist/stormcloud-vp.min.js"></script>
 
 <script>
-  const { StormcloudVideoPlayer } = window.StormcloudVideoPlayer;
+  const { StormcloudVideoPlayer } = window.StormcloudVP;
 
   const video = document.getElementById("video");
   const player = new StormcloudVideoPlayer({
@@ -97,9 +142,169 @@ await player.load();
 </script>
 ```
 
+## 🏗️ Professional Architecture
+
+The Stormcloud Video Player now follows a professional, modular architecture similar to react-player:
+
+### Player System Overview
+
+```
+StormcloudPlayer (Main Component)
+├── Player (Internal Wrapper)
+├── HlsPlayer (HLS Stream Handler)
+├── FilePlayer (Regular Video Handler)
+└── Legacy StormcloudVideoPlayerComponent
+```
+
+### What Each Player Does
+
+#### 🎬 **HlsPlayer** - HLS Stream Specialist
+
+- **Purpose**: Handles HLS (.m3u8) streams with advanced features
+- **Features**:
+  - SCTE-35 ad marker detection and processing
+  - Google IMA SDK integration for VAST/VPAID ads
+  - Live stream support with low-latency mode
+  - Drift correction for live timing
+  - Manifest-based and ID3 ad markers
+  - Ad failsafe and recovery mechanisms
+
+```jsx
+// Automatically used for HLS streams
+<StormcloudPlayer src="https://example.com/stream.m3u8" />
+```
+
+#### 📹 **FilePlayer** - Regular Video Handler
+
+- **Purpose**: Handles regular video files (MP4, WebM, etc.)
+- **Features**:
+  - Direct video element control
+  - Picture-in-Picture support
+  - Standard HTML5 video features
+  - Lightweight and fast
+  - No HLS.js dependency
+
+```jsx
+// Automatically used for regular video files
+<StormcloudPlayer src="https://example.com/video.mp4" />
+```
+
+### Automatic Player Selection
+
+The system automatically chooses the right player based on your video source:
+
+```javascript
+// HLS streams → HlsPlayer
+"https://example.com/playlist.m3u8"; // Uses HlsPlayer
+"https://example.com/stream/index.m3u8"; // Uses HlsPlayer
+
+// Regular videos → FilePlayer
+"https://example.com/video.mp4"; // Uses FilePlayer
+"https://example.com/video.webm"; // Uses FilePlayer
+"https://example.com/video.mov"; // Uses FilePlayer
+```
+
+### Bundle Optimization
+
+Import only what you need for smaller bundles:
+
+```javascript
+// Full player (auto-detection) - ~140KB
+import StormcloudPlayer from "stormcloud-video-player";
+
+// HLS only - ~120KB
+import StormcloudPlayer from "stormcloud-video-player/hls";
+
+// File only - ~80KB
+import StormcloudPlayer from "stormcloud-video-player/file";
+
+// Legacy component - Full features
+import { StormcloudVideoPlayerComponent } from "stormcloud-video-player";
+```
+
 ## 📖 API Reference
 
-### StormcloudVideoPlayer Class
+### StormcloudPlayer Component (New)
+
+#### Props
+
+```typescript
+interface StormcloudPlayerProps {
+  // Media source
+  src?: string;
+
+  // Playback control
+  playing?: boolean;
+  loop?: boolean;
+  controls?: boolean;
+  volume?: number;
+  muted?: boolean;
+  playbackRate?: number;
+
+  // Styling
+  width?: string | number;
+  height?: string | number;
+  style?: CSSProperties;
+  className?: string;
+  wrapperClassName?: string;
+  wrapperStyle?: CSSProperties;
+
+  // Video attributes
+  playsInline?: boolean;
+  autoplay?: boolean;
+  preload?: string;
+  poster?: string;
+
+  // Stormcloud-specific
+  allowNativeHls?: boolean;
+  lowLatencyMode?: boolean;
+  driftToleranceMs?: number;
+  immediateManifestAds?: boolean;
+  debugAdTiming?: boolean;
+  showCustomControls?: boolean;
+  licenseKey?: string;
+  adFailsafeTimeoutMs?: number;
+
+  // Event handlers
+  onReady?: (player: StormcloudVideoPlayer) => void;
+  onStart?: () => void;
+  onPlay?: () => void;
+  onPause?: () => void;
+  onBuffer?: () => void;
+  onBufferEnd?: () => void;
+  onEnded?: () => void;
+  onError?: (
+    error: any,
+    data?: any,
+    hlsInstance?: any,
+    hlsGlobal?: any
+  ) => void;
+  onDuration?: (duration: number) => void;
+  onSeek?: (seconds: number) => void;
+  onProgress?: (state: {
+    played: number;
+    playedSeconds: number;
+    loaded: number;
+    loadedSeconds: number;
+  }) => void;
+  onVolumeToggle?: () => void;
+  onFullscreenToggle?: () => void;
+  onControlClick?: () => void;
+}
+```
+
+#### Methods
+
+```typescript
+// Player instance methods (available via ref or onReady)
+player.seekTo(amount: number, type?: 'seconds' | 'fraction')
+player.getCurrentTime(): number | null
+player.getSecondsLoaded(): number | null
+player.getDuration(): number | null
+player.getInternalPlayer(key?: string): any
+```
+
+### StormcloudVideoPlayer Class (Core)
 
 #### Constructor
 
@@ -110,13 +315,19 @@ new StormcloudVideoPlayer(config: StormcloudVideoPlayerConfig)
 #### Methods
 
 | Method                                     | Description                                   | Returns         |
-| ------------------------------------------ | --------------------------------------------- | --------------- |
+| ------------------------------------------ | --------------------------------------------- | --------------- | -------- |
 | `load()`                                   | Initialize and start video playback           | `Promise<void>` |
 | `destroy()`                                | Clean up player resources and event listeners | `void`          |
 | `toggleMute()`                             | Toggle video mute state                       | `void`          |
 | `toggleFullscreen()`                       | Enter/exit fullscreen mode                    | `Promise<void>` |
 | `isMuted()`                                | Check if video is currently muted             | `boolean`       |
 | `isFullscreen()`                           | Check if player is in fullscreen mode         | `boolean`       |
+| `isAdPlaying()`                            | Check if an ad is currently playing           | `boolean`       |
+| `isShowingAds()`                           | Check if ads are being shown                  | `boolean`       |
+| `getCurrentAdIndex()`                      | Get current ad index in pod                   | `number`        |
+| `getTotalAdsInBreak()`                     | Get total ads in current break                | `number`        |
+| `shouldShowNativeControls()`               | Check if native controls should be shown      | `boolean`       |
+| `getStreamType()`                          | Get detected stream type                      | `'hls'          | 'other'` |
 | `loadDefaultVastFromAdstorm(url, params?)` | Load VAST tags from Adstorm API               | `Promise<void>` |
 
 #### Configuration Options
@@ -124,14 +335,14 @@ new StormcloudVideoPlayer(config: StormcloudVideoPlayerConfig)
 ```typescript
 interface StormcloudVideoPlayerConfig {
   videoElement: HTMLVideoElement; // Target video element
-  src: string; // HLS stream URL
+  src: string; // Stream URL (HLS or regular video)
   autoplay?: boolean; // Auto-start playback (default: false)
   muted?: boolean; // Start muted (default: false)
-  allowNativeHls?: boolean; // Use native HLS when available (default: true)
+  allowNativeHls?: boolean; // Use native HLS when available (default: false)
   showCustomControls?: boolean; // Enable enhanced UI controls (default: false)
   lowLatencyMode?: boolean; // Enable low-latency mode for live streams (default: false)
-  driftToleranceMs?: number; // Drift tolerance for live streams (default: 3000)
-  immediateManifestAds?: boolean; // Load ads immediately from manifest (default: false)
+  driftToleranceMs?: number; // Drift tolerance for live streams (default: 1000)
+  immediateManifestAds?: boolean; // Load ads immediately from manifest (default: true)
   licenseKey?: string; // API authentication key
   debugAdTiming?: boolean; // Enable debug logging (default: false)
   adFailsafeTimeoutMs?: number; // Ad timeout in milliseconds (default: 10000)
@@ -157,7 +368,7 @@ The player includes beautiful, adaptive video controls that ensure visibility on
 
 #### Full Controls (HLS Streams)
 
-When `showCustomControls={true}` and `allowNativeHls={true}` for HLS streams:
+When `showCustomControls={true}` for HLS streams:
 
 - Progress timeline with seek functionality
 - Play/pause button with smooth animations
@@ -166,9 +377,9 @@ When `showCustomControls={true}` and `allowNativeHls={true}` for HLS streams:
 - Fullscreen toggle
 - Time display (current/duration)
 
-#### Live Mode Controls (Non-HLS or Native HLS disabled)
+#### Live Mode Controls (Non-HLS or when native HLS is used)
 
-When `showCustomControls={true}` for live streams or when native HLS is disabled:
+When `showCustomControls={true}` for regular video files:
 
 - Volume control with hover-activated slider
 - Fullscreen toggle
@@ -184,7 +395,7 @@ All controls use a consistent high-contrast design:
 - **Smooth transitions** for professional feel
 
 ```jsx
-<StormcloudVideoPlayerComponent
+<StormcloudPlayer
   showCustomControls={true}
   wrapperStyle={{ borderRadius: "12px", overflow: "hidden" }}
   onVolumeToggle={() => console.log("Volume toggled")}
@@ -192,11 +403,11 @@ All controls use a consistent high-contrast design:
 />
 ```
 
-## 🎬 Ad Integration
+## 🎬 Ad Integration (HLS Streams Only)
 
 ### SCTE-35 Support
 
-The player automatically detects and responds to SCTE-35 signals embedded in HLS streams:
+The HlsPlayer automatically detects and responds to SCTE-35 signals embedded in HLS streams:
 
 - **CUE-OUT**: Triggers ad break start
 - **CUE-OUT-CONT**: Handles mid-roll continuation
@@ -218,6 +429,19 @@ When viewers join during an ad break:
 - **play_remaining**: Plays the remaining portion of the current ad
 - **skip_to_content**: Skips to main content (configurable via API)
 
+### Ad Status Monitoring
+
+```jsx
+<StormcloudPlayer
+  onReady={(player) => {
+    // Monitor ad playback
+    console.log("Is ad playing:", player.isAdPlaying());
+    console.log("Current ad index:", player.getCurrentAdIndex());
+    console.log("Total ads in break:", player.getTotalAdsInBreak());
+  }}
+/>
+```
+
 ## 🔐 Authentication
 
 The player supports license key authentication for enhanced features:
@@ -237,36 +461,76 @@ Authenticated requests are sent to:
 
 ## 🔧 Advanced Configuration
 
-### Custom Styling
+### Custom Player Creation
 
-```css
-.stormcloud-video-player {
-  width: 100%;
-  height: 100%;
-  background: #000;
-}
+Create your own player with specific capabilities:
 
-.stormcloud-video-player video {
-  width: 100%;
-  height: 100%;
-  object-fit: contain;
-}
+```javascript
+import { createStormcloudPlayer, players } from "stormcloud-video-player";
+
+// Create a player with only HLS support
+const HLSOnlyPlayer = createStormcloudPlayer([
+  players.find((p) => p.key === "hls"),
+]);
+
+// Create a player with custom fallback
+const CustomPlayer = createStormcloudPlayer(
+  players,
+  players.find((p) => p.key === "file") // fallback to file player
+);
 ```
 
-### Event Handling
+### Adding Custom Players
 
 ```javascript
-player.on("adStart", (event) => {
-  console.log("Ad started:", event.ad);
+import StormcloudPlayer from "stormcloud-video-player";
+
+// Add a custom player for a specific format
+StormcloudPlayer.addCustomPlayer({
+  key: "custom",
+  name: "CustomPlayer",
+  canPlay: (src) => src.includes("custom://"),
+  lazyPlayer: React.lazy(() => import("./CustomPlayer")),
 });
+```
 
-player.on("adComplete", (event) => {
-  console.log("Ad completed:", event.ad);
-});
+### Player Detection
 
-player.on("contentResumed", () => {
-  console.log("Content playback resumed");
-});
+```javascript
+import StormcloudPlayer from "stormcloud-video-player";
+
+// Check if a URL can be played
+const canPlay = StormcloudPlayer.canPlay("https://example.com/video.m3u8");
+console.log("Can play:", canPlay); // true
+
+// Check Picture-in-Picture support
+const canPIP = StormcloudPlayer.canEnablePIP("https://example.com/video.mp4");
+console.log("Supports PIP:", canPIP); // true for file player
+```
+
+### Event Handling
+
+```jsx
+<StormcloudPlayer
+  onReady={(player) => {
+    console.log("Player ready");
+  }}
+  onPlay={() => {
+    console.log("Playback started");
+  }}
+  onPause={() => {
+    console.log("Playback paused");
+  }}
+  onProgress={(state) => {
+    console.log("Progress:", state.playedSeconds, "of", state.loadedSeconds);
+  }}
+  onError={(error, data, hlsInstance, hlsGlobal) => {
+    console.error("Player error:", error);
+    if (hlsInstance) {
+      console.log("HLS instance available for recovery");
+    }
+  }}
+/>
 ```
 
 ## 🌐 Browser Support
@@ -275,41 +539,133 @@ player.on("contentResumed", () => {
 - **Mobile**: iOS Safari 12+, Chrome Mobile 60+
 - **Smart TV**: WebOS, Tizen, Android TV, Roku, Apple TV
 
+### Format Support by Player
+
+#### HlsPlayer
+
+- **HLS Streams**: `.m3u8` files
+- **Native HLS**: Safari, iOS Safari (when `allowNativeHls=true`)
+- **HLS.js**: Chrome, Firefox, Edge (automatic fallback)
+
+#### FilePlayer
+
+- **Video Formats**: MP4, WebM, MOV, AVI, OGV
+- **Audio Formats**: MP3, WAV, OGG, AAC
+- **Streaming**: Progressive download
+- **Picture-in-Picture**: Supported browsers
+
 ## 🏗️ Development
 
 ### Build Commands
 
 ```bash
-npm run build      # Build production bundle
-npm run dev        # Development watch mode
-npm run clean      # Clean build artifacts
-npm run test       # Run test suite
-npm run lint       # Lint codebase
+# Build everything
+npm run build:all
+
+# Individual builds
+npm run build:lib      # Library build (ESM/CJS)
+npm run build:minified # Minified UMD bundle
+npm run build:dist     # Production UMD bundle
+
+# Development
+npm run dev            # Development watch mode
+npm run clean          # Clean build artifacts
+npm run test           # Run test suite
+npm run lint           # Lint codebase
 ```
 
 ### Project Structure
 
 ```
 src/
-├── index.ts                    # Main exports
+├── index.ts                           # Main exports
+├── StormcloudPlayer.tsx               # New main component
+├── Player.tsx                         # Internal wrapper component
+├── players/
+│   ├── index.ts                       # Player registry
+│   ├── HlsPlayer.tsx                  # HLS stream handler
+│   └── FilePlayer.tsx                 # Regular video handler
 ├── player/
-│   └── StormcloudVideoPlayer.ts   # Core player class
+│   └── StormcloudVideoPlayer.ts       # Core player class
 ├── ui/
-│   └── StormcloudVideoPlayer.tsx  # React component
+│   └── StormcloudVideoPlayer.tsx      # Legacy React component
 ├── sdk/
-│   └── ima.ts                     # Google IMA integration
+│   └── ima.ts                         # Google IMA integration
 ├── utils/
-│   └── tracking.ts                # Analytics and tracking
-└── types.ts                       # TypeScript definitions
+│   ├── tracking.ts                    # Analytics and tracking
+│   └── index.ts                       # Utility functions
+├── props.ts                           # Centralized props system
+├── patterns.ts                        # URL pattern matching
+└── types.ts                           # TypeScript definitions
+```
+
+### Export Structure
+
+```
+stormcloud-video-player/
+├── index.js                           # Main entry (auto-detection)
+├── hls.js                             # HLS-only entry
+├── file.js                            # File-only entry
+├── base.d.ts                          # Base type definitions
+├── hls.d.ts                           # HLS-specific types
+├── file.d.ts                          # File-specific types
+├── lib/                               # Compiled library
+├── dist/                              # UMD bundles
+└── scripts/                           # Build utilities
 ```
 
 ## 🎯 Use Cases
 
+### By Player Type
+
+#### HlsPlayer Use Cases
+
 - **Live Streaming**: Sports, news, and event broadcasts
+- **Live Shopping**: E-commerce live streams with ads
+- **FAST Channels**: Free ad-supported streaming TV
+- **Linear TV**: Traditional broadcast over IP
+- **Event Streaming**: Conferences, concerts, webinars
+
+#### FilePlayer Use Cases
+
 - **VOD Platforms**: Movie and series streaming services
 - **Educational Content**: E-learning and training platforms
-- **Corporate Communications**: Internal and external video content
+- **Corporate Communications**: Internal videos and presentations
 - **Digital Signage**: Retail and public display systems
+- **Social Media**: User-generated content playback
+
+### Migration Guide
+
+#### From Legacy Component
+
+```jsx
+// Old way (still works)
+import { StormcloudVideoPlayerComponent } from "stormcloud-video-player";
+
+<StormcloudVideoPlayerComponent
+  src="https://example.com/stream.m3u8"
+  autoplay={true}
+  // ... other props
+/>;
+
+// New way (recommended for new projects)
+import StormcloudPlayer from "stormcloud-video-player";
+
+<StormcloudPlayer
+  src="https://example.com/stream.m3u8"
+  playing={true} // Note: 'playing' instead of 'autoplay'
+  // ... other props
+/>;
+```
+
+#### Key Differences
+
+| Legacy Component         | New Component              | Notes                       |
+| ------------------------ | -------------------------- | --------------------------- |
+| `autoplay={true}`        | `playing={true}`           | More React-like prop naming |
+| Always loads full bundle | Supports optimized imports | Better performance          |
+| Single component         | Modular architecture       | More maintainable           |
+| Fixed UI structure       | Flexible wrapper system    | More customizable           |
 
 ## ⚠️ Known Limitations
 
@@ -317,6 +673,7 @@ src/
 - SCTE-35 binary splice parsing not yet implemented
 - Multi-ad pod competitive separation handled by ad server
 - Low-latency HLS (LL-HLS) optimizations in development
+- Picture-in-Picture only available in FilePlayer
 
 ## 🗺️ Roadmap
 
@@ -329,6 +686,7 @@ src/
 - **UI Themes**: Multiple control themes and color schemes
 - **Accessibility**: Enhanced ARIA support and keyboard navigation
 - **Error Recovery**: Advanced retry logic and failover handling
+- **More Players**: DASH, YouTube, Vimeo player implementations
 
 ### Performance Improvements
 
@@ -336,6 +694,7 @@ src/
 - Memory optimization for long-running sessions
 - Network bandwidth adaptation
 - Smart preloading strategies
+- Code splitting and lazy loading optimizations
 
 ## 🤝 Contributing
 
@@ -348,3 +707,14 @@ MIT License - see [LICENSE](LICENSE) file for details.
 ---
 
 Built with ❤️ by the Stormcloud team
+
+### What's New in v2.0
+
+- 🎯 **Professional Architecture**: Modular player system inspired by react-player
+- 🚀 **Automatic Format Detection**: Smart player selection based on video source
+- 📦 **Optimized Bundles**: Import only what you need (HLS-only, File-only, or Full)
+- 🔄 **Backward Compatibility**: Legacy component still works without changes
+- 🎨 **Enhanced Controls**: Improved UI with better accessibility and design
+- 📚 **Better TypeScript**: Comprehensive type definitions and IntelliSense
+- 🏗️ **Extensible**: Easy to add custom players for new formats
+- ⚡ **Performance**: Lazy loading and code splitting for faster load times