Playback Monitoring

Purpose

Playback Monitoring addresses the critical need to observe media playback progress and ad playback events in real time, to ensure timely and accurate triggering of ad-related actions within the media player. Specifically, it monitors the video playback timeline to detect when cue points are reached to initiate ad calls and ad insertions, and it observes ad playback completion or errors to transition the player state machine appropriately. This ensures seamless integration of advertisements into the content stream without disrupting the user experience.

Functionality

Playback Monitoring is realized through two specialized monitors: **CuePointMonitor** and **AdPlayingMonitor**.

• CuePointMonitor
  Continuously checks the content playback position against predefined cue points and ad call points. When the playback position nears an ad call point, it triggers an FSM transition to initiate fetching ads. When the playback reaches a cue point, it triggers an FSM transition to start ad playback. To avoid redundant triggers due to frame-by-frame checking, it employs safe-check flags that reset only after the playback moves out of the triggering range.

  Core behaviors include:

  • Binary search with a tolerance window to efficiently detect proximity to cue points.

  • Computing ad call points by subtracting a configurable networking-ahead offset from cue points, allowing prefetching of ads.

  • Invoking FSM inputs (MAKE_AD_CALL and SHOW_ADS) at appropriate times.

• AdPlayingMonitor
  Listens to the ad player's playback state changes and errors. Key tasks are:

  • Detecting when an ad finishes playing (Player.STATE_ENDED with playWhenReady == true) and notifying the FSM to remove the played ad and transit to the next state.

  • Handling playback errors by signaling the FSM to skip or recover from the error state.

  • Implementing a workaround for stuck buffering states by seeking slightly forward to recover playback on corrupted ad streams.

Key Code Snippets

**Triggering ad call and ad show in CuePointMonitor:**

if (isProgressActionable(adCallPoints, milliseconds) && safeCheckForAdcall) {
    safeCheckForAdcall = false;
    fsmPlayer.transit(Input.MAKE_AD_CALL);
}

if (isProgressActionable(cuePoints, milliseconds) && safeCheckForCue) {
    safeCheckForCue = false;
    fsmPlayer.transit(Input.SHOW_ADS);
}

**Ad playback completion handling in AdPlayingMonitor:**

@Override
public void onPlayerStateChanged(EventTime eventTime, boolean playWhenReady, int playbackState) {
    if (playbackState == Player.STATE_ENDED && playWhenReady) {
        fsmPlayer.removePlayedAdAndTransitToNextState();
    }
}

Integration

Playback Monitoring tightly integrates with the parent topic — **Ad and Cue Point Management** — by acting as the runtime observer that bridges media playback progress with ad insertion logic. While Ad Retrieval and Cue Point Retrieval focus on fetching ad metadata and cue timing data, Playback Monitoring ensures that these data points translate into timely FSM transitions.

• It complements Ad Retrieval by triggering ad fetch calls just before the cue points are reached, based on the ad call points calculated by CuePointMonitor.

• It complements Cue Point Retrieval by using the retrieved cue points to monitor playback progress and decide when to show ads.

• It interfaces directly with the FSM player (FsmPlayer) by sending input events (MAKE_AD_CALL, SHOW_ADS) and notifying about ad playback completion or errors, enabling the FSM to transition states smoothly.

• It interacts with playback controllers by listening to ExoPlayer events for both content and ads, ensuring synchronization between playback state and FSM state.

This monitoring introduces a proactive and reactive mechanism not covered in other subtopics — it acts as the real-time engine that triggers state changes based on playback progress and ad lifecycle events.

Diagram

flowchart TD
    ContentPlayer[Content Playback (ExoPlayer)]
    CuePointMonitor -->|Checks playback position| ContentPlayer
    ContentPlayer -->|Playback Progress| CuePointMonitor
    CuePointMonitor -->|Trigger MAKE_AD_CALL| FSM[FsmPlayer]
    CuePointMonitor -->|Trigger SHOW_ADS| FSM
    AdPlayer[Ad Playback (ExoPlayer)]
    AdPlayingMonitor -->|Monitors ad playback state| AdPlayer
    AdPlayer -->|Playback events| AdPlayingMonitor
    AdPlayingMonitor -->|Notify ad ended or error| FSM
    FSM -->|Controls playback| ContentPlayer
    FSM -->|Controls playback| AdPlayer

This flowchart highlights the core monitoring interactions: `CuePointMonitor` observes content playback progress to trigger ad calls and ad playback start, while `AdPlayingMonitor` observes ad playback events to notify FSM transitions. Both monitors communicate with the FSM player, which in turn controls the underlying media players.