Player plugin

The player plugin is the class that handles the communication between the player and the EaseLive SDK. It has to implement the interface PlayerPluginInterface.

The player plugin is responsible for:

• listen for changes in the player's state and metadata, and then send them as events from the player plugin.
• listen for events from the overlay UI and change the player state.

PlayerPluginBase

The class PlayerPluginBase can be use as a base class for a player plugin implementation. The base class provides default implementations for PlayerPluginInterface, and takes care of the receiving and sending of the events.

Implementation

Create a class extending PlayerPluginBase. The base class contains overridable methods which will be called based on the plugin lifecycle and events received from the overlay UI.

The implementation can override the following methods:

createPlayer()

Optional: only needed if the plugin should manage the player instance. Not needed if reusing an existing player instance.

Initialize a player instance and add listeners on the player for changes in state and metadata.

destroyPlayer()

Optional: only needed if the player should be destroyed when the player plugin is destroyed.

Remove any listeners the player plugin has set on the player instance and release the player instance.

playVideoUrl(String url)

Optional: only needed if the video should be settable from the overlay UI.

Open the stream in the player, or resume playback if it is already loaded.

setControllerVisible(boolean visible)

Show or hide the player controls.

setTime(long time)

Seek to the given time. The time parameter is the UTC timecode of the seek position. Seek to the equivalent position in the player's seekable window.

setState(tv.easelive.easelivesdk.model.PlayerState state)

Change the state of the player.

setSelectedTracks(tv.easelive.easelivesdk.model.PlayerTracks playerTracks)

Optional: only needed if the tracks should be selectable from the overlay UI.

Set the selected tracks in the player (eg. to change between multiple camera angles or audio languages).

Listen for changes in the player

When the state or metadata of the player changes, the implementation should call the appropriate method on the player plugin. This will send an event to the overlay UI, so that overlay UI can update its state based on the state of the player.

Ready to play

Listen for when the player is ready to play. When it is ready call onReady().

Player state changed

Listen for when the player changes state between playing, pausing, buffering, seeking, etc. When a change happens call onState(PlayerState state) with one of the values from PlayerState.

Controls visibility changed

Listen for when the playback controls changes visibility. When a change happens call onControllerVisibilityChanged(boolean visible) with the new visibility.

Timecode

Listen for when the player reads the UTC timecode of the current playback position. This information is commonly embedded in timed ID3 tags, or in the manifest (eg. EXT-X-PROGRAM-DATE-TIME in HLS).

When the timecode is read call onTime(long time, long position, long duration). The parameters are: time: the UTC timecode at the current playback position as milliseconds since 1970-01-01T00:00:00Z. position: the current playback position in the seekable window as milliseconds from the start. duration: the duration of the player's seekable window in milliseconds.

For example with a stream that has a 1 hour seekable window, if the current playback position is 10 seconds from the end, the duration would be 3600000 and position 3590000.

Errors

If a fatal error occurs in the player it can be sent using onError(tv.easelive.easelivesdk.model.Error error).

Metadata

Optional: only needed if the stream contains additional metadata that are to be used by the overlay UI.

When metadata is read (eg. timed ID3 tags) it can be sent using onMetadata(String metadata), where the parameter is a JSON formatted string.

Tracks

Optional: only needed if the tracks should be selectable from the overlay UI.

When the stream contains multiple tracks (eg. multiple camera angles or audio languages), the available and selected tracks can be sent using onTracksChanged(tv.easelive.easelivesdk.model.PlayerTracks tracks).