unified-video-framework 1.4.399 → 1.4.401

package/packages/web/src/react/WebPlayerView.tsx

@@ -4,6 +4,7 @@ import type { CSSProperties } from 'react';
 import type { VideoSource, SubtitleTrack, VideoMetadata, PlayerConfig } from '../../core/dist';
 import { WebPlayer } from '../WebPlayer';
 import { GoogleAdsManager } from '../ads/GoogleAdsManager';
+import { LiveStreamAdsManager } from '../ads/LiveStreamAdsManager';
 // EPG imports - conditionally loaded
 import type { EPGData, EPGConfig, EPGProgram, EPGProgramRow } from './types/EPGTypes';
 import type { VCManifest, VCProduct, VCEvent } from './types/VideoCommerceTypes';
@@ -406,16 +407,34 @@ export type WebPlayerViewProps = {
   // Google Ads Configuration
   googleAds?: {
     adTagUrl: string;                    // VAST/VMAP ad tag URL
-    midrollTimes?: number[];            // Mid-roll ad times in seconds [30, 60, 120]
+    midrollTimes?: number[];            // Mid-roll ad times in seconds [30, 60, 120] (VOD only)
     companionAdSlots?: Array<{          // Companion ad containers
       containerId: string;
       width: number;
       height: number;
     }>;
+
+    // Live Stream Ad Options (NEW)
+    liveAdBreakMode?: 'metadata' | 'periodic' | 'manual' | 'hybrid';  // Live ad insertion mode
+    periodicAdInterval?: number;        // For periodic mode: ad every X seconds (default: 300)
+    syncToLiveEdge?: boolean;           // Jump to live edge after ad (default: false - DVR style)
+    liveEdgeOffset?: number;            // Seconds behind live edge (default: 3)
+    pauseStreamDuringAd?: boolean;      // Pause stream download during ad (default: true)
+
+    // Metadata Detection Config (for 'metadata' mode)
+    metadataConfig?: {
+      detectDateRange?: boolean;        // Detect #EXT-X-DATERANGE tags (default: true)
+      detectID3?: boolean;               // Detect ID3 timed metadata (default: true)
+      adClassNames?: string[];          // CLASS values to detect (default: ['com.google.ads', 'ads'])
+    };
+
+    // Callbacks
     onAdStart?: () => void;             // Called when ad starts
     onAdEnd?: () => void;               // Called when ad ends
     onAdError?: (error: any) => void;   // Called on ad error
     onAllAdsComplete?: () => void;      // Called when all ads complete
+    onLiveAdBreakDetected?: (metadata: any) => void;  // Called when live ad cue detected (metadata mode)
+    onAdBreakScheduled?: (scheduledTime: number) => void;  // Called when ad scheduled (periodic mode)
   };
   
   // Chapter Event Callbacks
@@ -1225,9 +1244,25 @@ export const WebPlayerView: React.FC<WebPlayerViewProps> = (props) => {
           
           // Initialize Google Ads if configured
           if (props.googleAds) {
-            // Small delay to ensure ad container is properly mounted in DOM
+            // Wait for ad container to be properly mounted in DOM
+            const waitForAdContainer = () => {
+              return new Promise<void>((resolve) => {
+                const checkContainer = () => {
+                  if (adContainerRef.current && document.body.contains(adContainerRef.current)) {
+                    resolve();
+                  } else {
+                    setTimeout(checkContainer, 50);
+                  }
+                };
+                checkContainer();
+              });
+            };
+
             setTimeout(async () => {
               try {
+                // Wait for ad container to be in DOM
+                await waitForAdContainer();
+
                 // Ensure ad container exists
                 if (!adContainerRef.current) {
                   console.error('❌ Ad container ref is null - cannot initialize ads');
@@ -1270,14 +1305,122 @@ export const WebPlayerView: React.FC<WebPlayerViewProps> = (props) => {
                   return true;
                 };
 
-                const adsManager = new GoogleAdsManager(
-                  videoElement,
-                  adContainer,
-                  {
-                    adTagUrl: props.googleAds.adTagUrl,
-                    midrollTimes: props.googleAds.midrollTimes,
-                    companionAdSlots: props.googleAds.companionAdSlots,
-                    onAdStart: () => {
+                // Determine if this is a live stream with live ad modes
+                const isLiveAdMode = props.googleAds.liveAdBreakMode &&
+                                     props.googleAds.liveAdBreakMode !== 'manual';
+
+                // Use LiveStreamAdsManager for live ad modes, otherwise use GoogleAdsManager
+                const adsManager = isLiveAdMode
+                  ? new LiveStreamAdsManager(
+                      videoElement,
+                      adContainer,
+                      {
+                        adTagUrl: props.googleAds.adTagUrl,
+                        midrollTimes: props.googleAds.midrollTimes,
+                        companionAdSlots: props.googleAds.companionAdSlots,
+
+                        // Live stream specific config
+                        liveAdBreakMode: props.googleAds.liveAdBreakMode,
+                        periodicAdInterval: props.googleAds.periodicAdInterval,
+                        syncToLiveEdge: props.googleAds.syncToLiveEdge,
+                        liveEdgeOffset: props.googleAds.liveEdgeOffset,
+                        pauseStreamDuringAd: props.googleAds.pauseStreamDuringAd,
+                        metadataConfig: props.googleAds.metadataConfig,
+
+                        onAdStart: () => {
+                          setIsAdPlaying(true);
+
+                          // Check if this is a pre-roll ad (video time near 0)
+                          if (videoElement.currentTime < 1) {
+                            console.log('🎬 Pre-roll ad starting - blocking video playback');
+                            isPrerollPlaying = true;
+                            hasPrerollAd = true;
+
+                            // Add playback blocker
+                            videoElement.addEventListener('play', blockVideoUntilPreroll);
+                          }
+
+                          // Notify player to block keyboard controls
+                          if (typeof (player as any).setAdPlaying === 'function') {
+                            (player as any).setAdPlaying(true);
+                          }
+                          props.googleAds?.onAdStart?.();
+                        },
+                        onLiveAdBreakDetected: props.googleAds.onLiveAdBreakDetected,
+                        onAdBreakScheduled: props.googleAds.onAdBreakScheduled,
+                        onAdEnd: () => {
+                          setIsAdPlaying(false);
+
+                          // Handle pre-roll completion
+                          if (isPrerollPlaying) {
+                            console.log('🎬 Pre-roll ad completed');
+                            isPrerollPlaying = false;
+
+                            // Remove playback blocker
+                            videoElement.removeEventListener('play', blockVideoUntilPreroll);
+
+                            // Reset video to beginning if it leaked any playback
+                            if (videoElement.currentTime > 0 && videoElement.currentTime < 10) {
+                              console.log(`⏮️ Resetting video to 0:00 (was at ${videoElement.currentTime.toFixed(2)}s)`);
+                              videoElement.currentTime = 0;
+                            }
+                          }
+
+                          // Notify player to unblock keyboard controls
+                          if (typeof (player as any).setAdPlaying === 'function') {
+                            (player as any).setAdPlaying(false);
+                          }
+                          props.googleAds?.onAdEnd?.();
+                        },
+                        onAdError: (error) => {
+                          setIsAdPlaying(false);
+                          isPrerollPlaying = false;
+
+                          // Remove blocker on error
+                          videoElement.removeEventListener('play', blockVideoUntilPreroll);
+
+                          // Notify player to unblock keyboard controls
+                          if (typeof (player as any).setAdPlaying === 'function') {
+                            (player as any).setAdPlaying(false);
+                          }
+                          props.googleAds?.onAdError?.(error);
+                        },
+                        onAllAdsComplete: () => {
+                          setIsAdPlaying(false);
+                          isPrerollPlaying = false;
+
+                          // Remove blocker when all ads complete
+                          videoElement.removeEventListener('play', blockVideoUntilPreroll);
+
+                          // Notify player to unblock keyboard controls
+                          if (typeof (player as any).setAdPlaying === 'function') {
+                            (player as any).setAdPlaying(false);
+                          }
+                          props.googleAds?.onAllAdsComplete?.();
+                        },
+                        onAdCuePoints: (cuePoints: number[]) => {
+                          // Check if there's a pre-roll (cue point at 0)
+                          if (cuePoints.includes(0)) {
+                            console.log('✅ Pre-roll ad detected in cue points');
+                            hasPrerollAd = true;
+                          }
+
+                          // Inject markers from VMAP cue points (if midrollTimes not provided)
+                          if (!props.googleAds?.midrollTimes || props.googleAds.midrollTimes.length === 0) {
+                            console.log('🔵 Using VMAP cue points for ad markers:', cuePoints);
+                            injectAdMarkersFromTimes(cuePoints);
+                          }
+                        },
+                      }
+                    )
+                  : new GoogleAdsManager(
+                      videoElement,
+                      adContainer,
+                      {
+                        adTagUrl: props.googleAds.adTagUrl,
+                        midrollTimes: props.googleAds.midrollTimes,
+                        companionAdSlots: props.googleAds.companionAdSlots,
+                        onAdStart: () => {
                       setIsAdPlaying(true);
 
                       // Check if this is a pre-roll ad (video time near 0)
@@ -1361,11 +1504,20 @@ export const WebPlayerView: React.FC<WebPlayerViewProps> = (props) => {
                     },
                   }
                 );
-                
-                await adsManager.initialize();
-                adsManagerRef.current = adsManager;
 
-                console.log('✅ Google Ads initialized successfully');
+                // Initialize ads manager (different for live vs VOD)
+                if (isLiveAdMode) {
+                  // For LiveStreamAdsManager, pass HLS instance for metadata detection
+                  const hlsInstance = (player as any).hls || (player as any).getHlsInstance?.();
+                  await (adsManager as LiveStreamAdsManager).initializeLiveAds(hlsInstance);
+                  console.log('✅ Live Stream Ads initialized successfully');
+                } else {
+                  // For regular GoogleAdsManager
+                  await adsManager.initialize();
+                  console.log('✅ Google Ads initialized successfully');
+                }
+
+                adsManagerRef.current = adsManager;
 
                 // Move ad container into player wrapper for fullscreen support
                 const playerWrapper = containerRef.current?.querySelector('.uvf-player-wrapper');

package/packages/web/src/react/examples/live-stream-ads-example.tsx

@@ -0,0 +1,362 @@
+import React, { useState } from 'react';
+import { WebPlayerView } from '../WebPlayerView';
+
+/**
+ * Example: Live Stream Ads with Metadata and Periodic Modes
+ *
+ * This example demonstrates how to integrate ads with live streaming using:
+ * 1. Metadata-based ad insertion (detects cues in HLS stream)
+ * 2. Periodic timer-based ad insertion (every X seconds)
+ * 3. Hybrid mode (both metadata and periodic)
+ */
+
+export const LiveStreamAdsExample: React.FC = () => {
+  const [adEvents, setAdEvents] = useState<string[]>([]);
+  const [mode, setMode] = useState<'metadata' | 'periodic' | 'hybrid'>('periodic');
+
+  const logAdEvent = (event: string) => {
+    console.log(`[Ad Event] ${event}`);
+    setAdEvents(prev => [...prev, `${new Date().toLocaleTimeString()}: ${event}`].slice(-10)); // Keep last 10
+  };
+
+  return (
+    <div style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      {/* Mode Selector */}
+      <div style={{ padding: '20px', backgroundColor: '#f5f5f5', borderBottom: '1px solid #ddd' }}>
+        <h2 style={{ margin: '0 0 15px 0' }}>Live Stream Ads - Example</h2>
+
+        <div style={{ display: 'flex', gap: '10px', marginBottom: '10px' }}>
+          <button
+            onClick={() => setMode('metadata')}
+            style={{
+              padding: '10px 20px',
+              backgroundColor: mode === 'metadata' ? '#007bff' : '#6c757d',
+              color: 'white',
+              border: 'none',
+              borderRadius: '4px',
+              cursor: 'pointer'
+            }}
+          >
+            Metadata Mode
+          </button>
+
+          <button
+            onClick={() => setMode('periodic')}
+            style={{
+              padding: '10px 20px',
+              backgroundColor: mode === 'periodic' ? '#007bff' : '#6c757d',
+              color: 'white',
+              border: 'none',
+              borderRadius: '4px',
+              cursor: 'pointer'
+            }}
+          >
+            Periodic Mode (Every 2 min)
+          </button>
+
+          <button
+            onClick={() => setMode('hybrid')}
+            style={{
+              padding: '10px 20px',
+              backgroundColor: mode === 'hybrid' ? '#007bff' : '#6c757d',
+              color: 'white',
+              border: 'none',
+              borderRadius: '4px',
+              cursor: 'pointer'
+            }}
+          >
+            Hybrid Mode
+          </button>
+        </div>
+
+        <div style={{ fontSize: '14px', color: '#666' }}>
+          <strong>Current Mode:</strong> {mode}
+          {mode === 'metadata' && ' - Detects #EXT-X-DATERANGE tags in HLS stream'}
+          {mode === 'periodic' && ' - Shows ads every 2 minutes of playback'}
+          {mode === 'hybrid' && ' - Uses both metadata detection AND periodic fallback'}
+        </div>
+      </div>
+
+      {/* Video Player */}
+      <div style={{ flex: 1, position: 'relative', backgroundColor: '#000' }}>
+        <WebPlayerView
+          // Live HLS stream
+          url="https://stream.example.com/live.m3u8"
+          type="hls"
+
+          // Player config
+          autoPlay={false}
+          controls={true}
+          muted={true}  // Start muted for autoplay compatibility
+
+          // Google Ads for Live Streaming
+          googleAds={{
+            // VAST ad tag URL
+            adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=',
+
+            // ========================================
+            // LIVE STREAM AD CONFIGURATION
+            // ========================================
+
+            // Choose ad insertion mode
+            liveAdBreakMode: mode,
+
+            // For periodic mode: ad every X seconds (default: 300 = 5 minutes)
+            periodicAdInterval: 120,  // 2 minutes for demo
+
+            // Sync to live edge after ad (recommended for live streams)
+            syncToLiveEdge: true,
+            liveEdgeOffset: 3,  // Stay 3 seconds behind live edge
+
+            // Metadata detection config (for metadata/hybrid modes)
+            metadataConfig: {
+              detectDateRange: true,  // Detect #EXT-X-DATERANGE tags
+              detectID3: true,        // Detect ID3 timed metadata
+              adClassNames: ['com.google.ads', 'ads', 'ad-break']
+            },
+
+            // ========================================
+            // AD EVENT CALLBACKS
+            // ========================================
+
+            onAdStart: () => {
+              logAdEvent(`🎬 Ad Started (Mode: ${mode})`);
+            },
+
+            onAdEnd: () => {
+              logAdEvent('✅ Ad Ended - Resuming Live Stream');
+            },
+
+            onAdError: (error: any) => {
+              logAdEvent(`❌ Ad Error: ${error?.getMessage?.() || error}`);
+            },
+
+            onAllAdsComplete: () => {
+              logAdEvent('✅ All Ads in Pod Completed');
+            },
+
+            // Live-specific callbacks
+            onLiveAdBreakDetected: (metadata) => {
+              logAdEvent(`📍 Live Ad Cue Detected: ${JSON.stringify(metadata).slice(0, 50)}...`);
+            },
+
+            onAdBreakScheduled: (scheduledTime) => {
+              logAdEvent(`⏰ Ad Break Scheduled at ${scheduledTime.toFixed(0)}s playback time`);
+            },
+          }}
+
+          // Player callbacks
+          onReady={(player) => {
+            console.log('Player ready with live stream ads');
+            logAdEvent('🎥 Player Ready');
+          }}
+
+          onError={(error) => {
+            console.error('Player error:', error);
+            logAdEvent(`❌ Player Error: ${error instanceof Error ? error.message : String(error)}`);
+          }}
+
+          onTimeUpdate={(time) => {
+            // Optional: Track playback time
+          }}
+        />
+      </div>
+
+      {/* Ad Event Log */}
+      <div style={{
+        padding: '20px',
+        backgroundColor: '#f9f9f9',
+        borderTop: '1px solid #ddd',
+        maxHeight: '200px',
+        overflowY: 'auto',
+      }}>
+        <h3 style={{ margin: '0 0 10px 0', fontSize: '16px' }}>Live Ad Events Log:</h3>
+        {adEvents.length === 0 ? (
+          <p style={{ color: '#999', margin: 0 }}>No ad events yet. Play the video to see ads.</p>
+        ) : (
+          <ul style={{ margin: 0, padding: '0 0 0 20px' }}>
+            {adEvents.map((event, index) => (
+              <li key={index} style={{ fontSize: '14px', marginBottom: '5px' }}>
+                {event}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+
+      {/* Implementation Notes */}
+      <div style={{
+        padding: '20px',
+        backgroundColor: '#e7f3ff',
+        borderTop: '1px solid #b3d9ff'
+      }}>
+        <h3 style={{ margin: '0 0 10px 0', fontSize: '16px' }}>💡 Implementation Notes:</h3>
+        <ul style={{ margin: 0, paddingLeft: '20px', fontSize: '14px' }}>
+          <li>
+            <strong>Metadata Mode:</strong> Requires HLS stream with #EXT-X-DATERANGE tags or ID3 metadata.
+            Your encoder must embed ad cues in the manifest.
+          </li>
+          <li>
+            <strong>Periodic Mode:</strong> Works with any live stream. Ads trigger every X seconds of actual playback.
+            Simple but users see ads at different times (not synchronized).
+          </li>
+          <li>
+            <strong>Hybrid Mode:</strong> Uses metadata when available, falls back to periodic timer.
+            Best of both worlds!
+          </li>
+          <li>
+            <strong>Live Edge Sync:</strong> After ads, player jumps to live edge (catches up to "now").
+            Disable if you want DVR-style behavior (continue from where paused).
+          </li>
+        </ul>
+      </div>
+    </div>
+  );
+};
+
+/**
+ * ========================================================================
+ * USAGE EXAMPLE 1: METADATA-BASED LIVE ADS
+ * ========================================================================
+ */
+export const MetadataLiveAdsExample: React.FC = () => {
+  return (
+    <WebPlayerView
+      url="https://stream.example.com/live.m3u8"
+      type="hls"
+
+      googleAds={{
+        adTagUrl: 'https://pubads.g.doubleclick.net/...',
+
+        // Use metadata mode
+        liveAdBreakMode: 'metadata',
+
+        // Metadata detection config
+        metadataConfig: {
+          detectDateRange: true,
+          detectID3: true,
+          adClassNames: ['com.google.ads', 'ads']
+        },
+
+        // Sync to live edge after ads
+        syncToLiveEdge: true,
+        liveEdgeOffset: 3,
+
+        onLiveAdBreakDetected: (metadata) => {
+          console.log('Ad cue detected:', metadata);
+        }
+      }}
+    />
+  );
+};
+
+/**
+ * ========================================================================
+ * USAGE EXAMPLE 2: PERIODIC TIMER-BASED LIVE ADS
+ * ========================================================================
+ */
+export const PeriodicLiveAdsExample: React.FC = () => {
+  return (
+    <WebPlayerView
+      url="https://stream.example.com/live.m3u8"
+      type="hls"
+
+      googleAds={{
+        adTagUrl: 'https://pubads.g.doubleclick.net/...',
+
+        // Use periodic mode
+        liveAdBreakMode: 'periodic',
+
+        // Ad every 5 minutes (300 seconds)
+        periodicAdInterval: 300,
+
+        // Sync to live edge after ads
+        syncToLiveEdge: true,
+
+        onAdBreakScheduled: (scheduledTime) => {
+          console.log(`Next ad at ${scheduledTime}s playback time`);
+        }
+      }}
+    />
+  );
+};
+
+/**
+ * ========================================================================
+ * USAGE EXAMPLE 3: HYBRID MODE (METADATA + PERIODIC FALLBACK)
+ * ========================================================================
+ */
+export const HybridLiveAdsExample: React.FC = () => {
+  return (
+    <WebPlayerView
+      url="https://stream.example.com/live.m3u8"
+      type="hls"
+
+      googleAds={{
+        adTagUrl: 'https://pubads.g.doubleclick.net/...',
+
+        // Use hybrid mode
+        liveAdBreakMode: 'hybrid',
+
+        // Metadata detection (primary)
+        metadataConfig: {
+          detectDateRange: true,
+          detectID3: true
+        },
+
+        // Periodic fallback (if no metadata detected)
+        periodicAdInterval: 300,
+
+        // Sync to live edge
+        syncToLiveEdge: true,
+
+        // Callbacks for both modes
+        onLiveAdBreakDetected: (metadata) => {
+          console.log('✅ Metadata ad cue detected');
+        },
+
+        onAdBreakScheduled: (scheduledTime) => {
+          console.log('⏰ Fallback periodic ad scheduled');
+        }
+      }}
+    />
+  );
+};
+
+/**
+ * ========================================================================
+ * BACKEND-CONTROLLED EXAMPLE
+ * ========================================================================
+ * Fetch ad schedule from backend and configure player accordingly
+ */
+export const BackendControlledLiveAdsExample: React.FC = () => {
+  const [adConfig, setAdConfig] = useState<any>(null);
+
+  // Fetch ad configuration from backend
+  React.useEffect(() => {
+    fetch('/api/live-stream/ad-config')
+      .then(res => res.json())
+      .then(config => {
+        setAdConfig(config);
+      });
+  }, []);
+
+  if (!adConfig) return <div>Loading...</div>;
+
+  return (
+    <WebPlayerView
+      url={adConfig.streamUrl}
+      type="hls"
+
+      googleAds={{
+        adTagUrl: adConfig.adTagUrl,
+        liveAdBreakMode: adConfig.mode,  // Backend decides: metadata | periodic | hybrid
+        periodicAdInterval: adConfig.periodicInterval,
+        metadataConfig: adConfig.metadataConfig,
+        syncToLiveEdge: true
+      }}
+    />
+  );
+};
+
+export default LiveStreamAdsExample;