State Management

Purpose

This component addresses the complex challenge of controlling media playback and advertisement integration through a clear, modular finite state machine (FSM) design. It encapsulates distinct playback scenarios—such as content playing, ad retrieval, ad playback (including VPAID ads), and user interactions—into well-defined states. This approach ensures robust handling of asynchronous events, smooth transitions between content and ads, and consistent UI updates, which collectively provide a seamless viewing experience.

Functionality

State Management defines specific playback states that govern the behavior of the media player at any given point. Each state encapsulates the logic for responding to inputs (events) and performing relevant actions. Key functionalities include:

• Ad Fetching States

  • MakingPrerollAdCallState: Initiates fetching of preroll ads based on cue points; updates the ad retriever with the correct cue point before calling the ad server.

  • MakingAdCallState: Handles general ad retrieval requests, invoking ad server fetches and transitioning upon ad reception.

• Ad Playback States

  • AdPlayingState: Manages playback of standard ads using ExoPlayer. It prepares the ad player, pauses content playback, updates UI for ad display, and handles transitions on ad completion or user interaction.

  • VpaidState: Manages playback of VPAID-compliant interactive ads inside a WebView. It pauses all ExoPlayer instances, initializes the VPAID client, shows the WebView, and handles JavaScript communication events to transition back to content or next ads.

• Content Playback State

  • MoviePlayingState: Resumes and manages main content playback after ads finish. It handles ExoPlayer preparation, resumes playback positions, toggles subtitle visibility, and hides ad or VPAID UI components.

• Cue Point Fetching State

  • FetchCuePointState: Initiates retrieval of cue points from the ad server to determine ad insertion points and transitions based on the presence or absence of preroll ads.

• Ad Reception and Interaction States

  • ReceiveAdState: Awaits ad data after an ad call; triggers transitions to ad playback when ads are ready.

  • VastAdInteractionSandBoxState: Handles user interactions with ads (e.g., clicking) and transitions back to ad playback after ad interaction.

• Terminal State

  • FinishState: Represents the end of playback or error states where no further transitions occur.

Input-Driven Transitions

Each state defines a `transformToState` method that determines the next state based on input events. For example:

@Override
public State transformToState(Input input, StateFactory factory) {
    switch (input) {
        case MAKE_AD_CALL:
            return factory.createState(MakingAdCallState.class);
        case MOVIE_FINISH:
            return factory.createState(FinishState.class);
        // other cases...
    }
    return null;
}

Work Execution and UI Updates

States implement `performWorkAndUpdatePlayerUI` to carry out actions like fetching ads, preparing players, pausing/resuming playback, and updating UI visibility. For instance, `AdPlayingState` prepares the ad player and hides subtitles:

SimpleExoPlayer adPlayer = controller.getAdPlayer();
adPlayer.prepare(adMedia.getMediaSource(), !haveResumePosition, true);
adPlayer.setPlayWhenReady(true);

((TubiExoPlayerView) controller.getExoPlayerView()).getSubtitleView().setVisibility(View.INVISIBLE);

Integration

State Management is the core operational layer within the broader Finite State Machine Playback system. It directly implements the playback logic abstracted by the FSM framework, bridging asynchronous ad and cue point fetching with synchronous playback control.

• Parent Topic Relationship
  It realizes the abstract FSM concept by defining concrete states and their behaviors, enabling the FSM to manage content and ad playback cycles seamlessly.

• Interaction with Other Subtopics

  • Works closely with State Factory to instantiate and cache state objects.

  • Collaborates with Ad and Cue Point Management by invoking ad server interfaces to fetch ads and cue points.

  • Coordinates with Media Playback and UI Controls by manipulating ExoPlayer instances and updating UI controllers to reflect current playback states.

  • Supports VPAID Ad Integration by switching to the VpaidState when interactive ads are played inside a WebView.

This modular state structure allows the FSM player to react dynamically to playback events, ad server responses, and user interactions without mixing concerns, promoting maintainability and extensibility.

Diagram

flowchart LR
    Start[Start Playback] --> FetchCuePoints[Fetch Cue Points]
    FetchCuePoints -->|Has Preroll| MakePrerollAdCall[MakingPrerollAdCallState]
    FetchCuePoints -->|No Preroll| MoviePlaying[MoviePlayingState]
    MakePrerollAdCall --> ReceiveAd[ReceiveAdState]
    ReceiveAd --> AdPlaying[AdPlayingState]
    AdPlaying -->|VPAID Ad Detected| Vpaid[VpaidState]
    AdPlaying --> MoviePlaying
    Vpaid --> MoviePlaying
    MoviePlaying -->|Midroll Cue Point| MakingAdCall[MakingAdCallState]
    MakingAdCall --> ReceiveAd
    MoviePlaying -->|Playback Finished| Finish[FinishState]

This flowchart illustrates the primary states and transitions managed by State Management, highlighting the core playback and ad integration process, including preroll, midroll, standard ads, and VPAID ads.