PlaybackActionCallback.java

Overview

`PlaybackActionCallback.java` defines a Java interface that serves as a contract for handling user and player actions related to media playback within the application. It provides a structured way to receive callbacks when specific playback events occur, such as progress updates, seeking, toggling play/pause, subtitle changes, and quality adjustments. This interface is designed to decouple the media player logic from UI updates or other system components that react to playback changes, facilitating modular and maintainable code.

The callback methods are invoked **after** the corresponding playback actions have been performed, enabling observers to update the UI or trigger other processes accordingly. This interface is particularly useful in scenarios such as reactive UI components, analytics tracking, or adaptive playback features.

Classes and Interface

PlaybackActionCallback

Description

An interface defining callbacks for media playback-related actions. Implementors of this interface receive notifications about playback events and user interactions with the media player.

Methods

Implementation Details and Usage

• Nullable Annotations:
  The interface uses Android Support Annotations (@Nullable and @NonNull) to indicate the expected nullability of parameters. For example, mediaModel can be null in some callbacks, implying that the callback implementor should handle these cases gracefully.

• MediaModel Dependency:
  The MediaModel parameter represents the media content currently being played or interacted with. It is a model class (from com.tubitv.media.models) encapsulating metadata and state about the media, such as title, duration, and possibly identifiers. This dependency ties the interface closely to the media domain model of the application.

• Callback Invocation Timing:
  All callbacks are designed to be called after the corresponding action has been performed. For example, onSeek is called after the player has adjusted the playback position.

• Active State Check:
  The isActive() method allows the system to query whether the callback implementation is currently interested in receiving updates. This can optimize event dispatching by skipping inactive listeners.

Example Usage

public class PlaybackLogger implements PlaybackActionCallback {

    private boolean active = true;

    @Override
    public void onProgress(@Nullable MediaModel mediaModel, long milliseconds, long durationMillis) {
        if (mediaModel != null) {
            System.out.println("Playback progress for " + mediaModel.getTitle() + ": " + milliseconds + "/" + durationMillis);
        }
    }

    @Override
    public void onSeek(@Nullable MediaModel mediaModel, long oldPositionMillis, long newPositionMillis) {
        System.out.println("Seeked from " + oldPositionMillis + " to " + newPositionMillis);
    }

    @Override
    public void onPlayToggle(@Nullable MediaModel mediaModel, boolean playing) {
        System.out.println("Playback " + (playing ? "started" : "paused"));
    }

    @Override
    public void onLearnMoreClick(@NonNull MediaModel mediaModel) {
        System.out.println("Learn more clicked for: " + mediaModel.getTitle());
    }

    @Override
    public void onSubtitles(@Nullable MediaModel mediaModel, boolean enabled) {
        System.out.println("Subtitles " + (enabled ? "enabled" : "disabled"));
    }

    @Override
    public void onQuality(@Nullable MediaModel mediaModel) {
        System.out.println("Quality changed or requested for media");
    }

    @Override
    public void onCuePointReceived(long[] cuePoints) {
        System.out.println("Received cue points: " + Arrays.toString(cuePoints));
    }

    @Override
    public boolean isActive() {
        return active;
    }

    public void setActive(boolean active) {
        this.active = active;
    }
}

In this example, `PlaybackLogger` implements the interface to log playback events for debugging or analytics.

Interaction with Other Components

• Media Player Component:
  The media player component triggers these callbacks after handling user inputs or playback state changes. It passes the current MediaModel and relevant playback state information.

• UI Layer:
  UI components implement this interface (or use implementations) to update playback controls, progress bars, subtitles toggle buttons, and quality selectors accordingly.

• Analytics/Tracking:
  Implementations of this interface may send event data to analytics services to track user engagement and playback behavior.

• MediaModel Dependency:
  As the interface depends on MediaModel, any changes to the media model structure can affect callback implementations.

Mermaid Class Diagram

classDiagram
    interface PlaybackActionCallback {
        +void onProgress(MediaModel? mediaModel, long milliseconds, long durationMillis)
        +void onSeek(MediaModel? mediaModel, long oldPositionMillis, long newPositionMillis)
        +void onPlayToggle(MediaModel? mediaModel, boolean playing)
        +void onLearnMoreClick(MediaModel mediaModel)
        +void onSubtitles(MediaModel? mediaModel, boolean enabled)
        +void onQuality(MediaModel? mediaModel)
        +void onCuePointReceived(long[] cuePoints)
        +boolean isActive()
    }
    
    class MediaModel {
        <<external>>
    }
    
    PlaybackActionCallback ..> MediaModel : uses

Summary

`PlaybackActionCallback.java` is a fundamental interface in the media playback system that enables decoupled, event-driven communication about playback actions. Its design promotes modularity and flexibility by informing interested components post-action, supporting features like UI updates, analytics, and adaptive playback. The interface's reliance on `MediaModel` ensures contextual awareness for each callback, and the active state query optimizes event dispatch.

This interface plays a key role in integrating the media playback engine with user interaction layers and other system components, aligning with the overall modular architecture of the application.