Events

To listen for events sent by the SDK and overlay, add listeners using easeLive.on:

ExampleListen.kt

easeLive.on<EaseLiveEvent.ReadyEvent> {
    Log.d(TAG, "EL ready")
}

easeLive.on<EaseLiveEvent.ErrorEvent> { e ->
    Log.d(TAG, "EL error " + e.error)
    if (e.error.level == Error.LEVEL_FATAL) {
        // fatal error. For example the UI failed to load.
        // remove the overlay and fallback to a normal video
        easeLive?.destroy()
        easeLive = null
    } else {
        // non-fatal error/warning.
    }
}

ExampleListen.java

class ExampleListen {
    EaseLive easeLive;

    void setupEaseLiveEvents() {
        easeLive.on(EaseLiveEvent.ReadyEvent.class, e -> Log.d(TAG, "EL ready"));
        easeLive.on(EaseLiveEvent.ErrorEvent.class, e -> {
            Error error = e.getError();
            if (error.getLevel() == Error.LEVEL_FATAL) {
                easeLive.destroy();
                easeLive = null;
            }
        });
    }
}

To listen for events and then later stop listening:

val onEaseLiveReady: (EaseLiveEvent.ReadyEvent) -> Unit = { }
// start listening
easeLive!!.on(onEaseLiveReady)
// stop listening
easeLive!!.off(onEaseLiveReady)

To send an event to the overlay, call easeLive.emit:

ExampleEmit.kt

easeLive.emit(EaseLiveEvent.MessageEvent("myPrefix.myEvent", JSONObject()))

ExampleEmit.java

class ExampleEmit {
    EaseLive easeLive;

    void sendCustomEvent() {
        easeLive.emit(new EaseLiveEvent.MessageEvent("myPrefix.myEvent", new JSONObject()));
    }
}

Events from the SDK to the app

EaseLiveEvent.ReadyEvent

Sent from the SDK when all the components becomes fully operational.

EaseLiveEvent.ErrorEvent

Sent when an error occurs in the SDK or plugins. The app should destroy the SDK on fatal errors.

Attribute	Description	Type	Required
error	Error object	tv.easelive.easelivesdk.model.Error	Required

The error contained in the notification has an identification code to specify if it's a Fatal error or just a Warning, it's possible to check that reading the error.getLevel() value and check if it's equal to Error.LEVEL_FATAL.

Events from the app to the overlay

EaseLiveEvent.MessageEvent

Sent from the mobile app to notify about a generic message, which can be used for custom functionality in the overlay.

Attribute	Description	Type	Required
event	Event name as defined in the overlay project	String	Required
metadata	JSON object to send	JSONObject	Optional

Example

Events from the overlay to the app

EaseLiveEvent.StatusEvent

Sent when the status of the overlay changes. When the overlay was disabled, it should be removed from the app.

Attribute	Description	Type	Required
STATUS	New status	String	Required

Status is a String with possible values enabled, hidden, disabled.

EaseLiveEvent.BridgeReadyEvent

Sent when the bridge is ready to receive events. Events from the app will not be sent until this is received.

EaseLiveEvent.PlayerControlsEvent

Sent when the stage of the overlay UI is clicked, and should trigger a change in the visibility of the player controls.

Attribute	Description	Type	Required
visible	New controls state	Boolean	Required

EaseLiveEvent.StageSwipedEvent

Sent when the stage of the overlay UI is swiped, and can be used to trigger a change in the visibility of player controls.

Attribute	Description	Type	Required
direction	Swipe direction	tv.easelive.easelivesdk.model.Direction	Required

EaseLiveEvent.PlayerTimeEvent

Sent when the player should seek to the given timecode.

Attribute	Description	Type	Required
timecode	New timecode as milliseconds since 1970-01-01T00:00:00Z	Long	Required

EaseLiveEvent.PlayerStateEvent

Sent when the player should change its playback state, for example to pause or play.

Attribute	Description	Type	Required
state	New state	tv.easelive.easelivesdk.model.PlayerState	Required

EaseLiveEvent.MessageEvent

