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 AVPlayer 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(url: String)

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(visible: Bool)

Show or hide the player controls. By default this will be called when user taps in an empty area of the overlay ("stage" in Studio project) on iOS/visionOS, and when user presses remote Back/Menu button when the overlay has focus on tvOS.

If the player on iOS/visionOS does not have functionality to toggle player controls visibility programatically, a mode where touches on the overlay's background pass through to the player view behind it can be enabled by passing params: ["stageTouchPassthrough": true] to EaseLive constructor. See an example of this with AVPlayerViewController's default controls on iOS/visionOS in the Example project.

setTime(time: Int64)

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(state: PlayerState)

Change the state of the player.

setSelectedTracks(tracks: 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(speed: Float)

Optional

Change the playback rate. speed is a value where 1.0 is normal playback, 2.0 is 2x fast forward, etc.

setVolume(volume: Int)

Optional

Change the audio volume. volume is a value 0 - 100

setMute(mute: Bool)

Optional

Change the audio mute status. mute is true to mute, and false to unmute.

didSwipeStage(direction: UISwipeGestureRecognizer.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.

setVideoScale(scaleX: Float, scaleY: Float, pivotX: Float, pivotY: Float, duration: Int)

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 as a value between 0 and 1. 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(state: PlayerState) with one of the values from PlayerState.

Controls visibility changed

Listen for when the playback controls changes visibility. When a change happens call onControllerVisibilityChanged(visible: Bool) 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(time: Int64, position: Int64, duration: Int64). 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(error: EaseLiveError?).

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(metadata: String), 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(tracks: PlayerTracks).

Playback rate

Listen for when the playback rate changes. When a change happens call onSpeedChanged(speed: Float) with the new rate. 1.0 equals normal speed.

Audio volume

Listen for when audio volume is set. When a change happens call onVolumeChanged(volume: Int) 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(mute: Bool) 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.