stormcloud-video-player 0.4.0 → 0.5.0

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 with comprehensive Smart TV support.
+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.
 
 ## 🎯 Key Features
 
@@ -11,11 +11,9 @@ 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
 
@@ -43,6 +41,7 @@ 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) => {
@@ -79,6 +78,7 @@ 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,11 +264,15 @@ interface StormcloudPlayerProps {
   immediateManifestAds?: boolean;
   debugAdTiming?: boolean;
   showCustomControls?: boolean;
-  hideLoadingIndicator?: boolean; // Hide the loading spinner/indicator
   licenseKey?: string;
   adFailsafeTimeoutMs?: number;
   minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
 
+  // 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)
+
   // Event handlers
   onReady?: (player: StormcloudVideoPlayer) => void;
   onStart?: () => void;
@@ -343,16 +347,18 @@ 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)
-  adBreakCheckIntervalMs?: number; // Interval for checking ad breaks (default: 1000)
-  maxAdBreakExtensionMs?: number; // Maximum ad break extension time (default: 5000)
+  minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
+
+  // 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)
 
   onVolumeToggle?: () => void; // Callback for volume toggle
   onFullscreenToggle?: () => void; // Callback for fullscreen toggle
@@ -413,69 +419,89 @@ All controls use a consistent high-contrast design:
 
 ## 🎬 Ad Integration (HLS Streams Only)
 
-### Ad Player Configuration
+### VAST Mode Configuration
 
-The player uses AdStorm backend with native ad player for optimal performance:
+The player supports two VAST modes that automatically configure the appropriate ad player:
+
+#### 1. **AdStorm Mode** (Recommended)
+
+Uses AdStorm backend with HLS 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 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
+- 🎯 Automatically uses HLS ad player (`adPlayerType: 'hls'`)
+- 🔗 VAST endpoint: `GET https://adstorm.co/api-adstorm-dev/adstorm/vast/{licenseKey}`
   - License key is passed in the URL path (no authorization header needed)
-  - Returns VAST XML with multiple ads to fill the duration (ad pod)
+  - Returns VAST XML directly with HLS media files
 - 📊 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 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
+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
 
 **Benefits:**
 - ✅ Zero external dependencies (no Google IMA SDK)
 - ✅ Full control over ad serving
-- ✅ Multi-format support (MP4, WebM, HLS)
-- ✅ Automatic quality matching to content stream
+- ✅ Native HLS playback (same format as content)
 - ✅ Better performance and reliability
 - ✅ Custom targeting and selection
 - ✅ Proper error handling (distinguishes parsing errors from "no ads available")
-- ✅ Ad pod support (multiple ads per break)
+
+#### 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 Generation (Multiple Consecutive Ads)
 
@@ -536,6 +562,8 @@ 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
 });
 ```
@@ -593,6 +621,27 @@ 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:
@@ -610,6 +659,85 @@ The HlsPlayer automatically detects and responds to SCTE-35 signals embedded in
 - `#EXT-X-DATERANGE`
 - ID3 timed metadata
 
