stormcloud-video-player 0.2.35 → 0.3.0

package/README.md

@@ -501,6 +501,124 @@ const player = new StormcloudVideoPlayer({
 - ✅ Backward compatible with existing VAST tags
 - ✅ Supports both custom VAST URLs and AdStorm backend
 
+### Ad Pod Generation (Multiple Consecutive Ads)
+
+The player automatically generates **ad pods** (multiple ads played consecutively) from a single VAST URL. This works differently for VOD and live streams:
+
+#### VOD Mode: Fixed Ad Count
+
+For **Video on Demand**, the player uses the `number_ads` field from the API response to determine how many ads to play:
+
+**API Response Configuration:**
+```json
+{
+  "response": {
+    "ima": {
+      "publisherdesk.ima": {
+        "payload": "https://pubads.g.doubleclick.net/gampad/ads?...",
+        "priority": 1
+      }
+    },
+    "options": {
+      "vast": {
+        "cue_tones": {
+          "number_ads": 3
+        }
+      }
+    }
+  }
+}
+```
+
+**How it works:**
+1. Player receives a single VAST URL from the API
+2. The `number_ads` field specifies how many ads should play (e.g., 3)
+3. Player generates 3 unique VAST URLs by adding different `correlator` values
+4. Each unique correlator causes GAM to return a different ad
+5. All 3 ads play consecutively in the ad break
+
+**Example:**
+```javascript
+// Base URL from API
+"https://pubads.g.doubleclick.net/...&correlator="
+
+// Generated URLs (3 ads)
+[
+  "https://pubads.g.doubleclick.net/...&correlator=1730995200000123456780",
+  "https://pubads.g.doubleclick.net/...&correlator=1730995200000789012341",
+  "https://pubads.g.doubleclick.net/...&correlator=1730995200000345678902"
+]
+```
+
+#### Live Mode: Adaptive Duration-Based Ad Filling
+
+For **live streams**, the player uses an **adaptive strategy** that fetches VAST responses, extracts actual ad durations, and dynamically requests additional ads as needed to fill the SCTE-35 marker duration:
+
+**Configuration:**
+```javascript
+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
+});
+```
+
+**How Adaptive Mode Works:**
+
+1. **Initial Request**: Player starts with 2 initial VAST URLs
+2. **Fetch Real Duration**: As each VAST is fetched, the player extracts the actual `<Duration>` from the XML
+3. **Adaptive Calculation**: After fetching each ad, the player:
+   - Calculates total duration of fetched ads
+   - Compares against target SCTE-35 duration
+   - Dynamically generates more VAST URLs if needed
+4. **Smart Filling**: Uses **average** of actual fetched durations (not estimates) to calculate remaining ads
+5. **Continuous Adaptation**: Recalculates after each ad fetch until target duration is met
+
+**Example Scenario:**
+```
+SCTE-35 Duration: 120 seconds
+
+Step 1: Start with 2 initial ads
+  → Fetch Ad 1: Actual duration = 45s
+  → Recalculate: Need (120-45)/45 = 2 more ads
+  → Generate 2 additional VAST URLs
+
+Step 2: Fetch Ad 2: Actual duration = 40s
+  → Total so far: 85s (45s + 40s)
+  → Recalculate: Need (120-85)/42.5 = 1 more ad
+  → Generate 1 additional VAST URL
+
+Step 3: Fetch Ad 3: Actual duration = 35s
+  → Total: 120s ✅ Target reached!
+
+Final: 3 ads played (perfectly fills 120 seconds)
+```
+
+**Debug Output:**
+```
+[ADAPTIVE-POD] 📺 LIVE MODE (ADAPTIVE): Target duration=120000ms | Starting with 2 ads, will fetch actual durations and add more dynamically
+[DEBUG-POD] 🔄 Generated 2 initial VAST URLs with unique correlators
+[ADAPTIVE-POD] ✓ Fetched ad duration: 45s (1 ads fetched so far)
+[ADAPTIVE-POD] 📊 Need 2 more ads | Fetched: 45000ms / Target: 120000ms | Remaining: 75000ms | Avg duration: 45000ms
+[ADAPTIVE-POD] 🔄 Adding 2 additional VAST URLs to queue
+[ADAPTIVE-POD] ✓ Fetched ad duration: 40s (2 ads fetched so far)
+[ADAPTIVE-POD] 📊 Need 1 more ads | Fetched: 85000ms / Target: 120000ms | Remaining: 35000ms | Avg duration: 42500ms
+[ADAPTIVE-POD] ✓ Fetched ad duration: 35s (3 ads fetched so far)
+[ADAPTIVE-POD] ✅ Target duration reached: 120000ms / 120000ms
+```
+
+**Benefits of Adaptive Approach:**
+
+- ✅ **Accurate Filling**: Uses actual ad durations from VAST responses
+- ✅ **Less Waste**: Doesn't over-request ads unnecessarily  
+- ✅ **Flexible**: Adapts to GAM returning 15s, 30s, 60s, or mixed-length ads
+- ✅ **Efficient**: Fetches durations while preloading, no extra latency
+- ✅ **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: