API Reference

EaseLive

new EaseLive(options)

Creates a new Ease Live Bridge on your web page. Throws an Error exception if a required parameter is missing.

Attribute	Description	Type	Required
logLevel	Which level of logging to apply (debug, info, error). Defaults to info	String	Optional
setupTimeout	Timeout in millisecond after which the overlay loading should error out. Defaults to 30000	Integer	Optional
viewContainer	Which DOM element to render the Ease Live UI in. If blank, the player container will be used.	String or DOM Node	Optional
playerPlugin	Which player plugin to use. Either a function or an array where the first element is the function and the remaining elements are parameters	Function or Array	Required
viewPlugin	Which view plugin to use. Defaults to xcomponent	Object	Optional
accountId	Account ID	String	Required
projectId	Project ID. If not set, it will load the project the program belongs to	String	Optional
programId	Program ID	String	Required
env	Which environment to load URL for. Use to load different URLs for "prod", "staging" and "dev". Defaults to "prod"	String	Optional
keymapping	Mapping of keys used for spatial navigation in Smart TV projects. An Object where the property name is the value of key or keyCode in KeyboardEvent mapped to a value which is one of 'ArrowLeft', 'ArrowUp', 'ArrowRight', 'ArrowDown', 'Enter', 'Back'. Example: {'Escape': 'Back', 87: 'ArrowUp'} to use Esc to navigate back, and W to navigate up	Object	Optional
allowPermissions	Custom allow list for the iframe. If set to empty array, no permissions are given. By default the following permission are given: ['camera', 'microphone', 'clipboard-read', 'clipboard-write', 'fullscreen'].	Array	Optional
params	Parameters to the Ease Live web app	Object	Optional
params.debug	Instruct the web app to run in debug mode	Boolean	Optional
params.streamId	Stream ID. Defaults to main	String	Optional

easeLive.options

Returns the options object that was provided at startup.

easeLive.use(plugin, options)

Installs a new plugin to the easeLive instance.

Parameter	Description	Type	Required
plugin	Anonymous function, or object with install function	Function/Object	Required
options	Configuration options specific to the plugin to be installed	Object	Optional

easeLive.getPlayer()

Returns the player instance created by the player plugin.

easeLive.on(event, listener, fromSdkOnly)

Subscribe to an event. The callback handler will receive any attached metadata/payload. Events can be triggered by either the SDK itself, plugins, or by the connected web app.

Note that wildcards are supported.

Parameter	Description	Type	Required
event	Event name	String	Required
listener	Callback ran with event metadata as the first argument when event received	Function	Required
fromSdkOnly	When true, only trigger on events emitted by the SDK/overlay, and ignore events from the app/custom plugins. When false, trigger on all emitted events. Defaults to false	Boolean	Optional

easeLive.off(event, listener)

Unsubscribe an event listener that was previously added with easeLive.on.

Parameter	Description	Type	Required
event	Event name	String	Required
listener	Callback	Function	Required

easeLive.emit(event, data)

Send an event to the overlay.

Parameter	Description	Type	Required
event	Event name	String	Required
data	Event metadata	Object	Optional

easeLive.focus()

Move focus for spatial navigation to the EaseLive overlay.

easeLive.hasFocus()

Returns true if focus is currently within the EaseLive overlay.

easeLive.setProgram(options)

Loads a different program in the current instance.

Attribute	Description	Type	Required
accountId	Account ID	String	If not set, it will use the one set in constructor
projectId	Project ID	String	If not set, it will load the project the program belongs to
programId	Program ID	String	Required
env	Which environment to load URL for. Use to load different URLs for "prod", "staging" and "dev". Defaults to "prod"	String	Optional
params	Parameters to the Ease Live web app	Object	Optional

easeLive.setStream(options)

Updates the Stream ID during runtime. The overlay will automatically apply the stream’s timecode settings.

Attribute	Description	Type	Required
streamId	Stream ID	String	Required

easeLive.destroy()

Removes the overlay and its event listeners. EaseLive should be destroyed before removing the DOM element passed as viewContainer. For example in React componentWillUnmount, Vue onBeforeUnmount, or equivalent.

Events

easelive.ready

Fired when overlay has completed loading.

easelive.error

Fired when any error occurs in the SDK or plugins. For separate error events by component, see Error events. The app should destroy the SDK on fatal errors. See Error handling.

