stormcloud-video-player 0.8.18 → 0.8.19

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, VMAP ad-break scheduling, 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, VMAP ad-break scheduling, and a native HLS ad player for VAST-based ad playback. Now featuring a modern, extensible architecture inspired by react-player.
 
 ## 🎯 Key Features
 
@@ -12,7 +12,7 @@ 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 & Smart TV Ready**: Desktop, mobile, tablets, LG WebOS, Samsung Tizen, Sony BRAVIA, Android TV, Roku, Apple TV
-- **Automatic Browser Compatibility**: Built-in browser detection, polyfills, and automatic ad-player selection for legacy Smart TVs
+- **Automatic Browser Compatibility**: Built-in browser detection, polyfills, and Smart TV playback overrides (e.g. native HLS)
 - **React Ready**: Multiple React components for different use cases
 - **TypeScript Support**: Full type definitions included
 - **Professional Architecture**: Modular player system with lazy loading
@@ -44,7 +44,8 @@ function MyVideoApp() {
       hideLoadingIndicator={false} // Hide the built-in loading spinner
       allowNativeHls={true} // Allow native HLS for better performance
       licenseKey="your_license_key_here"
-      vastMode="adstorm" // Use AdStorm mode with HLS ad player
+      vastMode="adstorm" // AdStorm VAST endpoint resolution
+      isVmap={true}
       vmapUrl="https://your-cdn.com/ads.vmap" // Optional VMAP manifest for scheduled breaks
       style={{ width: "100%", aspectRatio: "16/9" }}
       wrapperStyle={{ borderRadius: "12px", overflow: "hidden" }}
@@ -174,7 +175,7 @@ StormcloudPlayer (Main Component)
 - **Purpose**: Handles HLS (.m3u8) streams with advanced features
 - **Features**:
   - SCTE-35 ad marker detection and processing
-  - Google IMA SDK integration for VAST/VPAID ads
+  - HLS ad player with VAST XML parsing (HLS and progressive media files)
   - Live stream support with low-latency mode
   - Drift correction for live timing
   - Manifest-based and ID3 ad markers
@@ -279,10 +280,10 @@ interface StormcloudPlayerProps {
   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)
-  vmapUrl?: string; // Optional VMAP 1.0 manifest URL used to schedule pre/mid/post-roll ad breaks
-  adPlayerType?: 'ima' | 'hls'; // Manual override for ad player type (auto-determined by vastMode if not specified)
+  vastMode?: 'adstorm' | 'default'; // VAST endpoint resolution: 'adstorm' (/vast/{licenseKey}) or 'default' (/ads/web or vastTagUrl) (default: 'default')
+  vastTagUrl?: string; // Custom VAST tag URL (default mode; when omitted, /ads/web supplies the tag URL)
+  isVmap?: boolean; // Enable VMAP manifest scheduling (requires vmapUrl)
+  vmapUrl?: string; // VMAP 1.0 manifest URL for pre/mid/post-roll ad breaks (requires isVmap: true)
 
   // Event handlers
   onReady?: (player: StormcloudVideoPlayer) => void;
@@ -372,10 +373,12 @@ interface StormcloudVideoPlayerConfig {
   maxAdBreakExtensionMs?: number; // Max time an ad break may be extended past its SCTE-35 duration when ads are still playing/queued (default: 60000)
 
   // 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)
-  vmapUrl?: string; // Optional VMAP 1.0 manifest URL used to schedule pre/mid/post-roll ad breaks
-  adPlayerType?: 'ima' | 'hls'; // Manual override for ad player type (auto-determined by vastMode/browser if not specified)
+  vastMode?: 'adstorm' | 'default'; // VAST endpoint resolution: 'adstorm' (/vast/{licenseKey}) or 'default' (/ads/web or vastTagUrl) (default: 'default')
+  vastTagUrl?: string; // Custom VAST tag URL (default mode; when omitted, /ads/web supplies the tag URL)
+  isVmap?: boolean; // Enable VMAP manifest scheduling (requires vmapUrl)
+  vmapUrl?: string; // VMAP 1.0 manifest URL (requires isVmap: true)
+  ctvAdRequest?: boolean; // Include CTV device signals in VAST macro substitution
+  adTest?: boolean; // Enable test ad mode in VAST requests
 
   onVolumeToggle?: () => void; // Callback for volume toggle
   onFullscreenToggle?: () => void; // Callback for fullscreen toggle
@@ -438,11 +441,11 @@ All controls use a consistent high-contrast design:
 
 ### VAST Mode Configuration
 
-The player supports two VAST modes that automatically configure the appropriate ad player:
+The player always uses the **HLS ad player** to fetch VAST XML and play ad media (HLS or progressive). The `vastMode` option only controls **which endpoint supplies the VAST tag URL**:
 
 #### 1. **AdStorm Mode** (Recommended)
 
-Uses AdStorm backend with HLS ad player for optimal performance:
+Uses the AdStorm `/vast/{licenseKey}` endpoint, which returns VAST XML directly:
 
 ```javascript
 const player = new StormcloudVideoPlayer({
@@ -450,7 +453,6 @@ const player = new StormcloudVideoPlayer({
   src: "https://your-stream.com/playlist.m3u8",
   licenseKey: "your-license-key",
 
-  // AdStorm mode - uses HLS ad player automatically
   vastMode: 'adstorm',
 
   debugAdTiming: true,
@@ -458,7 +460,6 @@ const player = new StormcloudVideoPlayer({
 ```
 
 **What happens:**
-- 🎯 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 directly with HLS media files
@@ -468,20 +469,20 @@ const player = new StormcloudVideoPlayer({
 **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
+3. HLS ad player parses VAST XML and extracts MediaFile URLs
+4. Ad segments are loaded and played
 
 **Benefits:**
-- ✅ Zero external dependencies (no Google IMA SDK)
+- ✅ Zero external ad SDK dependencies
 - ✅ Full control over ad serving
 - ✅ Native HLS playback (same format as content)
-- ✅ Better performance and reliability
+- ✅ Better performance and reliability on Smart TVs
 - ✅ 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:
+Uses the AdStorm `/ads/web` API (or a custom `vastTagUrl`) to obtain a VAST tag URL, then plays ads through the same HLS ad player:
 
 ```javascript
 const player = new StormcloudVideoPlayer({
@@ -489,7 +490,6 @@ const player = new StormcloudVideoPlayer({
   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
 
@@ -498,27 +498,24 @@ const player = new StormcloudVideoPlayer({
 ```
 
 **What happens:**
-- 🎯 Automatically uses Google IMA SDK (`adPlayerType: 'ima'`)
-- 🔗 VAST endpoint resolution:
+- 🔗 VAST tag URL 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
+     - Returns JSON with a VAST tag URL in `response.ima["publisherdesk.ima"].payload`
+- 📊 HLS ad player fetches VAST XML from the resolved tag URL and plays returned media files
 
 **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
+1. Player calls `/ads/web` with Bearer token (if no `vastTagUrl` provided)
+2. Backend returns JSON with a VAST tag URL in `response.ima["publisherdesk.ima"].payload`
+3. HLS ad player requests VAST XML from that URL
+4. Ad media is parsed from VAST and played
 
 **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
+- ✅ Industry-standard VAST tag URLs (e.g. Google Ad Manager)
+- ✅ Backward compatible with existing AdStorm `/ads/web` integrations
+- ✅ Supports both custom VAST URLs and AdStorm backend configuration
+- ✅ Same HLS ad player stack as AdStorm mode
 
 ### Ad Pod Generation (Multiple Consecutive Ads)
 
@@ -644,7 +641,7 @@ In addition to SCTE-35 markers and continuous-ad-fetch, the player supports **VM
 
 #### Usage
 
-Provide a `vmapUrl` in addition to (or instead of) a VAST/AdStorm configuration:
+Provide `isVmap: true` and a `vmapUrl` in addition to (or instead of) a VAST/AdStorm configuration:
 
 ```javascript
 const player = new StormcloudVideoPlayer({
@@ -653,6 +650,7 @@ const player = new StormcloudVideoPlayer({
   licenseKey: "your-license-key",
 
   vastMode: 'default',
+  isVmap: true,
   vmapUrl: 'https://your-cdn.com/schedule.vmap', // VMAP 1.0 manifest
 
   debugAdTiming: true,
@@ -665,6 +663,7 @@ Or with React:
 <StormcloudPlayer
   src="https://your-stream.com/video.m3u8"
   licenseKey="your-license-key"
+  isVmap={true}
   vmapUrl="https://your-cdn.com/schedule.vmap"
   playing={true}
 />
@@ -726,26 +725,18 @@ The VMAP parser recognizes all standard `timeOffset` values:
 - ✅ Supports pre-roll, mid-roll, percentage-based, and post-roll breaks
 - ✅ Gracefully handles malformed XML and fetch failures (logged when `debugAdTiming` is enabled)
 
-### Manual Ad Player Override
+### Ad Player Architecture
 
-You can still manually override the ad player type if needed:
+All ads are played through the built-in **HLS ad player** (`createHlsAdPlayer`).
 
-```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,
-});
-```
+The player:
+1. Resolves a VAST tag URL (`vastMode`, `vastTagUrl`, VMAP, or `/ads/web`)
+2. Fetches and parses VAST XML (including wrapper chains)
+3. Plays HLS or progressive `MediaFile` URLs from the VAST response
 
-**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)
+`vastMode` only changes how the initial VAST tag URL is obtained:
+- `vastMode: 'adstorm'` → `/vast/{licenseKey}` returns VAST XML directly (used as the tag URL for pod generation)
+- `vastMode: 'default'` → `/ads/web` or `vastTagUrl` supplies the tag URL; the HLS ad player fetches VAST from that URL
 
 ### SCTE-35 Support
 
@@ -919,7 +910,7 @@ Authenticated requests are sent to:
   
 - **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
+  - Returns JSON with a VAST tag URL in `response.ima["publisherdesk.ima"].payload`
 
 - **Player Tracking** (both modes):
   - Player tracking: `POST https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/track` (requires `Authorization: Bearer {licenseKey}` header)
@@ -957,14 +948,14 @@ await sendAdDetectTracking(licenseKey, {
 });
 
 await sendAdLoadedTracking(licenseKey, {
-  source: "ima", // 'prebid' | 'ima' | 'hls'
+  source: "hls", // 'vast' | 'hls' (ad playback path)
   vastUrl: "https://...",
   durationSeconds: 15,
   timestamp: new Date().toISOString(),
 });
 
 await sendAdImpressionTracking(licenseKey, {
-  source: "ima",
+  source: "hls",
   adIndex: 0,
   durationSeconds: 15,
   timestamp: new Date().toISOString(),
@@ -1084,15 +1075,13 @@ console.log("Supports PIP:", canPIP); // true for file player
 - **Mobile**: iOS Safari 12+, Chrome Mobile 60+
 - **Smart TV**: LG WebOS (v2+), Samsung Tizen (v2+), Sony BRAVIA, Android TV, Roku, Apple TV, generic Smart TV user-agents
 
-### Automatic Browser Detection & Ad Player Selection
+### Automatic Browser Detection & Smart TV Overrides
 
-The player automatically detects the runtime environment and chooses the optimal ad-player configuration. This is especially useful for Smart TVs where the Google IMA SDK may not be available on older devices.
+The player detects the runtime environment and applies Smart TV-friendly defaults via `getBrowserConfigOverrides()`.
 
 ```javascript
 import {
   detectBrowser,
-  supportsGoogleIMA,
-  getRecommendedAdPlayer,
   supportsModernJS,
   logBrowserInfo,
   getBrowserConfigOverrides,
@@ -1106,25 +1095,22 @@ const info = detectBrowser();
 //   majorVersion: 5,
 //   isSmartTV: true,
 //   isLegacyTV: false,
-//   supportsIMA: true,
 //   supportsModernJS: true,
-//   recommendedAdPlayer: 'ima',
 //   webOSVersion: 5,
 //   chromeVersion: 79,
 //   ...
 // }
 
-console.log(supportsGoogleIMA());   // true | false
-console.log(getRecommendedAdPlayer()); // 'ima' | 'hls'
+console.log(supportsModernJS()); // true | false
 console.log(supportsFeature('fetch')); // true | false
+console.log(getBrowserConfigOverrides()); // e.g. { allowNativeHls: true } on Smart TVs
 ```
 
 **What happens automatically:**
 
-- **Legacy Smart TVs** (LG NetCast, old WebOS < 3, old Tizen): `adPlayerType` is forced to `'hls'` and `allowNativeHls` is enabled.
-- **Modern Smart TVs**: `allowNativeHls` is enabled by default (TVs generally play HLS better natively).
-- **If IMA SDK is unsupported**: the player falls back to the HLS ad player automatically.
+- **Smart TVs** (LG WebOS, Samsung Tizen, etc.): `allowNativeHls` is enabled by default (TVs generally play HLS better natively).
 - **Browser overrides** are merged with your config — user-provided options always take precedence.
+- **Ads**: HLS ad player on all supported devices.
 
 Call `logBrowserInfo(true)` (or enable `debugAdTiming`) to print a detailed compatibility report to the console.
 
@@ -1198,8 +1184,8 @@ src/
 ├── ui/
 │   └── StormcloudVideoPlayer.tsx      # Legacy React component
 ├── sdk/
-│   ├── ima.ts                         # Google IMA integration
-│   └── hlsAdPlayer.ts                 # Native HLS ad player (AdStorm mode, legacy TVs)
+│   ├── pal.ts                         # Google PAL nonce manager
+│   └── hlsAdPlayer.ts                 # HLS / progressive VAST ad player
 ├── utils/
 │   ├── tracking.ts                    # Analytics and ad tracking
 │   ├── browserCompat.ts               # Browser / Smart TV detection & auto-overrides
@@ -1321,19 +1307,18 @@ Built with ❤️ by the Stormcloud team
 
 ### What's New in v0.5
 
-- 🗓️ **VMAP 1.0 Support**: New `vmapUrl` config/prop loads a VMAP manifest and schedules pre-roll, mid-roll, percentage-based, and post-roll breaks automatically
+- 🗓️ **VMAP 1.0 Support**: `isVmap` + `vmapUrl` load a VMAP manifest and schedule pre-roll, mid-roll, percentage-based, and post-roll breaks automatically
   - Supports `start`, `end`, `HH:MM:SS[.mmm]`, and `NN%` `timeOffset` values
   - Namespaced (`vmap:AdBreak`) and non-namespaced manifests both supported
   - Breaks are consumed-once-per-session and integrate with the existing late-join policy
 - 📺 **Smart TV First-Class Support**: New browser-compat layer auto-detects LG WebOS, Samsung Tizen, Sony BRAVIA, LG NetCast and generic Smart TV UAs
-  - Exports `detectBrowser`, `supportsGoogleIMA`, `getRecommendedAdPlayer`, `supportsModernJS`, `logBrowserInfo`, `getBrowserConfigOverrides`, `supportsFeature`
-  - Automatically forces HLS ad player on legacy TVs where IMA SDK is not available
+  - Exports `detectBrowser`, `supportsModernJS`, `logBrowserInfo`, `getBrowserConfigOverrides`, `supportsFeature`
   - Automatically enables `allowNativeHls` on Smart TVs for more reliable playback
 - 🧩 **Automatic Polyfills**: `initializePolyfills()` runs at construction time and backfills `URLSearchParams`, `TextEncoder`, `Promise.prototype.finally`, `Object.assign`, `Array.from`, and `String.prototype.startsWith/endsWith/includes` for legacy environments
-- 📊 **Expanded Ad Tracking**: New `sendAdDetectTracking`, `sendAdLoadedTracking`, and `sendAdImpressionTracking` helpers (plus `AdDetectInfo`, `AdLoadedInfo`, `AdImpressionInfo`, and `AdTrackingSource` types) for prebid/IMA/HLS ad lifecycle events
+- 📊 **Expanded Ad Tracking**: New `sendAdDetectTracking`, `sendAdLoadedTracking`, and `sendAdImpressionTracking` helpers (plus `AdDetectInfo`, `AdLoadedInfo`, `AdImpressionInfo` types) for SCTE-35 and HLS ad lifecycle events
 - ⚙️ **Ad-Break Timing Controls**: New `adBreakCheckIntervalMs` (default 1000ms, min 250ms) and `maxAdBreakExtensionMs` (default 60000ms) options give you precise control over how long the player is allowed to extend an ad break past its SCTE-35 duration when ads are still playing or queued
 - 🙈 **Hide Loading Indicator**: New `hideLoadingIndicator` prop/config hides the built-in buffering spinner when you want to render your own overlay
-- 🔌 **Expanded Public API**: `createImaController`, `createHlsAdPlayer`, and `initializePolyfills` are now exported alongside the new browser-compat utilities, making it easier to build custom integrations on top of the player core
+- 🔌 **Expanded Public API**: `createHlsAdPlayer`, `createPalNonceManager`, and `initializePolyfills` are exported alongside browser-compat utilities for custom integrations
 
 ### What's New in v0.4
 
@@ -1358,17 +1343,16 @@ 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
+- 🎬 **Custom HLS Ad Player**: Native HLS ad playback with VAST XML parsing
+- 🎯 **VAST Tag Resolution**: `vastMode` selects AdStorm `/vast/{licenseKey}` vs `/ads/web` or custom `vastTagUrl`
 - 📊 **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
-- 🔀 **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
+- 📦 **Zero external ad SDK dependencies**
+- 🎨 **Seamless Playback**: Same player stack for content and ads
+- 🔀 **VAST Mode System**: `vastMode` configures which endpoint supplies the VAST tag URL
+  - `vastMode: 'adstorm'` → `/vast/{licenseKey}` endpoint
+  - `vastMode: 'default'` → `/ads/web` endpoint or `vastTagUrl` (both resolve to HLS ad player playback)
 - ⚠️ **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