@newrelic/video-videojs 4.1.1 → 4.2.0

package/src/ads/media-tailor.js

@@ -0,0 +1,1281 @@
+/* eslint-disable no-undef */
+import nrvideo from '@newrelic/video-core';
+import VideojsAdsTracker from './videojs-ads';
+import {
+  DEFAULT_LIVE_POLL_INTERVAL_MS,
+  HLS_MIME_TYPE,
+  MEDIATAILOR_HOST_MARKER,
+  SCTE35_SCHEME_MARKER,
+  TRACKING_API_TIMEOUT_MS,
+  STREAM_TYPE,
+  MANIFEST_TYPE,
+} from './utils/mt-constants.js';
+import {
+  getTimestamp,
+  detectManifestFormatFromUrl,
+  detectPlaybackStreamType,
+  buildTrackingEndpointUrl,
+  determineAdPosition,
+  getQuartilesToFire,
+  findActiveAdBreak,
+  findActivePod,
+  mergeAdSchedules,
+  parseHlsManifestForAdBreaks,
+  parseDashManifestForAdBreaks,
+  detectAdBreaksFromVhsPlaylist,
+  whichAdSegmentMarker,
+  enrichAdScheduleWithTrackingMetadata,
+  extractHlsTargetDurationSeconds,
+  extractDashMinimumUpdatePeriodSeconds,
+  fetchHlsMasterManifest,
+  fetchHlsMediaPlaylist,
+  fetchDashManifest,
+  getTrackingMetadata,
+} from './utils/mt.js';
+
+// Handle both direct and default export from video-core
+const nrvideoCore = nrvideo.default || nrvideo;
+const Log = nrvideoCore.Log;
+
+/**
+ * AWS MediaTailor Ad Tracker
+ * Tracks ads from AWS MediaTailor SSAI streams (HLS/DASH)
+ *
+ * Features:
+ * - Client-side ad detection from manifest markers (CUE-OUT/CUE-IN)
+ * - Pod-level tracking (multiple ads within one break)
+ * - VOD and Live stream support
+ * - Zero race conditions via VHS player hooks
+ * - Tracking API metadata enrichment
+ */
+export default class MediaTailorAdsTracker extends VideojsAdsTracker {
+  /**
+   * Checks if tracker should be used for this player source
+   */
+  static isUsing(player, options = {}) {
+    // Opt-in flag is the single source of truth.
+    // Accepts { mediatailor: true } or { mediatailor: { trackingUrl, adSegmentPrefix } }.
+    return Boolean(options && options.mediatailor);
+  }
+
+  /**
+   * Returns tracker name for New Relic instrumentation
+   */
+  getTrackerName() {
+    return 'aws-media-tailor';
+  }
+
+  /**
+   * Returns player version (MediaTailor doesn't have version)
+   */
+  getPlayerVersion() {
+    return 'MediaTailor';
+  }
+
+  /**
+   * Override to return the correct ad position from our ad schedule
+   * This overrides video-core's default logic which only checks if content started
+   */
+  getAdPosition() {
+    if (this.currentAdBreak && this.currentAdBreak.adPosition) {
+      return this.currentAdBreak.adPosition;
+    }
+    return super.getAdPosition();
+  }
+
+  constructor(player, options = {}) {
+    super(player);
+
+    // Normalize mediatailor option: true | { trackingUrl, adSegmentPrefix } | undefined
+    const mtOptions =
+      options.mediatailor === true ? {} : options.mediatailor || {};
+
+    // Initialize state
+    this.streamType = null; // 'vod' or 'live'
+    this.manifestFormat = null; // 'hls' or 'dash'
+    this.playbackManifestUrl = player.currentSrc();
+
+    // trackingUrl: optional override for the MediaTailor tracking endpoint.
+    // When not provided, the tracker derives it automatically from the playback URL.
+    this.explicitTrackingUrl = mtOptions.trackingUrl || null;
+
+    // adSegmentPrefix: only needed when the customer configured a CDN ad-segment
+    // prefix in AWS MediaTailor that does NOT follow the AWS-recommended /tm/ path.
+    // Most setups (default AWS hostname or CDN following AWS conventions) are
+    // detected automatically via MT_DEFAULT_AD_SEGMENT_PATH ('/tm/') and do not
+    // need this override.
+    this.adSegmentPrefix = mtOptions.adSegmentPrefix || null;
+
+    if (this.adSegmentPrefix) {
+      Log.debug(`[MT] ad segment detection: custom prefix "${this.adSegmentPrefix}"`);
+    } else {
+      Log.debug('[MT] ad segment detection: default (segments.mediatailor hostname or /tm/ path)');
+    }
+
+    // Ad tracking state
+    this.adSchedule = [];
+    this.currentAdBreak = null;
+    this.currentAdPod = null;
+    this.hasEndedContent = false;
+
+    // Disposal and abort state
+    this.isDisposed = false;
+    this.trackingAbortController = null;
+    this.manifestAbortController = null;
+    this.isFetchingTracking = false;
+    this.isFetchingManifest = false;
+
+    // Tracking API state
+    this.trackingEndpointUrl = null;
+    this.hasAttemptedTrackingFetch = false;
+    this.trackingFetchRetries = 0;
+    this.maxTrackingRetries = 1;
+
+    // Live polling timers
+    this.manifestPollTimer = null;
+    this.trackingPollTimer = null;
+    this.liveRefreshIntervalSeconds = null;
+
+    // Manifest parsing cache
+    this.mediaPlaylistUrl = null;
+    this.lastMediaPlaylistText = null;
+
+    Log.debug(`[MT - ${getTimestamp()}] MediaTailorAdsTracker initialized`, {
+      endpoint: this.playbackManifestUrl,
+      trackingAPITimeout: TRACKING_API_TIMEOUT_MS,
+    });
+
+    this.manifestFormat = detectManifestFormatFromUrl(this.playbackManifestUrl);
+    Log.debug(
+      `[MT - ${getTimestamp()}] Manifest type: ${this.manifestFormat.toUpperCase()}`,
+    );
+
+    this.player.one('loadedmetadata', () => {
+      this.streamType = detectPlaybackStreamType(this.player.duration());
+      Log.debug(
+        `[MT - ${getTimestamp()}] Stream type: ${this.streamType.toUpperCase()}`,
+      );
+      this.initializeTracking();
+    });
+  }
+
+  /**
+   * Initializes tracking based on detected stream type
+   */
+  initializeTracking() {
+    Log.debug(
+      `[MT - ${getTimestamp()}] Initializing ${this.manifestFormat.toUpperCase()} ${this.streamType.toUpperCase()} tracking`,
+    );
+
+    // Prefer explicit tracking URL (explicit POST session) over derived one
+    this.trackingEndpointUrl =
+      this.explicitTrackingUrl ||
+      buildTrackingEndpointUrl(this.playbackManifestUrl);
+    if (this.trackingEndpointUrl) {
+      Log.debug(
+        `[MT - ${getTimestamp()}] Tracking URL extracted:`,
+        this.trackingEndpointUrl,
+      );
+    } else {
+      Log.warn(
+        `[MT - ${getTimestamp()}] Could not derive tracking URL from playback URL — pass trackingUrl in mediatailor options if needed`,
+      );
+    }
+
+    // Set up format-specific tracking
+    if (this.streamType === STREAM_TYPE.VOD) {
+      this.setupVODTracking();
+    } else {
+      this.setupLiveTracking();
+    }
+  }
+
+  /**
+   * Register listeners (overrides parent class method)
+   */
+  registerListeners() {
+    super.registerListeners();
+
+    // Bind before registering — super(player) calls registerListeners() before
+    // the constructor body runs, so bindings must happen here, not in the constructor.
+    this.onPause = this.onPause.bind(this);
+    this.onPlaying = this.onPlaying.bind(this);
+    this.onSeeking = this.onSeeking.bind(this);
+    this.onSeeked = this.onSeeked.bind(this);
+    this.onWaiting = this.onWaiting.bind(this);
+    this.onEnded = this.onEnded.bind(this);
+    this.onTimeUpdate = this.onTimeUpdate.bind(this);
+
+    this.player.on('pause', this.onPause);
+    this.player.on('playing', this.onPlaying);
+    this.player.on('seeking', this.onSeeking);
+    this.player.on('seeked', this.onSeeked);
+    this.player.on('waiting', this.onWaiting);
+    this.player.on('ended', this.onEnded);
+    this.player.on('timeupdate', this.onTimeUpdate);
+    Log.debug(`[MT - ${getTimestamp()}] Event listeners registered`);
+  }
+
+  /**
+   * Unregister listeners (overrides parent class method)
+   */
+  unregisterListeners() {
+    super.unregisterListeners();
+    this.player.off('pause', this.onPause);
+    this.player.off('playing', this.onPlaying);
+    this.player.off('seeking', this.onSeeking);
+    this.player.off('seeked', this.onSeeked);
+    this.player.off('waiting', this.onWaiting);
+    this.player.off('ended', this.onEnded);
+    this.player.off('timeupdate', this.onTimeUpdate);
+    this.stopLivePolling();
+  }
+
+  /**
+   * Stops live polling timers
+   */
+  stopLivePolling() {
+    if (this.manifestPollTimer) {
+      clearTimeout(this.manifestPollTimer);
+      this.manifestPollTimer = null;
+    }
+
+    if (this.trackingPollTimer) {
+      clearInterval(this.trackingPollTimer);
+      this.trackingPollTimer = null;
+    }
+  }
+
+  /**
+   * Sets up VOD tracking (single parse, no polling)
+   */
+  setupVODTracking() {
+    Log.debug(`[MT - ${getTimestamp()}] VOD mode: Single manifest parse`);
+    this.hookPlayerManifest();
+  }
+
+  /**
+   * Sets up Live tracking (continuous polling)
+   */
+  setupLiveTracking() {
+    Log.debug(`[MT - ${getTimestamp()}] Live mode: Continuous polling`);
+    this.hookPlayerManifest();
+
+    const pollingInterval = this.getLiveRefreshIntervalMs();
+
+    // Start polling timers
+    this.manifestPollTimer = setInterval(() => {
+      this.pollManifestForNewAds();
+    }, pollingInterval);
+
+    this.trackingPollTimer = setInterval(() => {
+      this.getAndProcessTrackingMetadata();
+    }, pollingInterval);
+
+    Log.debug(`[MT - ${getTimestamp()}] Live polling started`, {
+      pollingInterval,
+    });
+  }
+
+  /**
+   * Returns the live polling interval in milliseconds
+   */
+  getLiveRefreshIntervalMs() {
+    return this.liveRefreshIntervalSeconds
+      ? this.liveRefreshIntervalSeconds * 1000
+      : DEFAULT_LIVE_POLL_INTERVAL_MS;
+  }
+
+  /**
+   * Updates live polling intervals after manifest metadata is detected
+   */
+  restartLivePollingTimers() {
+    if (!this.liveRefreshIntervalSeconds) return;
+
+    const newInterval = this.getLiveRefreshIntervalMs();
+    Log.debug(
+      `[MT - ${getTimestamp()}] Updating live polling interval: ${this.liveRefreshIntervalSeconds}s`,
+    );
+
+    // Restart timers with new interval
+    if (this.manifestPollTimer) clearInterval(this.manifestPollTimer);
+    if (this.trackingPollTimer) clearInterval(this.trackingPollTimer);
+
+    this.manifestPollTimer = setInterval(() => {
+      this.pollManifestForNewAds();
+    }, newInterval);
+
+    this.trackingPollTimer = setInterval(() => {
+      this.getAndProcessTrackingMetadata();
+    }, newInterval);
+  }
+
+  /**
+   * Hooks into player's manifest loading (zero race condition)
+   * Supports: VHS, Native HLS, contrib-hls, Shaka, dash.js
+   */
+  hookPlayerManifest() {
+    const tech = this.player.tech({ IWillNotUseThisInPlugins: true });
+    if (!tech) {
+      Log.debug(`[MT - ${getTimestamp()}] No tech - using fallback fetch`);
+      this.getManifestDirectly();
+      return;
+    }
+
+    // Try hooks in order of preference
+    if (this.manifestFormat === MANIFEST_TYPE.HLS) {
+      if (
+        this.hookHLSViaVHS(tech) ||
+        this.hookHLSViaNative(tech) ||
+        this.hookHLSViaContribHls(tech)
+      ) {
+        return; // Successfully hooked
+      }
+    } else if (this.manifestFormat === MANIFEST_TYPE.DASH) {
+      if (this.hookDASHViaShaka(tech) || this.hookDASHViaDashJs(tech)) {
+        return; // Successfully hooked
+      }
+    }
+
+    // Fallback: Direct manifest fetch
+    Log.debug(
+      `[MT - ${getTimestamp()}] Using fallback: direct manifest fetch`,
+    );
+    this.getManifestDirectly();
+  }
+
+  /**
+   * Hook: VHS (videojs-http-streaming) - Video.js 7.0+
+   */
+  hookHLSViaVHS(tech) {
+    if (!tech.vhs || !tech.vhs.playlists) return false;
+
+    Log.debug(`[MT - ${getTimestamp()}] Hooked: VHS`);
+
+    // Parse already-loaded playlist
+    const currentPlaylist = tech.vhs.playlists.media();
+    if (
+      currentPlaylist &&
+      currentPlaylist.segments &&
+      currentPlaylist.segments.length > 0
+    ) {
+      Log.debug(`[MT - ${getTimestamp()}] Parsing existing playlist`);
+      this.parseVhsPlaylistForAdBreaks(currentPlaylist);
+    }
+
+    // Hook future playlist loads
+    tech.vhs.on('loadedplaylist', () => {
+      const playlist = tech.vhs.playlists.media();
+      if (playlist) {
+        this.parseVhsPlaylistForAdBreaks(playlist);
+      }
+    });
+
+    return true;
+  }
+
+  /**
+   * Hook: Native HLS (Safari)
+   */
+  hookHLSViaNative(tech) {
+    // Safari uses native HLS - can't hook directly
+    if (
+      tech.el_ &&
+      tech.el_.canPlayType &&
+      tech.el_.canPlayType(HLS_MIME_TYPE)
+    ) {
+      Log.debug(
+        `[MT - ${getTimestamp()}] Native HLS detected - using fallback`,
+      );
+      this.getManifestDirectly();
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Hook: videojs-contrib-hls (legacy Video.js 5.x/6.x)
+   */
+  hookHLSViaContribHls(tech) {
+    if (!tech.hls || !tech.hls.playlists) return false;
+
+    Log.debug(`[MT - ${getTimestamp()}] Hooked: contrib-hls (legacy)`);
+
+    // Parse already-loaded playlist
+    const currentPlaylist = tech.hls.playlists.media();
+    if (
+      currentPlaylist &&
+      currentPlaylist.segments &&
+      currentPlaylist.segments.length > 0
+    ) {
+      this.parseVhsPlaylistForAdBreaks(currentPlaylist);
+    }
+
+    // Hook future playlist loads
+    tech.hls.on('loadedplaylist', () => {
+      const playlist = tech.hls.playlists.media();
+      if (playlist) {
+        this.parseVhsPlaylistForAdBreaks(playlist);
+      }
+    });
+
+    return true;
+  }
+
+  /**
+   * Hook: Shaka Player (DASH)
+   */
+  hookDASHViaShaka(tech) {
+    if (!tech.shakaPlayer) return false;
+
+    Log.debug(`[MT - ${getTimestamp()}] Hooked: Shaka Player`);
+    tech.shakaPlayer.addEventListener('emsg', (event) => {
+      this.handleDASHEmsgEvent(event);
+    });
+
+    return true;
+  }
+
+  /**
+   * Hook: dash.js (DASH)
+   */
+  hookDASHViaDashJs(tech) {
+    if (!tech.dash || !tech.dash.on) return false;
+
+    Log.debug(`[MT - ${getTimestamp()}] Hooked: dash.js`);
+    tech.dash.on('EVENT_MODE_ON_RECEIVE', (event) => {
+      this.handleDASHEventStream(event);
+    });
+
+    return true;
+  }
+
+  /**
+   * Fetches manifest directly (fallback when hooks unavailable)
+   */
+  async getManifestDirectly() {
+    Log.debug(
+      `[MT - ${getTimestamp()}] Fallback: fetching manifest directly`,
+    );
+
+    try {
+      const manifestUrl = this.playbackManifestUrl;
+
+      if (this.manifestFormat === MANIFEST_TYPE.HLS) {
+        await this.fetchAndParseHlsManifest(manifestUrl);
+      } else if (this.manifestFormat === MANIFEST_TYPE.DASH) {
+        await this.fetchAndParseDashManifest(manifestUrl);
+      }
+    } catch (error) {
+      Log.debug(`[MT - ${getTimestamp()}] Fallback fetch error:`, error);
+    }
+  }
+
+  /**
+   * Fetches and parses HLS master + media manifest
+   */
+  async fetchAndParseHlsManifest(manifestUrl) {
+    try {
+      Log.debug(`[MT - ${getTimestamp()}] Fetching HLS master manifest`);
+
+      // Fetch master manifest
+      const { mediaPlaylistUrl } = await fetchHlsMasterManifest(manifestUrl);
+
+      if (!mediaPlaylistUrl) {
+        Log.debug(`[MT - ${getTimestamp()}] No media playlist found`);
+        return;
+      }
+
+      Log.debug(`[MT - ${getTimestamp()}] Fetching media playlist`);
+
+      // Fetch media playlist
+      const mediaText = await fetchHlsMediaPlaylist(mediaPlaylistUrl);
+
+      const hlsTargetDurationSeconds = extractHlsTargetDurationSeconds(mediaText);
+      this.updateLiveRefreshIntervalFromManifest(
+        hlsTargetDurationSeconds,
+        'hls target duration',
+      );
+
+      // Parse for ads
+      const ads = parseHlsManifestForAdBreaks(mediaText);
+      if (ads.length > 0) {
+        Log.debug(
+          `[MT - ${getTimestamp()}] Detected ${ads.length} ad break(s)`,
+        );
+        this.mergeNewAds(ads);
+      }
+    } catch (error) {
+      Log.debug(`[MT - ${getTimestamp()}] HLS fetch error:`, error);
+    }
+  }
+
+  /**
+   * Fetches and parses DASH MPD manifest
+   */
+  async fetchAndParseDashManifest(manifestUrl) {
+    try {
+      Log.debug(`[MT - ${getTimestamp()}] Fetching DASH manifest`);
+
+      // Fetch DASH manifest
+      const xmlText = await fetchDashManifest(manifestUrl);
+
+      const dashMinimumUpdatePeriodSeconds =
+        extractDashMinimumUpdatePeriodSeconds(xmlText);
+      this.updateLiveRefreshIntervalFromManifest(
+        dashMinimumUpdatePeriodSeconds,
+        'dash minimumUpdatePeriod',
+      );
+
+      // Parse for ads
+      const ads = parseDashManifestForAdBreaks(xmlText);
+
+      Log.debug(
+        `[MT - ${getTimestamp()}] DASH: ${ads.length} ad break(s) found`,
+      );
+
+      if (ads.length > 0) {
+        this.mergeNewAds(ads); // also triggers tracking fetch
+      } else if (
+        this.streamType === STREAM_TYPE.VOD &&
+        this.trackingEndpointUrl &&
+        !this.hasAttemptedTrackingFetch
+      ) {
+        // No SCTE-35 markers in manifest - fall back to tracking API directly
+        Log.debug(
+          `[MT - ${getTimestamp()}] DASH: no manifest cues, fetching tracking API`,
+        );
+        this.hasAttemptedTrackingFetch = true;
+        this.getAndProcessTrackingMetadata();
+      }
+    } catch (error) {
+      Log.debug(`[MT - ${getTimestamp()}] DASH fetch error:`, error);
+    }
+  }
+
+  /**
+   * Handles DASH emsg events from Shaka Player
+   */
+  handleDASHEmsgEvent(event) {
+    Log.debug(`[MT - ${getTimestamp()}] DASH emsg event:`, event);
+
+    try {
+      // Shaka Player emits emsg events with event.detail containing the emsg box data
+      const emsgData = event.detail;
+
+      if (!emsgData) {
+        Log.debug(`[MT - ${getTimestamp()}] No emsg data in event`);
+        return;
+      }
+
+      // Check if this is a SCTE-35 event
+      // schemeIdUri for SCTE-35: urn:scte:scte35:2013:bin or urn:scte:scte35:2014:xml
+      const schemeIdUri = emsgData.schemeIdUri || '';
+
+      if (!schemeIdUri.includes(SCTE35_SCHEME_MARKER)) {
+        Log.debug(
+          `[MT - ${getTimestamp()}] Non-SCTE-35 emsg, skipping:`,
+          schemeIdUri,
+        );
+        return;
+      }
+
+      Log.debug(`[MT - ${getTimestamp()}] SCTE-35 emsg detected:`, {
+        schemeIdUri: emsgData.schemeIdUri,
+        value: emsgData.value,
+        timescale: emsgData.timescale,
+        presentationTime: emsgData.presentationTime,
+        presentationTimeDelta: emsgData.presentationTimeDelta,
+        eventDuration: emsgData.eventDuration,
+      });
+
+      // Calculate start time in seconds
+      const timescale = emsgData.timescale || 1;
+      const presentationTime = emsgData.presentationTime || 0;
+      const eventDuration = emsgData.eventDuration || 0;
+
+      const startTime = presentationTime / timescale;
+      const duration = eventDuration / timescale;
+
+      // Parse SCTE-35 message data
+      const messageData = emsgData.messageData;
+
+      if (messageData && duration > 0) {
+        const adBreak = {
+          id: `dash-emsg-${startTime}`,
+          startTime: startTime,
+          duration: duration,
+          endTime: startTime + duration,
+          source: 'dash-emsg',
+          confirmedByTracking: false,
+          hasFiredStart: false,
+          hasFiredEnd: false,
+          hasFiredAdStart: false,
+          pods: [],
+        };
+
+        Log.debug(
+          `[MT - ${getTimestamp()}] Adding ad break from DASH emsg:`,
+          adBreak,
+        );
+        this.mergeNewAds([adBreak]);
+      }
+    } catch (error) {
+      Log.debug(
+        `[MT - ${getTimestamp()}] Error parsing DASH emsg event:`,
+        error,
+      );
+    }
+  }
+
+  /**
+   * Handles DASH event stream from dash.js
+   */
+  handleDASHEventStream(event) {
+    Log.debug(`[MT - ${getTimestamp()}] DASH event stream:`, event);
+
+    try {
+      // dash.js emits events with different structure
+      const eventData = event.event || event;
+
+      if (!eventData) {
+        Log.debug(`[MT - ${getTimestamp()}] No event data`);
+        return;
+      }
+
+      // Check if this is a SCTE-35 event
+      const schemeIdUri = eventData.schemeIdUri || '';
+
+      if (!schemeIdUri.includes(SCTE35_SCHEME_MARKER)) {
+        Log.debug(
+          `[MT - ${getTimestamp()}] Non-SCTE-35 event, skipping:`,
+          schemeIdUri,
+        );
+        return;
+      }
+
+      Log.debug(`[MT - ${getTimestamp()}] SCTE-35 event stream detected:`, {
+        id: eventData.id,
+        schemeIdUri: eventData.schemeIdUri,
+        presentationTime: eventData.presentationTime,
+        duration: eventData.duration,
+        messageData: eventData.messageData,
+      });
+
+      // Calculate timing
+      const startTime = parseFloat(eventData.presentationTime || 0);
+      const duration = parseFloat(eventData.duration || 0);
+
+      if (duration > 0) {
+        const adBreak = {
+          id: eventData.id || `dash-event-${startTime}`,
+          startTime: startTime,
+          duration: duration,
+          endTime: startTime + duration,
+          source: 'dash-event-stream',
+          confirmedByTracking: false,
+          hasFiredStart: false,
+          hasFiredEnd: false,
+          hasFiredAdStart: false,
+          pods: [],
+        };
+
+        Log.debug(
+          `[MT - ${getTimestamp()}] Adding ad break from DASH event stream:`,
+          adBreak,
+        );
+        this.mergeNewAds([adBreak]);
+      }
+    } catch (error) {
+      Log.debug(
+        `[MT - ${getTimestamp()}] Error parsing DASH event stream:`,
+        error,
+      );
+    }
+  }
+
+  /**
+   * Parses VHS playlist object for ads
+   */
+  parseVhsPlaylistForAdBreaks(playlist) {
+    Log.debug(
+      `[MT - ${getTimestamp()}] Parsing VHS playlist (${
+        playlist.segments?.length || 0
+      } segments)`,
+    );
+
+    if (!playlist.segments || playlist.segments.length === 0) {
+      Log.debug(`[MT - ${getTimestamp()}] No segments in playlist`);
+      return;
+    }
+
+    this.updateLiveRefreshIntervalFromManifest(
+      playlist.targetDuration,
+      'vhs target duration',
+    );
+
+    // VHS strips CUE tags - detect via discontinuityStarts + MediaTailor segments
+    const ads = detectAdBreaksFromVhsPlaylist(playlist, {
+      adSegmentPrefix: this.adSegmentPrefix,
+    });
+
+    if (ads.length > 0) {
+      // Log which detection path matched — only on first detection to avoid noise
+      if (!this._detectionPathLogged) {
+        const firstSeg = playlist.segments && playlist.segments.find(s =>
+          whichAdSegmentMarker(s, { adSegmentPrefix: this.adSegmentPrefix })
+        );
+        if (firstSeg) {
+          const path = whichAdSegmentMarker(firstSeg, { adSegmentPrefix: this.adSegmentPrefix });
+          Log.debug(`[MT] ad segment detection matched via: ${path}`);
+          this._detectionPathLogged = true;
+        }
+      }
+      Log.debug(
+        `[MT - ${getTimestamp()}] VHS detected ${ads.length} ad break(s), ${ads.reduce(
+          (sum, ab) => sum + ab.pods.length,
+          0,
+        )} pod(s)`,
+      );
+      this.mergeNewAds(ads);
+    } else {
+      Log.debug(`[MT - ${getTimestamp()}] No ads detected in VHS playlist`);
+    }
+  }
+
+  /**
+   * Polls manifest for new ads (Live streams only)
+   */
+  async pollManifestForNewAds() {
+    if (this.isDisposed) return;
+    if (this.streamType !== STREAM_TYPE.LIVE) return;
+
+    if (this.isFetchingManifest) {
+      Log.debug(
+        `[MT - ${getTimestamp()}] Manifest fetch already in progress, skipping`,
+      );
+      return;
+    }
+
+    this.isFetchingManifest = true;
+
+    try {
+      const tech = this.player.tech({ IWillNotUseThisInPlugins: true });
+      if (tech && tech.vhs) {
+        const playlist = tech.vhs.playlists.media();
+        if (playlist) {
+          this.parseVhsPlaylistForAdBreaks(playlist);
+        }
+      } else if (this.manifestFormat === MANIFEST_TYPE.DASH) {
+        await this.fetchAndParseDashManifest(this.playbackManifestUrl);
+      }
+    } catch (error) {
+      Log.debug(`[MT - ${getTimestamp()}] Manifest poll error:`, error);
+    } finally {
+      this.isFetchingManifest = false;
+    }
+  }
+
+  /**
+   * Merges new ads into schedule (deduplicates)
+   */
+  mergeNewAds(newAds) {
+    this.adSchedule = mergeAdSchedules(this.adSchedule, newAds);
+
+    Log.debug(
+      `[MT - ${getTimestamp()}] Ad schedule: ${this.adSchedule.length} ad break(s)`,
+    );
+
+    // VOD: Fetch tracking metadata after first manifest parse (AWS best practice)
+    if (
+      this.streamType === STREAM_TYPE.VOD &&
+      this.trackingEndpointUrl &&
+      !this.hasAttemptedTrackingFetch
+    ) {
+      this.hasAttemptedTrackingFetch = true;
+      Log.debug(
+        `[MT - ${getTimestamp()}] Fetching tracking metadata (first manifest parse)`,
+      );
+      this.getAndProcessTrackingMetadata();
+    }
+  }
+
+  /**
+   * Updates live polling cadence from manifest-derived metadata
+   */
+  updateLiveRefreshIntervalFromManifest(intervalSeconds, source) {
+    if (
+      this.streamType !== STREAM_TYPE.LIVE ||
+      !intervalSeconds ||
+      intervalSeconds <= 0
+    ) {
+      return;
+    }
+
+    if (this.liveRefreshIntervalSeconds === intervalSeconds) {
+      return;
+    }
+
+    this.liveRefreshIntervalSeconds = intervalSeconds;
+    Log.debug(
+      `[MT - ${getTimestamp()}] Derived live polling interval from ${source}: ${intervalSeconds}s`,
+    );
+
+    if (this.manifestPollTimer || this.trackingPollTimer) {
+      this.restartLivePollingTimers();
+    }
+  }
+
+  /**
+   * Fetches and processes tracking metadata from AWS MediaTailor Tracking API
+   */
+  async getAndProcessTrackingMetadata() {
+    if (this.isDisposed || !this.trackingEndpointUrl) return;
+
+    if (this.isFetchingTracking) {
+      Log.debug(
+        `[MT - ${getTimestamp()}] Tracking fetch already in progress, skipping`,
+      );
+      return;
+    }
+
+    this.isFetchingTracking = true;
+
+    try {
+      Log.debug(`[MT - ${getTimestamp()}] Fetching tracking metadata`);
+
+      this.trackingAbortController = new AbortController();
+
+      const data = await getTrackingMetadata(
+        this.trackingEndpointUrl,
+        TRACKING_API_TIMEOUT_MS,
+        this.trackingAbortController.signal,
+      );
+
+      if (this.isDisposed) {
+        Log.debug(
+          `[MT - ${getTimestamp()}] Disposed during tracking fetch, ignoring result`,
+        );
+        return;
+      }
+
+      if (data.avails && data.avails.length > 0) {
+        Log.debug(
+          `[MT - ${getTimestamp()}] Enriching with ${data.avails.length} avail(s)`,
+        );
+        this.enrichWithTrackingMetadata(data.avails);
+        this.trackingFetchRetries = 0;
+      } else {
+        Log.debug(`[MT - ${getTimestamp()}] Tracking API returned 0 avails`);
+      }
+    } catch (error) {
+      if (error.name === 'AbortError' || this.isDisposed) {
+        Log.debug(`[MT - ${getTimestamp()}] Tracking fetch aborted`);
+        return;
+      }
+
+      Log.debug(
+        `[MT - ${getTimestamp()}] Tracking API error: ${error.message}`,
+        error,
+      );
+
+      if (this.trackingFetchRetries < this.maxTrackingRetries) {
+        this.trackingFetchRetries++;
+        Log.debug(
+          `[MT - ${getTimestamp()}] Retrying tracking fetch (${this.trackingFetchRetries}/${this.maxTrackingRetries})`,
+        );
+        this.isFetchingTracking = false;
+        await this.getAndProcessTrackingMetadata();
+        return;
+      }
+
+      Log.debug(
+        `[MT - ${getTimestamp()}] Max retries reached, continuing with manifest data only`,
+      );
+    } finally {
+      this.isFetchingTracking = false;
+      this.trackingAbortController = null;
+    }
+  }
+
+  /**
+   * Enriches ad schedule with tracking API metadata
+   */
+  enrichWithTrackingMetadata(avails) {
+    const newAds = enrichAdScheduleWithTrackingMetadata(this.adSchedule, avails);
+
+    // Add any new ads from tracking
+    if (newAds.length > 0) {
+      this.adSchedule.push(...newAds);
+      this.adSchedule.sort((a, b) => a.startTime - b.startTime);
+    }
+
+    Log.debug(
+      `[MT - ${getTimestamp()}] Enrichment complete: ${
+        this.adSchedule.length
+      } ad break(s)`,
+    );
+
+    // Log enriched schedule with full details
+    Log.debug(
+      `[MT - ${getTimestamp()}] Enriched schedule:`,
+      this.adSchedule.map((ab) => ({
+        id: ab.id,
+        startTime: ab.startTime,
+        endTime: ab.endTime,
+        duration: ab.duration,
+        title: ab.title,
+        podCount: ab.pods.length,
+        pods: ab.pods.map((p) => ({
+          title: p.title,
+          startTime: p.startTime,
+          endTime: p.endTime,
+          duration: p.duration,
+        })),
+      })),
+    );
+
+    // Log current player time for debugging
+    Log.debug(
+      `[MT - ${getTimestamp()}] Current player time: ${this.player.currentTime()}s`,
+    );
+  }
+
+  /**
+   * Tracks quartile events for active pod/ad
+   */
+  trackQuartiles(adObject, progress) {
+    if (!adObject.duration || adObject.duration <= 0) return;
+
+    const quartilesToFire = getQuartilesToFire(progress, adObject.duration, {
+      q1: adObject.hasFiredQ1,
+      q2: adObject.hasFiredQ2,
+      q3: adObject.hasFiredQ3,
+    });
+
+    quartilesToFire.forEach(({ quartile, key }) => {
+      Log.debug(`[MT - ${getTimestamp()}] → AD_QUARTILE ${quartile * 25}%`);
+      this.sendAdQuartile({ quartile });
+      adObject[`hasFired${key.toUpperCase()}`] = true;
+    });
+  }
+
+  /**
+   * Called on timeupdate - main event tracking logic
+   */
+  onTimeUpdate() {
+    const currentTime = this.player.currentTime();
+    const activeAdBreak = findActiveAdBreak(this.adSchedule, currentTime);
+
+    // Debug logging (only log when schedule exists and every 5 seconds)
+    if (
+      this.adSchedule.length > 0 &&
+      Math.floor(currentTime) % 5 === 0 &&
+      Math.floor(currentTime * 10) % 10 === 0
+    ) {
+      Log.debug(
+        `[MT - ${getTimestamp()}] TimeUpdate: ${currentTime.toFixed(2)}s, Active break: ${
+          activeAdBreak ? activeAdBreak.id : 'none'
+        }, Schedule count: ${this.adSchedule.length}`,
+      );
+    }
+
+    if (activeAdBreak) {
+      // === INSIDE AD BREAK ===
+
+      // Fire AD_BREAK_START once
+      if (!activeAdBreak.hasFiredStart) {
+        this.currentAdBreak = activeAdBreak;
+        this.setIsAd(true); // Switch to ad mode
+        Log.debug(
+          `[MT - ${getTimestamp()}] setIsAd(true) - Entering ad break`,
+        );
+
+        // Calculate ad position by finding index based on startTime
+        const adBreakIndex = this.adSchedule.findIndex(
+          (ad) => Math.abs(ad.startTime - activeAdBreak.startTime) < 0.5,
+        );
+        const adPosition = determineAdPosition(
+          adBreakIndex,
+          this.adSchedule.length,
+          this.streamType,
+        );
+
+        // Store position on the ad break for reuse
+        activeAdBreak.adPosition = adPosition;
+
+        Log.debug(`[MT - ${getTimestamp()}] → AD_BREAK_START`, {
+          startTime: activeAdBreak.startTime,
+          duration: activeAdBreak.duration,
+          podCount: activeAdBreak.pods?.length || 0,
+          position: adPosition,
+          breakIndex: adBreakIndex,
+          totalBreaks: this.adSchedule.length,
+        });
+        this.sendAdBreakStart();
+        activeAdBreak.hasFiredStart = true;
+      }
+
+      // Check for pod-level tracking
+      if (activeAdBreak.pods && activeAdBreak.pods.length > 0) {
+        const activePod = findActivePod(activeAdBreak, currentTime);
+
+        if (activePod) {
+          // Entering new pod
+          if (!this.currentAdPod || this.currentAdPod !== activePod) {
+            // End previous pod
+            if (this.currentAdPod) {
+              Log.debug(`[MT - ${getTimestamp()}] → AD_END (pod transition)`);
+              this.sendEnd();
+            }
+
+            // Start new pod
+            this.currentAdPod = activePod;
+
+            Log.debug(`[MT - ${getTimestamp()}] → AD_START (new pod)`, {
+              startTime: activePod.startTime,
+              duration: activePod.duration,
+              position: activeAdBreak.adPosition,
+            });
+
+            // NOTE: If the tracking API was slow to respond, the no-pods path
+            // (below) will have already called sendStart() on this break.
+            // Calling sendStart() again here is intentional — video-core's state
+            // machine suppresses duplicate AD_START transitions (AD_START →
+            // AD_START is a no-op), so nothing double-fires in New Relic. Once
+            // pods are populated by the tracking API, this path takes over and
+            // provides pod-level metadata (title, duration, creativeId) for all
+            // subsequent events in the break.
+            this.sendRequest({
+              adPartner: 'aws-mediatailor',
+              adPosition: activeAdBreak.adPosition,
+            });
+
+            this.sendStart({
+              adPartner: 'aws-mediatailor',
+              adPosition: activeAdBreak.adPosition,
+            });
+            activePod.hasFiredStart = true;
+          }
+
+          // Track quartiles for pod
+          const podProgress = currentTime - activePod.startTime;
+          this.trackQuartiles(activePod, podProgress);
+        }
+      } else {
+        // No pods - treat entire break as single ad
+        if (!activeAdBreak.hasFiredAdStart) {
+          Log.debug(`[MT - ${getTimestamp()}] → AD_START (no pods)`, {
+            startTime: activeAdBreak.startTime,
+            duration: activeAdBreak.duration,
+            position: activeAdBreak.adPosition,
+          });
+
+          // Send AD_REQUEST before AD_START (required sequence)
+          this.sendRequest({
+            adPartner: 'aws-mediatailor',
+            adPosition: activeAdBreak.adPosition,
+          });
+
+          // Send AD_START
+          this.sendStart({
+            adPartner: 'aws-mediatailor',
+            adPosition: activeAdBreak.adPosition,
+          });
+          activeAdBreak.hasFiredAdStart = true;
+        }
+
+        // Track quartiles for entire break
+        const adProgress = currentTime - activeAdBreak.startTime;
+        this.trackQuartiles(activeAdBreak, adProgress);
+      }
+    } else if (this.currentAdBreak) {
+      // === EXITING AD BREAK ===
+
+      // End last pod
+      if (this.currentAdPod) {
+        Log.debug(`[MT - ${getTimestamp()}] → AD_END (final pod)`);
+        this.sendEnd();
+        this.currentAdPod = null;
+      }
+
+      // End ad break
+      if (!this.currentAdBreak.hasFiredEnd) {
+        Log.debug(`[MT - ${getTimestamp()}] → AD_BREAK_END`);
+        this.sendAdBreakEnd();
+        this.currentAdBreak.hasFiredEnd = true;
+      }
+
+      this.currentAdBreak = null;
+      this.setIsAd(false); // Switch back to content mode
+      Log.debug(`[MT - ${getTimestamp()}] setIsAd(false) - Exiting ad break`);
+
+      // Check if video has ended after exiting last ad break
+      if (this.player.ended() && !this.hasEndedContent) {
+        Log.debug(
+          `[MT - ${getTimestamp()}] Video ended after last ad → CONTENT_END`,
+        );
+        this.sendContentEnd();
+        this.hasEndedContent = true;
+      }
+    }
+  }
+
+  /**
+   * Sends CONTENT_END event via parent content tracker
+   */
+  sendContentEnd() {
+    if (this.parentTracker) {
+      this.parentTracker.sendEnd();
+    } else {
+      super.sendEnd();
+    }
+  }
+
+  /**
+   * Generic handler for ad events - only fires if currently in an ad break
+   * @param {string} eventName - The event name for logging (e.g., 'AD_PAUSE')
+   * @param {Function} sendMethod - The method to call (e.g., this.sendPause)
+   */
+  handleAdEvent(eventName, sendMethod) {
+    if (this.isAd()) {
+      Log.debug(`[MT - ${getTimestamp()}] → ${eventName}`);
+      sendMethod.call(this);
+    }
+  }
+
+  /**
+   * Handle pause events - sends AD_PAUSE only when ads are playing
+   */
+  onPause() {
+    this.handleAdEvent('AD_PAUSE', this.sendPause);
+  }
+
+  /**
+   * Handle playing events - sends AD_RESUME only when ads are playing
+   */
+  onPlaying() {
+    if (this.isAd()) {
+      Log.debug(`[MT - ${getTimestamp()}] → AD_RESUME`);
+      this.sendResume();
+      this.sendBufferEnd(); // Playing event also ends any buffering
+    }
+  }
+
+  /**
+   * Handle seeking events - sends AD_SEEK_START only when ads are playing
+   */
+  onSeeking() {
+    this.handleAdEvent('AD_SEEK_START', this.sendSeekStart);
+  }
+
+  /**
+   * Handle seeked events - sends AD_SEEK_END only when ads are playing
+   */
+  onSeeked() {
+    this.handleAdEvent('AD_SEEK_END', this.sendSeekEnd);
+  }
+
+  /**
+   * Handle waiting (buffering) events - sends AD_BUFFER_START only when ads are playing
+   */
+  onWaiting() {
+    this.handleAdEvent('AD_BUFFER_START', this.sendBufferStart);
+  }
+
+  /**
+   * Override: Fire CONTENT_END when video ends
+   */
+  onEnded() {
+    if (!this.hasEndedContent) {
+      Log.debug(`[MT - ${getTimestamp()}] Video ended → CONTENT_END`);
+      this.sendContentEnd();
+      this.hasEndedContent = true;
+    }
+  }
+
+  /**
+   * Returns ad title for New Relic
+   */
+  getTitle() {
+    if (this.currentAdPod) {
+      return this.currentAdPod.title || this.currentAdBreak?.id || null;
+    }
+    return this.currentAdBreak?.title || this.currentAdBreak?.id || null;
+  }
+
+  /**
+   * Returns ad ID for New Relic (adId attribute)
+   */
+  getVideoId() {
+    if (this.currentAdPod) {
+      return (
+        this.currentAdPod.creativeId ||
+        this.currentAdPod.title ||
+        this.currentAdBreak?.id ||
+        null
+      );
+    }
+    return this.currentAdBreak?.creativeId || this.currentAdBreak?.id || null;
+  }
+
+  /**
+   * Returns ad source URL for New Relic (adSrc attribute)
+   */
+  getSrc() {
+    // MediaTailor doesn't provide individual creative URLs
+    return this.trackingEndpointUrl || this.playbackManifestUrl || null;
+  }
+
+  /**
+   * Returns ad duration in milliseconds for New Relic
+   */
+  getDuration() {
+    if (this.currentAdPod) {
+      return this.currentAdPod.duration * 1000;
+    }
+    return this.currentAdBreak ? this.currentAdBreak.duration * 1000 : null;
+  }
+
+  /**
+   * Stops polling timers
+   */
+  stopPolling() {
+    if (this.manifestPollTimer) {
+      clearInterval(this.manifestPollTimer);
+      this.manifestPollTimer = null;
+    }
+
+    if (this.trackingPollTimer) {
+      clearInterval(this.trackingPollTimer);
+      this.trackingPollTimer = null;
+    }
+
+    Log.debug(`[MT - ${getTimestamp()}] Polling stopped`);
+  }
+
+  /**
+   * Cleanup when tracker is destroyed
+   */
+  dispose() {
+    Log.debug(`[MT - ${getTimestamp()}] Disposing MediaTailorAdsTracker`);
+
+    this.isDisposed = true;
+
+    if (this.trackingAbortController) {
+      Log.debug(`[MT - ${getTimestamp()}] Aborting in-flight tracking fetch`);
+      this.trackingAbortController.abort();
+      this.trackingAbortController = null;
+    }
+
+    if (this.manifestAbortController) {
+      Log.debug(`[MT - ${getTimestamp()}] Aborting in-flight manifest fetch`);
+      this.manifestAbortController.abort();
+      this.manifestAbortController = null;
+    }
+
+    this.stopLivePolling();
+    this.unregisterListeners();
+    super.dispose && super.dispose();
+  }
+}