Sent from the overlay UI to notify about a generic message, which can be used for custom functionality.

Attribute	Description	Type	Required
event	Event name	String	Required
metadata	Event metadata	JSONObject	Required

Example

EaseLiveEvent.PlayerSpeedEvent

Sent when the player should change its speed (playback rate). E.g. 0.5 is half speed, 1 is normal speed, 2 is 2x fast-forward.

Attribute	Description	Type	Required
speed	New playback speed	Float	Required

EaseLiveEvent.PlayerVolumeEvent

Sent when the player should change its audio volume. E.g. 0 is silent, 100 is normal volume.

Attribute	Description	Type	Required
volume	New audio volume	Int	Required

EaseLiveEvent.PlayerMuteEvent

Sent when the player should change its audio mute status. E.g. true is muted, false is unmuted.

Attribute	Description	Type	Required
mute	New audio mute status	Boolean	Required

EaseLiveEvent.PlayerVideoScaleEvent

Sent when the player should change the video surface's scale and position.

Attribute	Description	Type	Required
scaleX	Horizontal scale factor, between 0 and 1.	Float	Required
scaleY	Vertical scale factor, between 0 and 1.	Float	Required
pivotX	Horizontal anchor for the scaling animation, between 0 and 1.	Float	Required
pivotY	Vertical anchor of the scaling animation, between 0 and 1.	Float	Required
duration	Duration of the scale animation in milliseconds.	Long	Required

Events from the player plugin to the overlay

These events are sent by the PlayerPlugin to the overlay.

EaseLiveEvent.PlayerReadyEvent

Sent when the player becomes ready to play.

EaseLiveEvent.PlayerTimeEvent

Sent when the player reads the timecode for the current playback position. All timecodes should be in milliseconds since 1970-01-01T00:00:00Z.

Attribute	Description	Type	Required
timecode	Timecode at current playback position	Long	Required
initialTimecode	Timecode at the start of the seekable window	Long	Optional
maxTimecode	Timecode at the end of the seekable window	Long	Optional

The initialTimecode and maxTimecode are optional. If not present the stream is considered to be a Live stream without a seekable buffer.

EaseLiveEvent.PlayerMetadataEvent

Sent when the player reads metadata from the stream.

Attribute	Description	Type	Required
metadata	JSON containing metadata	JSONObject	Required

EaseLiveEvent.PlayerStateEvent

Sent when the player changes state, for example a change from paused to playing.

Attribute	Description	Type	Required
state	New state	tv.easelive.easelivesdk.model.PlayerState	Required

Where state is a String with possible values playing, stopped, paused, seeking, buffering.

EaseLiveEvent.PlayerControlsEvent

Sent when the player changes the visibility of the player controls. Typically when the player stage is clicked or if the native controls hide automatically after a timeout, the player plugin should notify about this change.

Attribute	Description	Type	Required
visible	New controls visibility	Boolean	Required

EaseLiveEvent.PlayerSpeedEvent

Sent when the player has changed its speed (playback rate). E.g. 0.5 is half speed, 1 is normal speed, 2 is 2x fast-forward.

Attribute	Description	Type	Required
speed	New playback speed	Float	Required

EaseLiveEvent.PlayerVolumeEvent

Sent when the player has changed its audio volume. E.g. 0 is silent, 100 is normal volume.

Attribute	Description	Type	Required
volume	New audio volume	Int	Required

EaseLiveEvent.PlayerMuteEvent

Sent when the player has changed its audio mute status. E.g. true is muted, false is unmuted.

Attribute	Description	Type	Required
mute	New audio mute status	Boolean	Required

EaseLiveEvent.PlayerVideoScaleEvent

Sent when the player will change the video surface's scale and position.

Attribute	Description	Type	Required
scaleX	Horizontal scale factor, between 0 and 1.	float	Required
scaleY	Vertical scale factor, between 0 and 1.	float	Required
pivotX	Horizontal anchor for the scaling animation, between 0 and 1.	float	Required
pivotY	Vertical anchor of the scaling animation, between 0 and 1.	float	Required
duration	Duration of the scale animation in milliseconds.	long	Required