unified-video-framework 1.4.404 → 1.4.406

package/packages/web/src/ads/LiveStreamAdsManager.ts

@@ -1,625 +0,0 @@
-/**
- * Live Stream Ads Manager
- *
- * Extends GoogleAdsManager to support live streaming ad insertion
- *
- * Supported Modes:
- * 1. Metadata-based: Detects #EXT-X-DATERANGE or ID3 tags in HLS stream
- * 2. Periodic: Shows ads every X seconds of playback
- * 3. Manual: Programmatic ad break triggering
- */
-
-import { GoogleAdsManager, GoogleAdsConfig } from './GoogleAdsManager';
-
-// HLS.js event types (if using HLS.js)
-declare const Hls: any;
-
-export type LiveAdBreakMode = 'metadata' | 'periodic' | 'manual' | 'hybrid';
-
-export interface LiveStreamAdsConfig extends GoogleAdsConfig {
-  // Live stream specific options
-  liveAdBreakMode?: LiveAdBreakMode;
-
-  // For 'periodic' mode: Insert ads every X seconds of playback
-  periodicAdInterval?: number;  // Default: 300 (5 minutes)
-
-  // For 'metadata' mode: Configure metadata detection
-  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'])
-  };
-
-  // Advanced options
-  syncToLiveEdge?: boolean;       // Jump to live edge after ad (default: false for DVR-style)
-  liveEdgeOffset?: number;        // Seconds behind live edge (default: 3)
-  pauseStreamDuringAd?: boolean;  // Pause stream during ad (default: true - DVR-style)
-
-  // Callbacks
-  onLiveAdBreakDetected?: (metadata: any) => void;
-  onAdBreakScheduled?: (scheduledTime: number) => void;
-  onLiveEdgeSync?: (newPosition: number) => void;
-}
-
-export class LiveStreamAdsManager extends GoogleAdsManager {
-  private liveConfig: LiveStreamAdsConfig;
-
-  // Periodic mode state
-  private periodicAdTimer: NodeJS.Timeout | null = null;
-  private lastAdBreakTime: number = 0;
-  private playbackStartTime: number = 0;
-
-  // Metadata mode state
-  private hlsInstance: any = null;
-  private processedCuePoints: Set<string> = new Set();
-  private metadataTrack: TextTrack | null = null;
-
-  // Live stream state
-  private isLiveStream: boolean = false;
-  private streamStartTime: number = 0;
-
-  constructor(video: HTMLVideoElement, adContainer: HTMLElement, config: LiveStreamAdsConfig) {
-    super(video, adContainer, config);
-    this.liveConfig = {
-      liveAdBreakMode: 'metadata',
-      periodicAdInterval: 300,  // Default: 5 minutes
-      syncToLiveEdge: false,     // Default: DVR-style (user sees all content)
-      liveEdgeOffset: 3,
-      pauseStreamDuringAd: true, // Default: Pause stream during ad (DVR-style)
-      metadataConfig: {
-        detectDateRange: true,
-        detectID3: true,
-        adClassNames: ['com.google.ads', 'ads', 'ad-break']
-      },
-      ...config
-    };
-  }
-
-  /**
-   * Initialize live stream ads with specified mode
-   */
-  async initializeLiveAds(hlsInstance?: any): Promise<void> {
-    // Initialize parent (Google IMA SDK)
-    await this.initialize();
-
-    this.isLiveStream = true;
-    this.hlsInstance = hlsInstance;
-    this.playbackStartTime = this.video.currentTime || 0;
-    this.streamStartTime = Date.now();
-
-    const mode = this.liveConfig.liveAdBreakMode || 'metadata';
-
-    console.log(`🔴 Live Stream Ads initialized`);
-    console.log(`   Mode: ${mode}`);
-    console.log(`   Stream start time: ${this.playbackStartTime}s`);
-
-    // Setup based on mode
-    switch (mode) {
-      case 'metadata':
-        this.setupMetadataListener();
-        break;
-
-      case 'periodic':
-        this.setupPeriodicAdBreaks();
-        break;
-
-      case 'hybrid':
-        // Both metadata and periodic
-        this.setupMetadataListener();
-        this.setupPeriodicAdBreaks();
-        break;
-
-      case 'manual':
-        console.log('Manual mode - use triggerAdBreak() to show ads');
-        break;
-    }
-  }
-
-  /**
-   * ========================================================================
-   * OPTION 2: METADATA-BASED AD INSERTION
-   * ========================================================================
-   * Detects #EXT-X-DATERANGE tags or ID3 metadata in HLS stream
-   */
-  private setupMetadataListener(): void {
-    console.log('📡 Setting up metadata listener for live ad cues');
-
-    const config = this.liveConfig.metadataConfig!;
-
-    // Method 1: HLS.js metadata events
-    if (this.hlsInstance && typeof Hls !== 'undefined') {
-      this.setupHlsJsMetadata();
-    }
-
-    // Method 2: Native HLS (Safari, iOS) - TextTrack metadata
-    if (config.detectID3) {
-      this.setupNativeMetadata();
-    }
-  }
-
-  /**
-   * Setup HLS.js metadata detection
-   */
-  private setupHlsJsMetadata(): void {
-    if (!this.hlsInstance || typeof Hls === 'undefined') {
-      console.warn('HLS.js not available for metadata detection');
-      return;
-    }
-
-    console.log('✅ Setting up HLS.js metadata listeners');
-
-    // Listen for fragment parsing metadata (ID3 tags)
-    this.hlsInstance.on(Hls.Events.FRAG_PARSING_METADATA, (event: string, data: any) => {
-      console.log('📥 HLS metadata event:', data);
-      this.handleHlsMetadata(data);
-    });
-
-    // Listen for level updated (manifest changes with DATERANGE)
-    this.hlsInstance.on(Hls.Events.LEVEL_UPDATED, (event: string, data: any) => {
-      if (data.details && data.details.dateRanges) {
-        console.log('📅 DATERANGE tags detected:', data.details.dateRanges);
-        this.handleDateRanges(data.details.dateRanges);
-      }
-    });
-  }
-
-  /**
-   * Setup native HLS metadata detection (Safari, iOS)
-   */
-  private setupNativeMetadata(): void {
-    // Wait for text tracks to be available
-    const checkForMetadataTrack = () => {
-      if (!this.video.textTracks) return;
-
-      // Find metadata track
-      for (let i = 0; i < this.video.textTracks.length; i++) {
-        const track = this.video.textTracks[i];
-        if (track.kind === 'metadata') {
-          this.metadataTrack = track;
-          console.log('✅ Found native metadata track');
-
-          // Enable the track
-          track.mode = 'hidden';
-
-          // Listen for cue changes
-          track.addEventListener('cuechange', () => {
-            this.handleNativeMetadataCues(track);
-          });
-
-          break;
-        }
-      }
-    };
-
-    // Check now and on loadedmetadata
-    checkForMetadataTrack();
-    this.video.addEventListener('loadedmetadata', checkForMetadataTrack);
-  }
-
-  /**
-   * Handle HLS.js metadata (ID3 tags)
-   */
-  private handleHlsMetadata(data: any): void {
-    if (!data.samples || data.samples.length === 0) return;
-
-    data.samples.forEach((sample: any) => {
-      // Check if this is an ad-related metadata
-      const isAdCue = this.isAdMetadata(sample);
-
-      if (isAdCue) {
-        const cueId = this.generateCueId(sample);
-
-        if (!this.processedCuePoints.has(cueId)) {
-          console.log('✅ Ad cue detected from HLS metadata:', sample);
-          this.processedCuePoints.add(cueId);
-
-          // Notify callback
-          this.liveConfig.onLiveAdBreakDetected?.(sample);
-
-          // Trigger ad break
-          this.triggerAdBreak();
-        }
-      }
-    });
-  }
-
-  /**
-   * Handle #EXT-X-DATERANGE tags
-   */
-  private handleDateRanges(dateRanges: any): void {
-    Object.values(dateRanges).forEach((dateRange: any) => {
-      const className = dateRange.class || dateRange.CLASS;
-      const adClassNames = this.liveConfig.metadataConfig?.adClassNames || [];
-
-      // Check if this DATERANGE is for ads
-      const isAdCue = adClassNames.some(name => className?.includes(name));
-
-      if (isAdCue) {
-        const cueId = dateRange.id || dateRange.ID;
-
-        if (cueId && !this.processedCuePoints.has(cueId)) {
-          console.log('✅ Ad cue detected from DATERANGE:', dateRange);
-          this.processedCuePoints.add(cueId);
-
-          // Notify callback
-          this.liveConfig.onLiveAdBreakDetected?.(dateRange);
-
-          // Trigger ad break
-          this.triggerAdBreak();
-        }
-      }
-    });
-  }
-
-  /**
-   * Handle native metadata cues (Safari, iOS)
-   */
-  private handleNativeMetadataCues(track: TextTrack): void {
-    if (!track.activeCues || track.activeCues.length === 0) return;
-
-    for (let i = 0; i < track.activeCues.length; i++) {
-      const cue: any = track.activeCues[i];
-
-      // Check if this cue is ad-related
-      const isAdCue = this.isAdMetadata(cue);
-
-      if (isAdCue) {
-        const cueId = this.generateCueId(cue);
-
-        if (!this.processedCuePoints.has(cueId)) {
-          console.log('✅ Ad cue detected from native metadata:', cue);
-          this.processedCuePoints.add(cueId);
-
-          // Notify callback
-          this.liveConfig.onLiveAdBreakDetected?.(cue);
-
-          // Trigger ad break
-          this.triggerAdBreak();
-        }
-      }
-    }
-  }
-
-  /**
-   * Check if metadata indicates an ad break
-   */
-  private isAdMetadata(metadata: any): boolean {
-    const adClassNames = this.liveConfig.metadataConfig?.adClassNames || [];
-
-    // Check various metadata formats
-    const className = metadata.class || metadata.CLASS || metadata.value?.class;
-    const key = metadata.key;
-    const data = metadata.data || metadata.value?.data;
-
-    // Check if class name matches ad indicators
-    if (className) {
-      return adClassNames.some(name => className.includes(name));
-    }
-
-    // Check ID3 TXXX frame for ad indicators
-    if (key === 'TXXX' && data) {
-      return adClassNames.some(name => data.toLowerCase().includes(name.toLowerCase()));
-    }
-
-    return false;
-  }
-
-  /**
-   * Generate unique ID for cue point
-   */
-  private generateCueId(metadata: any): string {
-    return metadata.id ||
-           metadata.ID ||
-           metadata.startTime?.toString() ||
-           JSON.stringify(metadata);
-  }
-
-  /**
-   * ========================================================================
-   * OPTION 3: PERIODIC AD INSERTION
-   * ========================================================================
-   * Shows ads every X seconds of actual playback time
-   */
-  private setupPeriodicAdBreaks(): void {
-    const interval = this.liveConfig.periodicAdInterval || 300;
-
-    console.log(`⏰ Setting up periodic ad breaks`);
-    console.log(`   Interval: ${interval} seconds (${interval / 60} minutes)`);
-
-    // Clear existing timer
-    if (this.periodicAdTimer) {
-      clearInterval(this.periodicAdTimer);
-    }
-
-    // Track actual playback time (not wall-clock time)
-    let lastCheckTime = this.video.currentTime || 0;
-    let accumulatedPlaybackTime = 0;
-
-    // Check every second
-    this.periodicAdTimer = setInterval(() => {
-      // Only count time when video is actually playing
-      if (!this.video.paused && !this.isPlayingAd()) {
-        const currentTime = this.video.currentTime || 0;
-        const timeDelta = currentTime - lastCheckTime;
-
-        // Accumulate playback time (handle seeks)
-        if (timeDelta > 0 && timeDelta < 5) {  // Reasonable time delta
-          accumulatedPlaybackTime += timeDelta;
-        }
-
-        lastCheckTime = currentTime;
-
-        // Check if it's time for an ad break
-        const timeSinceLastAd = accumulatedPlaybackTime - this.lastAdBreakTime;
-
-        if (timeSinceLastAd >= interval) {
-          console.log(`⏰ Periodic ad break triggered`);
-          console.log(`   Playback time: ${accumulatedPlaybackTime.toFixed(0)}s`);
-          console.log(`   Time since last ad: ${timeSinceLastAd.toFixed(0)}s`);
-
-          // Notify callback
-          this.liveConfig.onAdBreakScheduled?.(accumulatedPlaybackTime);
-
-          // Trigger ad break
-          this.triggerAdBreak();
-
-          // Update last ad break time
-          this.lastAdBreakTime = accumulatedPlaybackTime;
-        }
-      }
-    }, 1000);
-  }
-
-  /**
-   * ========================================================================
-   * AD BREAK TRIGGERING
-   * ========================================================================
-   */
-
-  /**
-   * Trigger ad break for live stream
-   */
-  public triggerAdBreak(): void {
-    console.log('🎬 Triggering ad break for live stream');
-
-    // Don't interrupt if ad is already playing
-    if (this.isPlayingAd()) {
-      console.warn('⚠️ Ad already playing, skipping trigger');
-      return;
-    }
-
-    // Store current time for DVR-style resume
-    const timeBeforeAd = this.video.currentTime;
-
-    console.log(`📍 Stream position before ad: ${timeBeforeAd.toFixed(2)}s`);
-
-    // Pause stream downloading during ad (saves bandwidth)
-    if (this.liveConfig.pauseStreamDuringAd) {
-      this.pauseStreamDownload();
-    }
-
-    // Initialize ad display container
-    try {
-      this.initAdDisplayContainer();
-    } catch (e) {
-      // Already initialized
-    }
-
-    // Request ads from Google IMA
-    this.requestAds();
-
-    // Setup post-ad resume handler
-    this.setupLiveEdgeResume(timeBeforeAd);
-  }
-
-  /**
-   * Pause stream downloading during ad (saves bandwidth)
-   */
-  private pauseStreamDownload(): void {
-    try {
-      if (this.hlsInstance && this.hlsInstance.stopLoad) {
-        console.log('⏸️ Pausing stream download during ad');
-        this.hlsInstance.stopLoad();
-      } else if ((this.video as any).dashPlayer) {
-        const dashPlayer = (this.video as any).dashPlayer;
-        if (dashPlayer.pause) {
-          dashPlayer.pause();
-        }
-      }
-    } catch (error) {
-      console.warn('Could not pause stream download:', error);
-    }
-  }
-
-  /**
-   * Resume stream downloading after ad
-   */
-  private resumeStreamDownload(): void {
-    try {
-      if (this.hlsInstance && this.hlsInstance.startLoad) {
-        console.log('▶️ Resuming stream download after ad');
-        this.hlsInstance.startLoad();
-      } else if ((this.video as any).dashPlayer) {
-        const dashPlayer = (this.video as any).dashPlayer;
-        if (dashPlayer.play) {
-          dashPlayer.play();
-        }
-      }
-    } catch (error) {
-      console.warn('Could not resume stream download:', error);
-    }
-  }
-
-  /**
-   * Setup live edge resume after ad
-   */
-  private setupLiveEdgeResume(timeBeforeAd: number): void {
-    // Listen for ad end
-    const handleAdEnd = () => {
-      if (this.liveConfig.syncToLiveEdge) {
-        // Mode 1: Jump to live edge (user skips content during ad)
-        console.log('📺 Ad ended, syncing to live edge (skipping content)');
-        this.syncToLiveEdge();
-      } else {
-        // Mode 2: DVR-style resume from pause point (user sees all content)
-        console.log('📺 Ad ended, resuming from pause point (DVR-style)');
-        this.resumeFromPausePoint(timeBeforeAd);
-      }
-    };
-
-    // Use one-time listener
-    const originalOnAdEnd = this.config.onAdEnd;
-    this.config.onAdEnd = () => {
-      handleAdEnd();
-      originalOnAdEnd?.();
-    };
-  }
-
-  /**
-   * Resume from where stream was paused (DVR-style)
-   */
-  private resumeFromPausePoint(pausedTime: number): void {
-    setTimeout(() => {
-      try {
-        console.log(`⏯️ Resuming from paused position: ${pausedTime.toFixed(2)}s`);
-        console.log(`   User is now behind live, but will see all content`);
-
-        // Resume stream downloading first
-        if (this.liveConfig.pauseStreamDuringAd) {
-          this.resumeStreamDownload();
-        }
-
-        // Resume from exact pause point
-        this.video.currentTime = pausedTime;
-
-        // Notify callback
-        this.liveConfig.onLiveEdgeSync?.(pausedTime);
-
-        // Calculate how far behind live user is
-        if (this.hlsInstance && this.hlsInstance.liveSyncPosition !== undefined) {
-          const liveEdge = this.hlsInstance.liveSyncPosition;
-          const behindLive = liveEdge - pausedTime;
-          console.log(`   Behind live by: ${behindLive.toFixed(1)} seconds`);
-        }
-      } catch (error) {
-        console.error('❌ Error resuming from pause point:', error);
-      }
-    }, 100);  // Small delay to ensure ad container is hidden
-  }
-
-  /**
-   * Sync video to live edge after ad
-   */
-  private syncToLiveEdge(): void {
-    setTimeout(() => {
-      try {
-        // Resume stream downloading first
-        if (this.liveConfig.pauseStreamDuringAd) {
-          this.resumeStreamDownload();
-        }
-
-        let liveEdgePosition: number | null = null;
-
-        // Get live edge from HLS.js
-        if (this.hlsInstance && this.hlsInstance.liveSyncPosition !== undefined) {
-          liveEdgePosition = this.hlsInstance.liveSyncPosition;
-          console.log('📍 HLS.js live edge:', liveEdgePosition);
-        }
-        // Get live edge from DASH.js
-        else if ((this.video as any).dashPlayer) {
-          const dashPlayer = (this.video as any).dashPlayer;
-          if (dashPlayer.getDVRSeekOffset) {
-            liveEdgePosition = dashPlayer.getDVRSeekOffset(0);
-          }
-        }
-        // Fallback: estimate from duration and seekable
-        else if (this.video.seekable && this.video.seekable.length > 0) {
-          liveEdgePosition = this.video.seekable.end(this.video.seekable.length - 1);
-          console.log('📍 Native seekable live edge:', liveEdgePosition);
-        }
-
-        // Apply live edge offset
-        if (liveEdgePosition !== null) {
-          const offset = this.liveConfig.liveEdgeOffset || 3;
-          const targetPosition = Math.max(0, liveEdgePosition - offset);
-
-          console.log(`⏩ Syncing to live edge: ${targetPosition.toFixed(2)}s (offset: ${offset}s)`);
-
-          this.video.currentTime = targetPosition;
-
-          // Notify callback
-          this.liveConfig.onLiveEdgeSync?.(targetPosition);
-        } else {
-          console.warn('⚠️ Could not determine live edge position');
-        }
-      } catch (error) {
-        console.error('❌ Error syncing to live edge:', error);
-      }
-    }, 100);  // Small delay to ensure ad container is hidden
-  }
-
-  /**
-   * ========================================================================
-   * UTILITY METHODS
-   * ========================================================================
-   */
-
-  /**
-   * Reset periodic ad timer
-   */
-  public resetPeriodicTimer(): void {
-    this.lastAdBreakTime = 0;
-    console.log('🔄 Periodic ad timer reset');
-  }
-
-  /**
-   * Clear processed cue points (for testing)
-   */
-  public clearProcessedCues(): void {
-    this.processedCuePoints.clear();
-    console.log('🔄 Processed cue points cleared');
-  }
-
-  /**
-   * Update live ad configuration at runtime
-   */
-  public updateLiveConfig(config: Partial<LiveStreamAdsConfig>): void {
-    Object.assign(this.liveConfig, config);
-    console.log('🔄 Live ad config updated:', config);
-
-    // Re-initialize if mode changed
-    if (config.liveAdBreakMode && config.liveAdBreakMode !== this.liveConfig.liveAdBreakMode) {
-      this.destroy();
-      this.initializeLiveAds(this.hlsInstance);
-    }
-  }
-
-  /**
-   * Clean up live stream specific resources
-   */
-  destroy(): void {
-    // Clear periodic timer
-    if (this.periodicAdTimer) {
-      clearInterval(this.periodicAdTimer);
-      this.periodicAdTimer = null;
-    }
-
-    // Clear metadata listeners
-    if (this.hlsInstance && typeof Hls !== 'undefined') {
-      this.hlsInstance.off(Hls.Events.FRAG_PARSING_METADATA);
-      this.hlsInstance.off(Hls.Events.LEVEL_UPDATED);
-    }
-
-    if (this.metadataTrack) {
-      this.metadataTrack.removeEventListener('cuechange', () => {});
-      this.metadataTrack = null;
-    }
-
-    // Clear state
-    this.processedCuePoints.clear();
-    this.hlsInstance = null;
-
-    // Call parent destroy
-    super.destroy();
-  }
-}