Appearance
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.
See example implementation for ExoPlayer in the Example project.
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 UTC timecode of the seek position as milliseconds since 1970-01-01T00:00:00Z. 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).
setSpeed(float speed)
Optional
Change the playback rate. speed is a value where 1.0 is normal playback, 2.0 is 2x fast forward, etc.
setVolume(int volume)
Optional
Change the audio volume. volume is a value 0 - 100
setMute(boolean mute)
Optional
Change the audio mute status. mute is true to mute, and false to unmute.
didSwipeStage(Direction direction)
Optional
Called when a swipe gesture is detected on a part of the overlay where the video is visible (ie outside any EaseLive graphical element). Can be used to trigger native UI. direction is the swipe direction.
setVideoScale(float scaleX, float scaleY, float pivotX, float pivotY, long duration)
Optional
Allows the overlay to change video size and position. Eg. when the menu in the overlay opens, it can squeeze back the video, so that it does not overlap. scaleX and scaleY is the scale factor between 0 and 1 as a proportion of the unscaled size. A value of 1 means no scaling. pivotX and pivotY is the point around which the video should be scaled. duration is animation duration in milliseconds.
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).
Playback rate
Listen for when the playback rate changes. When a change happens call onSpeedChanged(float speed) with the new rate. 1.0 equals normal speed.
Audio volume
Listen for when audio volume is set. When a change happens call onVolumeChanged(int volume) with the new volume as a value between 0 - 100.
Audio muted
Listen for when audio mute status changes. When a change happens call onMuteChanged(boolean mute) with the new mute status, where true is muted and false is unmuted.
Video scaled
Optional: only needed if the overlay UI should change based on the video scale. When the player will change its video scale, call onVideoScale. See setVideoScale for parameters.