Cue Point Retrieval

Purpose

Cue Point Retrieval addresses the need to identify precise timings within a video where advertisements should be inserted. Unlike ad retrieval which fetches the actual ads, this subtopic focuses on acquiring cue points—markers that signal when preroll, midroll, or postroll ads should play during content playback. Managing cue points ensures that ad insertions occur seamlessly and at the correct moments, enabling smooth transitions between content and ads.

Functionality

The core functionality revolves around the `CuePointsRetriever` class, which encapsulates the minimal data required to request cue points for a given video:

• Video Identification: Holds the videoId representing the unique content.

• Publisher Identification: Contains the publisherId to scope cue point requests.

This retriever acts as a data carrier in the process of querying the ad server or cue point provider to obtain a list of cue points associated with the video. These cue points are then used by the FSM to trigger transitions into ad-fetching or ad-playing states.

The typical workflow involves:

1. Initialization: Creation of a CuePointsRetriever instance with the relevant videoId and publisherId.

2. Request: Passing this instance to the cue point retrieval mechanism (not shown here but part of the broader system).

3. Response Handling: Receiving cue point data, which includes timestamps and metadata about where ads should be inserted.

4. FSM Notification: Forwarding cue point information to the FSM to manage playback state transitions accordingly.

// Constructing a CuePointsRetriever for a specific video and publisher
CuePointsRetriever retriever = new CuePointsRetriever("video123", "publisherXYZ");

// This retriever is then used to fetch cue points from the ad server
cuePointService.fetchCuePoints(retriever, callback);

Integration with Parent Topic and Other Subtopics

Cue Point Retrieval is a foundational element within the broader **Ad and Cue Point Management** parent topic. It complements:

• Ad Retrieval by providing the timing information needed to initiate ad fetching.

• Playback Monitoring by supplying cue points that the playback system monitors to trigger midroll ad calls.

Specifically, cue points guide the FSM player when to:

• Transition from content playback to ad retrieval states (e.g., MakingMidrollAdCallState).

• Prepare the ad player for upcoming ads.

• Resume content playback after ad completion.

This subtopic introduces the concept of encapsulating cue point request parameters in a dedicated retriever object, which keeps cue point data and retrieval logic modular and separate from ad data handling.

Diagram

flowchart TD
    A[Initialize CuePointsRetriever]
    A --> B[Send Cue Point Request]
    B --> C[Receive Cue Point Data]
    C --> D{Cue Points Present?}
    D -->|Yes| E[Notify FSM to Trigger Ad Calls]
    D -->|No| F[Continue Content Playback]
    E --> F

This flowchart illustrates the key process of cue point retrieval and how it signals the FSM player to manage ad insertions based on received cue points.