stormcloud-video-player 0.2.11 → 0.2.13

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, and Google IMA SDK integration for seamless VAST/VPAID 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.
 
 ## 🎯 Key Features
 
@@ -265,6 +265,10 @@ interface StormcloudPlayerProps {
   licenseKey?: string;
   adFailsafeTimeoutMs?: number;
 
+  // Ad player configuration
+  adPlayerType?: 'ima' | 'hls'; // Choose ad player (default: 'ima')
+  vastTagUrl?: string; // Custom VAST URL for HLS ad player
+
   // Event handlers
   onReady?: (player: StormcloudVideoPlayer) => void;
   onStart?: () => void;
@@ -345,6 +349,12 @@ interface StormcloudVideoPlayerConfig {
   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 backend) or 'default' (uses Google IMA SDK) (default: 'default')
+  vastTagUrl?: string; // Custom VAST tag URL (used in default mode if provided)
+  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
   onControlClick?: () => void; // Callback for control area clicks
@@ -404,6 +414,84 @@ 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:
+
+#### 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 HLS ad player (`adPlayerType: 'hls'`)
+- 🔗 VAST endpoint: `https://adstorm.co/api-adstorm-dev/adstorm/vast/${licenseKey}`
+- 📊 Direct tracking and analytics through AdStorm backend
+
+**Benefits:**
+- ✅ Zero external dependencies (no Google IMA SDK)
+- ✅ Full control over ad serving
+- ✅ Native HLS playback (same format as content)
+- ✅ Better performance and reliability
+- ✅ Custom targeting and selection
+
+#### 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",
+
+  // 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: Uses `vastTagUrl` if provided, otherwise `https://adstorm.co/api-adstorm-dev/adstorm/ads/web`
+- 📊 Standard VAST/VPAID ad serving
+
+**Benefits:**
+- ✅ Industry-standard ad serving
+- ✅ Wide format support (VAST, VPAID)
+- ✅ Established ecosystem
+- ✅ Backward compatible with existing VAST tags
+
+### 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',
+
+  debugAdTiming: true,
+});
+```
+
 ### SCTE-35 Support
 
 The HlsPlayer automatically detects and responds to SCTE-35 signals embedded in HLS streams:
@@ -707,6 +795,17 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 Built with ❤️ by the Stormcloud team
 
+### 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
+- 📊 **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)
+- 🎨 **Seamless Playback**: Same player for content and ads
+
 ### What's New in v0.2
 
 - 🎯 **Professional Architecture**: Modular player system inspired by react-player