Player UI Controller

Purpose

The Player UI Controller manages the playback user interface components and the resume state information for both content videos and advertisements. Within the broader topic of media playback and UI controls, this controller specifically addresses the challenge of coordinating multiple playback surfaces—such as separate players for content and ads or a WebView for VPAID ads—and preserving playback positions to enable smooth resumption after interruptions or ad breaks.

By encapsulating these concerns, the Player UI Controller ensures seamless transitions between content and ad playback while maintaining consistent UI state, which enhances the overall user experience and playback reliability.

Functionality

• Playback Player Management:
  Maintains references to the primary ExoPlayer instance for content, an optional separate ExoPlayer for ads, a WebView for VPAID ads, and the associated player view. It abstracts the complexity of choosing which player instance to use for ad playback, accommodating device-specific optimizations (e.g., single-player reuse on certain devices).

• Resume State Tracking:
  Tracks playback positions and windows for both content and ads independently. This includes saving and retrieving resume information, such as the current playback window index and playback position in milliseconds, enabling the system to resume playback from the last known position after interruptions, user-initiated pauses, or ads.

• Playback History Management:
  Supports storing and querying whether there is a playback history (e.g., when a user resumes watching a video from a previously saved position) and clearing that history when no longer applicable.

• Builder Pattern for Flexible Instantiation:
  Provides a nested Builder class that allows clients to configure the controller by optionally supplying the content player, ad player, VPAID WebView, and player view. This pattern supports flexible construction tailored to different playback scenarios.

Key Methods and Data Flows

• getAdPlayer() dynamically returns the appropriate player instance for ad playback, considering device-specific logic via PlayerDeviceUtils.useSinglePlayer(). This allows the system to optimize resource usage by reusing the content player when feasible.

• setPlayFromHistory(long pos) marks that playback should resume from a saved position, storing that position internally.

• setAdResumeInfo(int window, long position) and setMovieResumeInfo(int window, long position) allow saving the current playback window and position for ads and content, respectively.

• Corresponding getter methods provide access to these resume points for use during playback initialization or resumption.

• clear* methods reset resume information when playback restarts or state is invalidated.

Example snippet showing player retrieval for ads, illustrating device-adaptive behavior:

public SimpleExoPlayer getAdPlayer() {
    // Reuse content player for ad playback on single-player devices
    if (PlayerDeviceUtils.useSinglePlayer()) {
        return contentPlayer;
    }
    return adPlayer;
}

Relationship with Parent Topic and Other Subtopics

The Player UI Controller operates as a bridge between the underlying media playback engines and the user interface layer, complementing other subtopics by:

• Enhancing Media Playback and UI Controls:
  While the parent topic covers adaptive streaming and binding UI controls to player state, the Player UI Controller adds focused management of multiple playback surfaces and resume state logic necessary for complex playback scenarios involving ads and VPAID content.

• Supporting Finite State Machine Playback:
  It provides controlled access to player instances used by the FSM states, facilitating smooth transitions between content and ad playback states.

• Coordinating with User Interaction Controller:
  The Player UI Controller exposes player instances that the User Interaction Controller may command (e.g., play, pause, seek), ensuring that user actions correctly affect the intended playback context (content vs. ads).

• Integrating with VPAID Ad Integration:
  By holding a reference to the VPAID WebView, it supports the specialized playback pathway for VPAID ads managed outside of ExoPlayer, linking this specialized UI component into the broader playback UI management.

This subtopic introduces the concept of coordinated multi-player and resume state management, which is not covered in the parent topic's general UI control discussions or in other subtopics focused on playback states or ad retrieval. It addresses the complexity arising from the coexistence of content, standard ads, and VPAID ads requiring distinct playback mechanisms.

Diagram

classDiagram
    class PlayerUIController {
        - SimpleExoPlayer contentPlayer
        - SimpleExoPlayer adPlayer
        - WebView vpaidWebView
        - View exoPlayerView
        - int adResumeWindow
        - long adResumePosition
        - int movieResumeWindow
        - long movieResumePosition
        - boolean hasHistory
        - long historyPosition
        + getContentPlayer()
        + getAdPlayer()
        + getVpaidWebView()
        + setPlayFromHistory(pos)
        + hasHistory()
        + getHistoryPosition()
        + setAdResumeInfo(window, position)
        + getAdResumeWindow()
        + getAdResumePosition()
        + setMovieResumeInfo(window, position)
        + getMovieResumeWindow()
        + getMovieResumePosition()
    }
    
    class PlayerDeviceUtils {
        + useSinglePlayer()
    }
    
    PlayerUIController --> PlayerDeviceUtils : uses
    
    %% Notes
    note for PlayerUIController "Manages player instances and resume states\nfor content, ads, and VPAID playback"

This class diagram highlights the core structure of the Player UI Controller, its key fields, and its reliance on device-specific utility logic to select appropriate playback instances. It visually encapsulates the controller’s role in managing multiple playback components and resume state data.