+### Early Ad Prefetching & Preload Pool
+
+The player includes an advanced ad prefetching system that dramatically reduces ad start latency:
+
+#### Early SCTE-35 Detection
+
+The player scans up to 5 manifest fragments ahead of current playback to detect upcoming SCTE-35 ad markers. When an ad break is detected early:
+
+1. **Prefetching Begins**: The player immediately starts generating VAST URLs and prefetching ads
+2. **Preload Pool**: Up to 3 ads are preloaded and ready to play instantly
+3. **Zero-Delay Starts**: When the ad break actually begins, ads start immediately (no request delay)
+
+**Benefits:**
+- ⚡ **80% reduction** in ad start latency
+- 🎯 **Instant ad playback** when breaks begin
+- 📊 **Better fill rates** through proactive ad preparation
+- 🔄 **Seamless transitions** between content and ads
+
+#### How It Works
+
+```javascript
+const player = new StormcloudVideoPlayer({
+  videoElement: video,
+  src: "https://your-stream.com/playlist.m3u8",
+  licenseKey: "your-license-key",
+  debugAdTiming: true, // Enable to see prefetching logs
+});
+
+// The player automatically:
+// 1. Scans manifest fragments for SCTE-35 markers
+// 2. Detects upcoming ad breaks before playback reaches them
+// 3. Prefetches and preloads ads into a pool
+// 4. Starts ads instantly when breaks begin
+```
+
+**Debug Output Example:**
+```
+[PREFETCH] 🔄 Starting ad prefetch for upcoming ad break
+[PREFETCH] 📋 Pre-generated 5 VAST URLs
+[PRELOAD-POOL] 🏊 Starting preload pool EARLY (target size: 3)
+[PRELOAD-POOL] 📥 Preloading ad into pool: https://...
+[PRELOAD-POOL] ✅ Ad preloaded (pool size: 1/3)
+[CONTINUOUS-FETCH] 🚀 Using preloaded ad from pool (preloaded in advance, ready immediately!)
+```
+
+#### Continuous Ad Fetching
+
+During ad breaks, the player continuously fetches additional ads to fill the entire SCTE-35 duration:
+
+- **Dynamic Queue**: Maintains a queue of ready-to-play VAST URLs
+- **Smart Rate Limiting**: 2.5s minimum interval between requests with exponential backoff
+- **Automatic Filling**: Fetches ads until the SCTE-35 duration is fully filled
+- **Error Recovery**: Distinguishes temporary failures (no-fill) from permanent failures
+
+**Rate Limiting & Backoff:**
+- Base interval: 2.5 seconds between requests
+- Exponential backoff: Increases with consecutive failures
+- Max backoff: 15 seconds
+- Cooldown period: 30 seconds for temporary failures (no-fill)
+
+#### Error Handling & Recovery
+
+The player intelligently handles different types of ad failures:
+
+**Temporary Failures (Retryable):**
+- No-fill responses (no ads available)
+- Network timeouts
+- Rate limiting errors
+- **Action**: URL enters 30s cooldown, then can be retried
+
+**Permanent Failures (Blacklisted):**
+- VAST parsing errors
+- Malformed responses
+- **Action**: URL is permanently blacklisted for the current ad break
+
+**Fallback System:**
+- If a primary ad request fails, the player automatically tries a preloaded ad from the pool
+- Ensures continuous ad playback even when individual requests fail
+
 ### Late Join Behavior
 
 When viewers join during an ad break:
@@ -630,29 +758,6 @@ 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:
@@ -680,7 +785,7 @@ Example with error handling:
 ```javascript
 const player = new StormcloudVideoPlayer({
   // ... config
-  licenseKey: "your-license-key",
+  vastMode: 'adstorm',
   debugAdTiming: true, // Enable detailed logging
 });
 
@@ -704,11 +809,14 @@ const player = new StormcloudVideoPlayer({
 
 Authenticated requests are sent to:
 
-- **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
+- **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
 
-- **Player Tracking**:
+- **Player Tracking** (both modes):
   - 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)
 
@@ -747,6 +855,39 @@ StormcloudPlayer.addCustomPlayer({
 });
 ```
 
