Media and Ad Models

Purpose

This subtopic addresses the need to represent and manage both media content and advertisements in a unified, structured way. Within the broader scope of media playback and helper utilities, it focuses specifically on modeling the data entities for playable media items and collections of ads. These models encapsulate metadata, playback URLs, and properties that distinguish ads from regular content, enabling seamless handling of diverse media types throughout the playback system.

Functionality

MediaModel

`MediaModel` serves as the fundamental data object representing a single playable media item. It holds essential information such as:

• Video URL: The media resource location.

• Media Name: Optional title for display purposes.

• Artwork URL: Optional image to show while loading or paused.

• Subtitles URL: Optional subtitles to sideload alongside video.

• Click-Through URL: For ads, a link users can follow (e.g., advertiser site).

• Flags: Indicators whether the media is an advertisement (isAd) and whether it is a VPAID ad (isVpaid).

• MediaSource: A reference to the ExoPlayer MediaSource built from this model, linking the data model to playback components.

The class provides factory methods to create distinct content or ad media models, ensuring clarity in usage:

public static MediaModel video(String mediaName, String videoUrl, String artworkUrl, String subtitlesUrl) {
    return new MediaModel(mediaName, videoUrl, artworkUrl, subtitlesUrl, null, false, false);
}

public static MediaModel ad(String videoUrl, String clickThroughUrl, boolean isVpaid) {
    return new MediaModel(null, videoUrl, null, null, clickThroughUrl, true, isVpaid);
}

AdMediaModel

`AdMediaModel` wraps a list of `MediaModel` instances representing a sequence or break of ads (commonly known as an Ad Break). It provides utility methods to:

• Retrieve the next ad to play (nextAD()).

• Remove the first ad after it has been played (popFirstAd()).

• Query the number of remaining ads (nubmerOfAd()).

This abstraction is crucial for managing multiple ads as a group and supporting workflows such as preroll, midroll, or postroll ad sequences handled by the FSM player and ad controllers.

Integration and Relationship

`MediaModel` and `AdMediaModel` integrate closely with other media playback and ad management components:

• Finite State Machine Playback: The FSM player uses these models to load media content and ad sources dynamically, switching states between content playback and ad playback. For example, when a cue point triggers an ad break, the FSM fetches an AdMediaModel and iterates through its MediaModel ads for playback.

• Media Helper Utilities: Helpers use the URLs and metadata from MediaModel to build ExoPlayer MediaSource objects, which are assigned back into the model via setMediaSource(). This ties the data representation with actual playback resources.

• Ad and Cue Point Management: The ad retrievers fetch ad data and instantiate AdMediaModel objects, which are then passed to the FSM and ad monitors for coordinated playback.

• VPAID Ad Integration: Ads flagged with isVpaid in MediaModel trigger specialized handling via the VPAID subsystem, which manages interactive ads played inside a WebView.

By encapsulating all relevant metadata and playback state in these models, the system achieves a clean separation of concerns, allowing UI components, FSM states, and playback controllers to operate on uniform data structures.

Diagram

The following class diagram illustrates the core structure and relationships between `MediaModel` and `AdMediaModel`:

classDiagram
    class MediaModel {
        - String videoUrl
        - String mediaName
        - String artworkUrl
        - String subtitlesUrl
        - String clickThroughUrl
        - boolean isAd
        - boolean isVpaid
        - MediaSource mediaSource
        + video(mediaName, videoUrl, artworkUrl, subtitlesUrl)
        + ad(videoUrl, clickThroughUrl, isVpaid)
        + getVideoUrl()
        + getMediaName()
        + getArtworkUrl()
        + getSubtitlesUrl()
        + getClickThroughUrl()
        + isAd()
        + isVpaid()
        + getMediaSource()
        + setMediaSource(mediaSource)
    }

    class AdMediaModel {
        - List~MediaModel~ listOfAds
        + nextAD()
        + popFirstAd()
        + nubmerOfAd()
        + getListOfAds()
    }

    AdMediaModel "1" --> "*" MediaModel : contains >

This diagram highlights:

• MediaModel encapsulates individual media or ad data.

• AdMediaModel manages a collection of MediaModel instances representing an ad break.

• The association is one-to-many from AdMediaModel to MediaModel.

Summary

The Media and Ad Models provide the foundational data abstractions for representing playable video content and advertisements within the media player system. By encapsulating URLs, metadata, and playback flags, these models enable seamless coordination of content and ads, supporting advanced features such as VPAID ad playback and cue point-based ad insertion. Their design facilitates clean integration with FSM playback logic, media source construction, and UI components, enhancing modularity and maintainability.