Ad and Cue Point Management

This module is responsible for coordinating the fetching, monitoring, and triggering of video advertisements and cue points during media playback. It integrates closely with the finite state machine (FSM) to enable timely ad insertions based on playback progress. By managing ad retrieval requests and cue point triggers, this module ensures a seamless user experience with video ads appearing at designated points without disrupting content playback.

Core Concepts and Purpose

• Ad Retrieval: Represents the data needed to request ads from the ad server corresponding to a specific video and cue point.

• Cue Point Retrieval: Represents the data needed to fetch cue points for a video, which indicate where ads should be inserted.

• Playback Monitoring: Watches playback progress frame-by-frame to detect when to initiate ad retrieval calls and when to actually show ads based on cue points.

This module exists to solve the challenge of timely and accurate insertion of video ads within content playback. It synchronizes ad calls and ad playback with content progress, preventing redundant calls and missed ad opportunities, while integrating with the FSM to manage state transitions accordingly.

Module Components and Workflows

1. Ad Retrieval Data Model (AdRetriever)

The `AdRetriever` class encapsulates the attributes necessary to request ads from the ad server. It contains:

• videoId — The identifier for the media content.

• publisherId — The identifier for the publisher.

• cubPoint — The cue point timestamp (in milliseconds) at which the ad should be played.

This object is updated dynamically with the current cue point during playback to request the correct set of ads aligned with the content timeline.

public class AdRetriever {
    private String videoId;
    private String publisherId;
    private long cubPoint;

    // Constructors, getters, and setters omitted for brevity
}

2. Cue Point Retrieval Data Model (CuePointsRetriever)

The `CuePointsRetriever` class holds the identifiers needed to retrieve cue points for a given video:

• videoId — Identifies the video content.

• publisherId — Identifies the publisher.

Cue points indicate the timestamps in the content where ads should be inserted (e.g., preroll, midroll, postroll).

public class CuePointsRetriever {
    private String videoId;
    private String publisherId;

    // Constructors, getters, and setters omitted for brevity
}

3. Playback Monitoring

Two key classes monitor playback to coordinate ad-related actions:

a. AdPlayingMonitor

• Observes the ad player's playback state.

• Detects when ad playback ends or errors occur.

• Upon ad completion or error, it instructs the FSM to remove the played ad and transition to the next appropriate state.

• Contains a workaround for handling corrupted ad files that cause indefinite buffering by seeking forward when video frames are dropped excessively.

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

@Override
public void onPlayerError(EventTime eventTime, ExoPlaybackException error) {
    fsmPlayer.removePlayedAdAndTransitToNextState();
}

The monitor ensures ads do not stall playback and handles errors gracefully.

b. CuePointMonitor

• Monitors the main content player's playback progress (millisecond granularity).

• Maintains arrays of cue points and corresponding ad call points (offset earlier by a "networking ahead" value to fetch ads in advance).

• Uses a binary search with a configurable range to detect when playback is near a cue point or ad call point.

• Ensures each ad call and ad display is triggered once per cue point using boolean flags (safeCheckForAdcall and safeCheckForCue).

• When the playback position reaches an ad call point, it triggers an FSM transition to make an ad network call.

• When the playback position reaches a cue point, it triggers an FSM transition to show the ad.

Key methods:

public void onMovieProgress(long milliseconds, long durationMillis) {
    if (fsmPlayer.getCurrentState() instanceof AdPlayingState || fsmPlayer.getCurrentState() instanceof VpaidState) {
        return; // Do not trigger during ad playback
    }
    preformAdCallIfNecessary(milliseconds);
    preformShowAdIfNecessary(milliseconds);
}

The monitor thus acts as a bridge between playback progress and FSM-driven ad state transitions, ensuring ads are fetched and displayed at correct times.

Interaction with Other System Parts

• FSM Player (FsmPlayer): Both monitors hold references to the FSM player instance, invoking FSM state transitions based on playback events and cue point detection.

• Ad and Content Players: AdPlayingMonitor listens to the ad player's state, while CuePointMonitor watches the content player's progress.

• Ad Retrieval Logic: When CuePointMonitor triggers an ad call, the FSM updates the AdRetriever with the current cue point to request appropriate ads.

• State Transitions: The FSM transitions between states like MakingAdCallState and AdPlayingState triggered by events from these monitors.

Important Concepts and Design Patterns

• Observer Pattern: Both monitors implement event listeners to observe ExoPlayer's playback state and progress, reacting to changes asynchronously.

• Finite State Machine Integration: Monitors do not directly handle UI or media playback but signal the FSM to transition states, keeping concerns separated.

• Safe-Check Flags: To prevent duplicate ad calls or ad displays due to frequent progress updates near cue points, boolean flags are used to ensure actions trigger only once per cue point.

• Binary Search With Range: Efficiently detects proximity to cue points within a tolerance window, allowing slight timing variations without missing triggers.

Visual Diagram: Cue Point and Ad Retrieval Workflow

flowchart TD
    ContentPlayer[Content Playback Progress]
    ContentPlayer -->|Frame by frame| CuePointMonitor
    CuePointMonitor -->|Near Ad Call Point| FSM[Finite State Machine]
    FSM -->|Make Ad Network Call| AdRetriever
    AdRetriever --> AdServer[Ad Server]
    AdServer -->|Ads Data| FSM
    FSM -->|Transition to AdPlayingState| AdPlayer[Ad Playback Player]
    AdPlayer -->|Ad Playback Progress| AdPlayingMonitor
    AdPlayingMonitor -->|Ad Finished or Error| FSM
    FSM -->|Transition to Content Playback| ContentPlayer

This diagram illustrates how the monitoring components observe playback progress, trigger ad retrieval calls, coordinate with the FSM to manage state transitions, and monitor ad playback completion to resume content playback accordingly.