Value	Description	Type
type	Possible values fatal, warning	string
message	Human-readable description of the error	string
code	Optional error code	integer
programId	Program ID if the error is related to subscribing to a program	string

Player

Events

player.ready

When the player has been initiated and is ready for playback, this event should be triggered. This is the point where the Ease Live View will be initialized.

Value	Description	Type	Required
player	The player instance	Object	Optional
playerContainer	The parent element which the view is to be attached. This will only be used if no viewContainer is configured (see EaseLive constructor)	DOM Element or String identifier	Optional

player.state

This event should be fired by the player plugin whenever the player state changes.

"state" is one of "playing", "paused", "stopped", "seeking" and "buffering". Required.

Value	Description	Type	Required
state	The new player state	String	Required

player.time

This event should be fired by the player plugin whenever it reads the timecode of the current playback position. The timecodes should be milliseconds since 1970-01-01T00:00:00Z.

The initialTimecode and maxTimecode are optional. If not present the stream is considered to be a Live stream without a seekable buffer. If it's a live stream the initialTimecode and maxTimecode should be equal to the timecode.

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

player.metadata

Fired when any additional metadata is received in the stream (optional).

The payload should contain the json-parsed payload of the tag embedded in the stream. It can have any number of name/value pairs.

player.speed

Sets or gets the playback speed of the player. Fast forward as well as slow motion is supported. Slow motion is used by values between 0 and 1, fast forward by values greater than 1.

Value	Description	Type	Required
speed	A playback speed factor greater than 0	Float	Required

player.volume

Sets or gets the player’s volume in the range of 0 (silent) to 100 (max volume).

Value	Description	Type	Required
volume	The volume to set between 0 and 100	Integer	Required

player.mute

Sets or gets the player’s audio mute.

Value	Description	Type	Required
mute	The mute status, true or false	Boolean	Required

player.videoscale

Sets or gets the size and position of the player’s video surface. Values are relative to the original video size.

Value	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.	Integer	Required

player.controls

Emit when your player controls change visibility.

Value	Description	Type	Required
controls	New player controls visibility. Possible values visible, hidden	string	Required

View

Events

view.ready

Fired when the view has been initiated, but not yet ready for bridge communication (see bridge.ready).

Receives an object with the following:

Value	Description	Type
viewContainer	The DOM element the view is rendered to	DOM Element
url	The complete URL used for connecting to the Ease Live web app	String

view.mouseenter

Fired when the mouse enters the EL container. Useful for e.g. showing player controls.

Bridge

Events

bridge.ready

Fired when the bridge communication layer has been initiated, after the web app has completed the initial load.

bridge.stage

Fired when your player controls should update its visibility and focus.

When user clicked on empty part of the overlay or pressed remote Back button at the root, controls value will be "visible":

• set your player controls visible if they are not visible already.
• if using spatial navigation (ie on a TV): set focus to some element inside the player controls.
• optionally you can hide the element used as viewContainer to hide the overlay while player controls are visible, or just keep EaseLive visible behind the player controls.

When user clicks in the overlay while controls are visible or navigates into a new scene, controls value will be "hidden":

• set your player controls hidden if they are not hidden already.
• set EaseLive's viewContainer visible if it is not visible already.
• if using spatial navigation (ie on a TV): set focus to EaseLive using easeLive.focus().

Value	Description	Type
controls	New player controls visibility. Possible values visible, hidden	string

Application

app.ready

Fired when the overlay has finished loading in the UI and is up and running as expected.

app.status

Fired when the producer has changed status of the overlay. If the status is disabled the EaseLive instance can be destroyed. If using spatial navigation (ie on a TV), set focus back to the player controls when EaseLive is hidden or disabled.

Value	Description	Type
status	New status. Possible values enabled, hidden, disabled	string

Error events

view.error

Fired when the Bridge SDK doesn't manage to setup an iframe or webview.

Value	Description	Type
type	Possible values fatal, warning	string
message	Human-readable description of the error	string

bridge.error

Fired when the Bridge SDK doesn't manage to setup a communication channel between the Bridge and the web app.

Value	Description	Type
type	Possible values fatal, warning	string
message	Human-readable description of the error	string

app.error

Fired when something wrong happens during runtime, like missing data or scalability issues.

Value	Description	Type
type	Possible values fatal, warning	string
message	Human-readable description of the error	string
code	Optional error code	integer
programId	Program ID if the error is related to subscribing to a program	string