MediaModel.java

Overview

`MediaModel.java` defines the `MediaModel` class, a core data representation within the media playback system. This class models an individual media item, encapsulating all essential metadata and playback information for both regular video content and advertisements. It provides a unified, serializable container that holds URLs for video, artwork, subtitles, and optionally click-through links for ads. Additionally, it tracks whether the media is an advertisement (including VPAID ads) and maintains a reference to the underlying `MediaSource` used by ExoPlayer for playback.

This abstraction enables the media player, UI components, and ad management logic to uniformly handle media items and ads without duplicating code or data structures, simplifying playback orchestration and metadata access.

Class: `MediaModel`

Purpose

Represents a single playable media item (video content or ad).
Encapsulates metadata such as URLs for media, artwork, subtitles, and ad click-throughs.
Holds playback flags to differentiate ads and VPAID ads.
Stores the associated MediaSource object used during playback.
Implements Serializable to support object serialization (e.g., for passing between components or saving state).

Fields

Field Name	Type	Description
`videoUrl`	`String`	Non-null URL string of the media video resource.
`mediaName`	`String`	Nullable display title or name of the media.
`artworkUrl`	`String`	Nullable URL string for artwork or thumbnail image.
`subtitlesUrl`	`String`	Nullable URL string for subtitle files to sideload.
`clickThroughUrl`	`String`	Nullable URL string for ad click-through link (if media is an ad).
`mediaSource`	`MediaSource`	ExoPlayer `MediaSource` object representing the playable stream.
`isAd`	`boolean`	Flag indicating if the media is an advertisement.
`isVpaid`	`boolean`	Flag indicating if the ad is a VPAID (interactive) ad.

Constructors

public MediaModel(@Nullable String mediaName, @NonNull String videoUrl, @Nullable String artworkUrl,
                  @Nullable String subtitlesUrl, @Nullable String clickThroughUrl, boolean isAd, boolean isVpaid)

Parameters:
- mediaName: Optional media title.
- videoUrl: Non-null URL string for the media.
- artworkUrl: Optional artwork URL.
- subtitlesUrl: Optional subtitles URL.
- clickThroughUrl: Optional URL for ad click-through.
- isAd: Whether the media is an ad.
- isVpaid: Whether the ad is a VPAID ad.
Functionality:
Initializes a new instance of MediaModel with provided metadata and flags.

Static Factory Methods

These methods simplify creating `MediaModel` instances for common use cases.

`video`

public static MediaModel video(@NonNull String mediaName, @NonNull String videoUrl, @NonNull String artworkUrl,
                               @Nullable String subtitlesUrl)

Creates a MediaModel representing regular video content.
Automatically sets isAd and isVpaid to false.
clickThroughUrl is set to null.

**Example:**

MediaModel videoContent = MediaModel.video(
    "Nature Documentary",
    "http://example.com/video.m3u8",
    "http://example.com/artwork.jpg",
    "http://example.com/subtitles.vtt"
);

`ad`

public static MediaModel ad(@NonNull String videoUrl, @Nullable String clickThroughUrl, boolean isVpaid)

Creates a MediaModel representing an advertisement.
mediaName, artworkUrl, and subtitlesUrl are set to null.
isAd is set to true.
The isVpaid flag is assigned from the parameter.

**Example:**

MediaModel adContent = MediaModel.ad(
    "http://example.com/ad.m3u8",
    "http://advertiser.com",
    false
);

Public Methods

Method	Return Type	Description
`@Nullable String getMediaName()`	`String`	Returns the media's display name or `null` if none.
`@NonNull Uri getVideoUrl()`	`Uri`	Parses and returns the video URL as an Android `Uri` object.
`@Nullable Uri getArtworkUrl()`	`Uri`	Parses and returns the artwork URL as `Uri`, or `null` if not set.
`@Nullable Uri getSubtitlesUrl()`	`Uri`	Parses and returns the subtitles URL as `Uri`, or `null` if not set.
`@Nullable String getClickThroughUrl()`	`String`	Returns the ad click-through URL or `null` if not applicable.
`boolean isAd()`	`boolean`	Returns `true` if the media is an ad; otherwise, `false`.
`String getMediaExtension()`	`String`	Returns the media file extension, hardcoded to `"m3u8"`. Used to identify media type.
`MediaSource getMediaSource()`	`MediaSource`	Returns the associated ExoPlayer `MediaSource` object.
`void setMediaSource(MediaSource mediaSource)`	`void`	Sets the `MediaSource` for this media model.
`boolean isVpaid()`	`boolean`	Returns `true` if the media is a VPAID ad; otherwise, `false`.

Usage Example

// Create a video content model
MediaModel video = MediaModel.video(
    "Travel Vlog",
    "https://videos.example.com/travel.m3u8",
    "https://images.example.com/travel.jpg",
    null
);

// Create an ad media model
MediaModel ad = MediaModel.ad(
    "https://ads.example.com/ad.m3u8",
    "https://advertiser.example.com",
    true
);

// Access media URL
Uri videoUri = video.getVideoUrl();

// Set and retrieve MediaSource (after preparing ExoPlayer source)
MediaSource source = ...; // Created elsewhere
video.setMediaSource(source);
MediaSource retrievedSource = video.getMediaSource();

Important Implementation Details

Serialization: Implements Serializable allowing instances to be serialized for IPC or persistence.
URI Parsing: All URL strings are parsed into Android Uri objects on-demand, ensuring type safety and compatibility with Android APIs.
Immutable Fields: Except for mediaSource, all fields are final and set during construction, enforcing immutability for metadata.
Ad Flags: Differentiates between regular media and ads through isAd and isVpaid flags, allowing playback logic to adapt accordingly.
Media Extension: Hardcoded to "m3u8", indicating usage of HTTP Live Streaming (HLS) playlists.

Interaction with Other System Components

Playback System / FSM:
MediaModel instances are passed to the playback finite state machine (FSM) and ExoPlayer components for media preparation and playback control.
MediaSource Construction:
The mediaSource field is assigned externally by utilities that build an ExoPlayer MediaSource from the URLs provided in the model.
Ad Management:
Ads use MediaModel instances with the isAd flag set. The clickThroughUrl supports user interaction with ads. VPAID ads (isVpaid) trigger specialized interactive ad handling.
UI Components:
UI layers use mediaName, artworkUrl, and subtitle information to display metadata, thumbnails, and subtitles during playback.
Serialization:
The class’s serializability allows passing MediaModel objects between Android components or saving playback state.

Visual Diagram: Class Structure

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)
        + getMediaName()
        + getVideoUrl()
        + getArtworkUrl()
        + getSubtitlesUrl()
        + getClickThroughUrl()
        + isAd()
        + isVpaid()
        + getMediaExtension()
        + getMediaSource()
        + setMediaSource(mediaSource)
    }

Summary

The `MediaModel` class provides a comprehensive, immutable representation of a media item — either regular video content or an advertisement — encapsulating all metadata and playback-related flags necessary for the media playback system. Its design facilitates clear creation via factory methods, supports media playback through integration with ExoPlayer's `MediaSource`, and enables ad-specific logic through dedicated flags and click-through URLs. This class forms the backbone of media representation within the application, enabling consistent and maintainable handling of video and ad playback scenarios.

*End of MediaModel.java documentation.*