+### Buffering Configuration
+
+#### Min Segments Before Play
+
+Control how many segments must be buffered before playback starts. This helps ensure smooth playback, especially on slower connections:
+
+```javascript
+const player = new StormcloudVideoPlayer({
+  videoElement: video,
+  src: "https://your-stream.com/playlist.m3u8",
+  autoplay: true,
+  minSegmentsBeforePlay: 3, // Wait for 3 segments before starting (default: 2)
+});
+
+// Or with React component
+<StormcloudPlayer
+  src="https://your-stream.com/playlist.m3u8"
+  playing={true}
+  minSegmentsBeforePlay={3}
+/>
+```
+
+**Configuration Options:**
+- `minSegmentsBeforePlay: 0` - Start immediately (may cause stuttering on slow connections)
+- `minSegmentsBeforePlay: 2` - Default, good balance for most use cases
+- `minSegmentsBeforePlay: 3-5` - Recommended for slower connections or higher quality streams
+- `minSegmentsBeforePlay: undefined` - Uses default value (2)
+
+**When to Adjust:**
+- **Increase** for high-bitrate streams or unreliable networks
+- **Decrease** for low-latency requirements or fast connections
+- **Set to 0** only if you need immediate playback and can tolerate potential stuttering
+
 ### Player Detection
 
 ```javascript
@@ -790,70 +931,7 @@ 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**: 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.
+- **Smart TV**: WebOS, Tizen, Android TV, Roku, Apple TV
 
 ### Format Support by Player
 
@@ -906,12 +984,9 @@ src/
 ├── ui/
 │   └── StormcloudVideoPlayer.tsx      # Legacy React component
 ├── sdk/
-│   ├── adstormPlayer.ts               # Native ad player (MP4/WebM/HLS)
-│   └── hlsAdPlayer.ts                 # HLS-specific ad player
+│   └── ima.ts                         # Google IMA integration
 ├── 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
@@ -1027,26 +1102,40 @@ 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.4
+
+- 🚀 **Early Ad Prefetching**: Detects SCTE-35 markers in manifest fragments before playback reaches them, prefetching ads in advance for zero-delay ad starts
+- 🏊 **Ad Preload Pool**: Maintains a pool of preloaded, ready-to-play ads (up to 3 by default) for instant ad playback when breaks start
+- 🔄 **Continuous Ad Fetching**: Dynamically fetches additional ads during ad breaks to perfectly fill SCTE-35 durations, ensuring no wasted ad time
+- ⏱️ **Smart Rate Limiting**: Intelligent rate limiting (2.5s minimum interval) with exponential backoff to prevent ad server overload
+- 🛡️ **Advanced Error Handling**: Distinguishes between temporary failures (no-fill, timeouts) and permanent failures, with 30s cooldown periods for retryable errors
+- ⏳ **Min Segments Before Play**: New `minSegmentsBeforePlay` option (default: 2) to ensure smooth playback start by buffering multiple segments
+- 🎯 **Ad Request Watchdog**: Timeout system prevents hanging ad requests and automatically recovers from stuck states
+- ⬛ **Placeholder System**: Seamless placeholder layer shown during ad transitions, preventing content flash between ads
+- 📊 **Improved Queue Management**: Better handling of ad request queues with automatic cleanup and failure tracking
+- 🔍 **Early SCTE-35 Detection**: Scans up to 5 manifest fragments ahead to detect upcoming ad breaks, enabling proactive ad preparation
+- ⚡ **Zero-Delay Ad Starts**: Preloaded ads start instantly when ad breaks begin, eliminating the traditional ad request delay
+- 🎬 **Fallback Ad System**: Automatic fallback to preloaded ads when primary ad requests fail, ensuring continuous ad playback
+
+**Performance Improvements:**
+- Reduced ad start latency by up to 80% through prefetching and preloading
+- Better resource utilization with intelligent ad pool management
+- Improved reliability with comprehensive error recovery mechanisms
+- Enhanced user experience with seamless ad transitions
 
 ### What's New in v0.3
 
 - 🎬 **Custom HLS Ad Player**: Native HLS ad playback with custom VAST service
-- 🎯 **Flexible Ad Integration**: Native ad player with AdStorm VAST endpoint
+- 🎯 **Flexible Ad Integration**: Choose between custom HLS or Google IMA SDK
 - 📊 **Direct Analytics**: Full control over ad tracking and metrics
 - ⚡ **Better Performance**: Native HLS playback for ads (same format as content)
-- 📦 **Zero Dependencies**: No external ad SDKs required
+- 🔧 **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)
 - 🎨 **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