stormcloud-video-player 0.3.17 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # Stormcloud Video Player
 
-A professional video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, custom VAST ad serving, and optional Google IMA SDK integration for seamless ad playback. Now featuring a modern, extensible architecture inspired by react-player.
+A professional video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, custom VAST ad serving, and optional Google IMA SDK integration for seamless ad playback. Now featuring a modern, extensible architecture inspired by react-player with comprehensive Smart TV support.
 
 ## 🎯 Key Features
 
@@ -11,9 +11,11 @@ A professional video player with advanced ad integration for web applications. B
 - **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
+- **Smart TV Optimized**: Native support for LG WebOS, Samsung Tizen, Sony BRAVIA, and other CTV platforms
 - **React Ready**: Multiple React components for different use cases
 - **TypeScript Support**: Full type definitions included
 - **Professional Architecture**: Modular player system with lazy loading
+- **Built-in Polyfills**: Automatic compatibility for older browsers and legacy TV platforms
 
 ## 🚀 Quick Start
 
@@ -41,7 +43,6 @@ function MyVideoApp() {
       showCustomControls={true} // Enable enhanced UI controls
       allowNativeHls={true} // Allow native HLS for better performance
       licenseKey="your_license_key_here"
-      vastMode="adstorm" // Use AdStorm mode with HLS ad player
       style={{ width: "100%", aspectRatio: "16/9" }}
       wrapperStyle={{ borderRadius: "12px", overflow: "hidden" }}
       onReady={(player) => {
@@ -78,7 +79,6 @@ function MyVideoApp() {
       allowNativeHls={true}
       showCustomControls={true}
       licenseKey="your_license_key_here"
-      vastMode="adstorm" // Use AdStorm mode (or omit for default mode)
       onReady={(player) => {
         console.log("Player is ready!", player);
       }}
@@ -264,13 +264,10 @@ interface StormcloudPlayerProps {
   immediateManifestAds?: boolean;
   debugAdTiming?: boolean;
   showCustomControls?: boolean;
+  hideLoadingIndicator?: boolean; // Hide the loading spinner/indicator
   licenseKey?: string;
   adFailsafeTimeoutMs?: number;
-
-  // Ad player configuration
-  vastMode?: 'adstorm' | 'default'; // VAST mode: 'adstorm' (HLS player + AdStorm VAST endpoint) or 'default' (IMA SDK + /ads/web endpoint) (default: 'default')
-  vastTagUrl?: string; // Custom VAST URL (used in default mode if provided; when not provided, uses /ads/web endpoint)
-  adPlayerType?: 'ima' | 'hls'; // Manual override for ad player type (auto-determined by vastMode if not specified)
+  minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
 
   // Event handlers
   onReady?: (player: StormcloudVideoPlayer) => void;
@@ -346,17 +343,16 @@ interface StormcloudVideoPlayerConfig {
   muted?: boolean; // Start muted (default: false)
   allowNativeHls?: boolean; // Use native HLS when available (default: false)
   showCustomControls?: boolean; // Enable enhanced UI controls (default: false)
+  hideLoadingIndicator?: boolean; // Hide the loading spinner/indicator (default: false)
   lowLatencyMode?: boolean; // Enable low-latency mode for live streams (default: false)
   driftToleranceMs?: number; // Drift tolerance for live streams (default: 1000)
   immediateManifestAds?: boolean; // Load ads immediately from manifest (default: true)
+  minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
   licenseKey?: string; // API authentication key
   debugAdTiming?: boolean; // Enable debug logging (default: false)
   adFailsafeTimeoutMs?: number; // Ad timeout in milliseconds (default: 10000)
-
-  // Ad configuration
-  vastMode?: 'adstorm' | 'default'; // VAST mode: 'adstorm' (uses HLS player + AdStorm VAST endpoint) or 'default' (uses Google IMA SDK + /ads/web endpoint) (default: 'default')
-  vastTagUrl?: string; // Custom VAST tag URL (used in default mode if provided; when not provided, defaults to /ads/web endpoint)
-  adPlayerType?: 'ima' | 'hls'; // Manual override for ad player type (auto-determined by vastMode if not specified)
+  adBreakCheckIntervalMs?: number; // Interval for checking ad breaks (default: 1000)
+  maxAdBreakExtensionMs?: number; // Maximum ad break extension time (default: 5000)
 
   onVolumeToggle?: () => void; // Callback for volume toggle
   onFullscreenToggle?: () => void; // Callback for fullscreen toggle
@@ -417,89 +413,69 @@ All controls use a consistent high-contrast design:
 
 ## 🎬 Ad Integration (HLS Streams Only)
 
-### VAST Mode Configuration
-
-The player supports two VAST modes that automatically configure the appropriate ad player:
+### Ad Player Configuration
 
-#### 1. **AdStorm Mode** (Recommended)
-
-Uses AdStorm backend with HLS ad player for optimal performance:
+The player uses AdStorm backend with native ad player for optimal performance:
 
 ```javascript
 const player = new StormcloudVideoPlayer({
   videoElement: video,
   src: "https://your-stream.com/playlist.m3u8",
   licenseKey: "your-license-key",
-
-  // AdStorm mode - uses HLS ad player automatically
-  vastMode: 'adstorm',
-
   debugAdTiming: true,
 });
 ```
 
 **What happens:**
-- 🎯 Automatically uses HLS ad player (`adPlayerType: 'hls'`)
-- 🔗 VAST endpoint: `GET https://adstorm.co/api-adstorm-dev/adstorm/vast/{licenseKey}`
+- 🎯 Automatically uses native ad player with MP4/WebM/HLS support
+- 🔗 VAST Pod endpoint: `GET https://adstorm.co/api-adstorm-dev/adstorm/vast/{licenseKey}/pod`
+  - Query parameters:
+    - `duration` - Target ad break duration in seconds
+    - `metadata` - JSON-encoded video/audio metadata for quality matching
   - License key is passed in the URL path (no authorization header needed)
-  - Returns VAST XML directly with HLS media files
+  - Returns VAST XML with multiple ads to fill the duration (ad pod)
 - 📊 Direct tracking and analytics through AdStorm backend
 - ⚠️ Gracefully handles "no ads available" scenarios (logs warnings, not errors)
 
+**Pod Ad API Request:**
+```
+GET /vast/{licenseKey}/pod?duration=60&metadata={"video":{"codec":"h264","width":1920,"height":1080},"audio":{"codec":"aac"}}
+```
+
+**Metadata Structure:**
+```typescript
+interface AdStormMetadata {
+  video?: {
+    codec?: string;    // e.g., "h264"
+    width?: number;    // e.g., 1920
+    height?: number;   // e.g., 1080
+    fps?: number;      // e.g., 29.97
+    bitrate?: number;  // e.g., 5000 (kbps)
+    profile?: string;  // e.g., "high"
+  };
+  audio?: {
+    codec?: string;       // e.g., "aac"
+    sample_rate?: number; // e.g., 48000
+    bitrate?: number;     // e.g., 128 (kbps)
+  };
+}
+```
+
 **API Flow:**
-1. Player calls `/vast/{licenseKey}` endpoint
-2. Backend returns VAST XML with HLS media files
-3. Player parses VAST XML and extracts MediaFile URLs
-4. HLS ad player loads and plays the ad segments
+1. Player detects SCTE-35 marker with ad break duration
+2. Calls `/vast/{licenseKey}/pod?duration={seconds}&metadata={...}` endpoint
+3. Backend returns VAST XML with ad pod (multiple ads matching requested duration)
+4. Native ad player loads and plays ads with quality matching content stream
 
 **Benefits:**
 - ✅ Zero external dependencies (no Google IMA SDK)
 - ✅ Full control over ad serving
-- ✅ Native HLS playback (same format as content)
+- ✅ Multi-format support (MP4, WebM, HLS)
+- ✅ Automatic quality matching to content stream
 - ✅ Better performance and reliability
 - ✅ Custom targeting and selection
 - ✅ Proper error handling (distinguishes parsing errors from "no ads available")
-
-#### 2. **Default Mode**
-
-Uses Google IMA SDK for traditional ad serving:
-
-```javascript
-const player = new StormcloudVideoPlayer({
-  videoElement: video,
-  src: "https://your-stream.com/playlist.m3u8",
-  licenseKey: "your-license-key",
-
-  // Default mode - uses Google IMA SDK automatically
-  vastMode: 'default', // or omit this property entirely
-  vastTagUrl: 'https://your-vast-server.com/vast.xml', // optional
-
-  debugAdTiming: true,
-});
-```
-
-**What happens:**
-- 🎯 Automatically uses Google IMA SDK (`adPlayerType: 'ima'`)
-- 🔗 VAST endpoint resolution:
-  1. If `vastTagUrl` is provided, uses that URL directly
-  2. Otherwise, calls `GET https://adstorm.co/api-adstorm-dev/adstorm/ads/web`
-     - Requires `Authorization: Bearer {licenseKey}` header
-     - Returns JSON response with IMA payload: `{ response: { ima: { "publisherdesk.ima": { payload: "VAST_URL" } } } }`
-     - Extracts VAST tag URL from the `payload` field
-- 📊 Standard VAST/VPAID ad serving through Google IMA SDK
-
-**API Flow:**
-1. Player calls `/ads/web` endpoint with Bearer token (if no `vastTagUrl` provided)
-2. Backend returns JSON with IMA configuration
-3. Player extracts VAST tag URL from `response.ima["publisherdesk.ima"].payload`
-4. Google IMA SDK loads and plays the VAST ad
-
-**Benefits:**
-- ✅ Industry-standard ad serving
-- ✅ Wide format support (VAST, VPAID)
-- ✅ Established ecosystem
-- ✅ Backward compatible with existing VAST tags
-- ✅ Supports both custom VAST URLs and AdStorm backend
+- ✅ Ad pod support (multiple ads per break)
 
 ### Ad Pod Generation (Multiple Consecutive Ads)
 
@@ -560,8 +536,6 @@ const player = new StormcloudVideoPlayer({
   videoElement: video,
   src: "https://your-live-stream.com/playlist.m3u8",
   licenseKey: "your-license-key",
-  
-  vastMode: 'default',
   debugAdTiming: true, // Enable to see adaptive calculations
 });
 ```
@@ -619,27 +593,6 @@ Final: 3 ads played (perfectly fills 120 seconds)
 - ✅ **Smart**: Improves calculation as more data is gathered (uses average of fetched durations)
 - ✅ **Self-Correcting**: Automatically adjusts if actual ad lengths differ from expectations
 
-### Manual Ad Player Override
-
-You can still manually override the ad player type if needed:
-
-```javascript
-const player = new StormcloudVideoPlayer({
-  videoElement: video,
-  src: "https://your-stream.com/playlist.m3u8",
-
-  vastMode: 'default',
-  adPlayerType: 'hls', // Manual override to use HLS player with default mode
-  vastTagUrl: 'https://your-backend.com/vast', // Will use this URL directly
-
-  debugAdTiming: true,
-});
-```
-
-**Note:** When `adPlayerType` is manually set, the `vastMode` property still determines which backend endpoint is called:
-- `vastMode: 'adstorm'` → Always calls `/vast/{licenseKey}` endpoint
-- `vastMode: 'default'` → Calls `/ads/web` endpoint (unless `vastTagUrl` is provided)
-
 ### SCTE-35 Support
 
 The HlsPlayer automatically detects and responds to SCTE-35 signals embedded in HLS streams:
@@ -677,6 +630,29 @@ When viewers join during an ad break:
 />
 ```
 
+### VAST Tracking Events
+
+The native ad player automatically fires VAST tracking pixels for the following events:
+
+| Event | When Fired |
+|-------|------------|
+| `impression` | When ad is loaded and ready to play |
+| `start` | When ad begins playing |
+| `firstQuartile` | When 25% of ad has played |
+| `midpoint` | When 50% of ad has played |
+| `thirdQuartile` | When 75% of ad has played |
+| `complete` | When ad finishes playing |
+| `mute` | When ad is muted |
+| `unmute` | When ad is unmuted |
+| `pause` | When ad is paused |
+| `resume` | When ad resumes after pause |
+| `fullscreen` | When entering fullscreen |
+| `exitFullscreen` | When exiting fullscreen |
+| `skip` | When ad is skipped |
+| `error` | When an error occurs |
+
+Tracking pixels include session ID and license key for analytics correlation.
+
 ### Error Handling
 
 The player distinguishes between different types of ad-related issues:
@@ -704,7 +680,7 @@ Example with error handling:
 ```javascript
 const player = new StormcloudVideoPlayer({
   // ... config
-  vastMode: 'adstorm',
+  licenseKey: "your-license-key",
   debugAdTiming: true, // Enable detailed logging
 });
 
@@ -728,14 +704,11 @@ const player = new StormcloudVideoPlayer({
 
 Authenticated requests are sent to:
 
-- **AdStorm Mode** (`vastMode: 'adstorm'`):
-  - VAST endpoint: `GET https://adstorm.co/api-adstorm-dev/adstorm/vast/{licenseKey}` (license key in URL path)
-  
-- **Default Mode** (`vastMode: 'default'`):
-  - Ad configuration: `GET https://adstorm.co/api-adstorm-dev/adstorm/ads/web` (requires `Authorization: Bearer {licenseKey}` header)
-  - Returns JSON with IMA payload containing VAST tag URL
+- **VAST Pod endpoint**: `GET https://adstorm.co/api-adstorm-dev/adstorm/vast/{licenseKey}/pod` (license key in URL path)
+  - Query parameters: `duration`, `metadata`
+  - Returns VAST XML with ad pod for requested duration
 
-- **Player Tracking** (both modes):
+- **Player Tracking**:
   - Player tracking: `POST https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/track` (requires `Authorization: Bearer {licenseKey}` header)
   - Heartbeat monitoring: `POST https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/heartbeat` (requires `Authorization: Bearer {licenseKey}` header)
 
@@ -817,7 +790,70 @@ console.log("Supports PIP:", canPIP); // true for file player
 
 - **Desktop**: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
 - **Mobile**: iOS Safari 12+, Chrome Mobile 60+
-- **Smart TV**: WebOS, Tizen, Android TV, Roku, Apple TV
+- **Smart TV**: LG WebOS, Samsung Tizen, Sony BRAVIA, Android TV, Roku, Apple TV, Fire TV
+
+### Smart TV & CTV Platform Support
+
+The player includes comprehensive Smart TV detection and automatic configuration:
+
+#### Supported Platforms
+
+| Platform | Detection | Auto-Config | Notes |
+|----------|-----------|-------------|-------|
+| LG WebOS | ✅ | ✅ | Auto-enables native HLS |
+| Samsung Tizen | ✅ | ✅ | Auto-enables native HLS |
+| Sony BRAVIA | ✅ | ✅ | Auto-enables native HLS |
+| LG NetCast | ✅ | ✅ | Legacy mode enabled |
+| Android TV | ✅ | ✅ | Standard HLS.js mode |
+| Roku | ✅ | ✅ | Native HLS recommended |
+| Apple TV | ✅ | ✅ | Native HLS |
+| Fire TV | ✅ | ✅ | Standard HLS.js mode |
+
+#### Automatic Configuration
+
+When a Smart TV is detected, the player automatically:
+
+1. **Enables native HLS** for better performance on TV browsers
+2. **Applies legacy compatibility** for older TV platforms
+3. **Logs browser info** when debug mode is enabled
+
+```javascript
+// Browser info logged in debug mode
+{
+  browser: "Samsung Tizen 6.0",
+  platform: "Linux",
+  isSmartTV: true,
+  isLegacyTV: false,
+  supportsModernJS: true,
+  userAgent: "..."
+}
+```
+
+#### Manual Override
+
+You can override automatic detection if needed:
+
+```javascript
+const player = new StormcloudVideoPlayer({
+  videoElement: video,
+  src: "https://stream.example.com/playlist.m3u8",
+  allowNativeHls: false, // Force HLS.js even on Smart TVs
+  debugAdTiming: true,   // Log browser detection info
+});
+```
+
+### Built-in Polyfills
+
+The player automatically loads polyfills for older browsers and legacy TV platforms:
+
+- **URLSearchParams** - For query string parsing
+- **TextEncoder** - For UTF-8 encoding
+- **Promise.finally** - For promise cleanup
+- **Object.assign** - For object merging
+- **Array.from** - For array-like iteration
+- **String.startsWith/endsWith/includes** - For string operations
+
+These polyfills are only loaded when needed and have minimal impact on modern browsers.
 
 ### Format Support by Player
 
@@ -870,9 +906,12 @@ src/
 ├── ui/
 │   └── StormcloudVideoPlayer.tsx      # Legacy React component
 ├── sdk/
-│   └── ima.ts                         # Google IMA integration
+│   ├── adstormPlayer.ts               # Native ad player (MP4/WebM/HLS)
+│   └── hlsAdPlayer.ts                 # HLS-specific ad player
 ├── utils/
 │   ├── tracking.ts                    # Analytics and tracking
+│   ├── browserCompat.ts               # Smart TV & browser detection
+│   ├── polyfills.ts                   # Legacy browser polyfills
 │   └── index.ts                       # Utility functions
 ├── props.ts                           # Centralized props system
 ├── patterns.ts                        # URL pattern matching
@@ -988,19 +1027,26 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 Built with ❤️ by the Stormcloud team
 
+### What's New in v0.3.17
+
+- 📺 **Smart TV Support**: Comprehensive detection for LG WebOS, Samsung Tizen, Sony BRAVIA, and more
+- 🔧 **Automatic Configuration**: Smart TVs automatically use native HLS for better performance
+- 🛡️ **Built-in Polyfills**: URLSearchParams, TextEncoder, Promise.finally, and more for legacy platforms
+- 📊 **Browser Detection API**: Detailed browser info logging in debug mode
+- ⚡ **Buffering Control**: New `minSegmentsBeforePlay` option to control initial buffering (default: 2 segments)
+- 🎛️ **UI Enhancements**: New `hideLoadingIndicator` option to hide loading spinners
+- 🎬 **Native Ad Player**: Multi-format ad playback (MP4, WebM, HLS) with quality matching
+- 📦 **Pod Ad API**: New `/vast/{licenseKey}/pod` endpoint for ad pod generation with metadata
+- 🎯 **Quality Matching**: Automatic ad quality selection based on content stream parameters
+
 ### What's New in v0.3
 
 - 🎬 **Custom HLS Ad Player**: Native HLS ad playback with custom VAST service
-- 🎯 **Flexible Ad Integration**: Choose between custom HLS or Google IMA SDK
+- 🎯 **Flexible Ad Integration**: Native ad player with AdStorm VAST endpoint
 - 📊 **Direct Analytics**: Full control over ad tracking and metrics
 - ⚡ **Better Performance**: Native HLS playback for ads (same format as content)
-- 🔧 **Custom VAST URLs**: Point to your own ad serving backend
-- 🔄 **Backward Compatible**: Existing Google IMA integration still works
-- 📦 **Zero Dependencies**: No external ad SDKs required (when using HLS ad player)
+- 📦 **Zero Dependencies**: No external ad SDKs required
 - 🎨 **Seamless Playback**: Same player for content and ads
-- 🔀 **VAST Mode System**: `vastMode` property automatically configures endpoints and ad players
-  - `vastMode: 'adstorm'` → Uses `/vast/{licenseKey}` endpoint with HLS ad player
-  - `vastMode: 'default'` → Uses `/ads/web` endpoint with Google IMA SDK
 - ⚠️ **Improved Error Handling**: Distinguishes between parsing errors and "no ads available" scenarios
   - Logs warnings for "no ads available" (graceful handling)
   - Logs errors for actual parsing/fetch failures