API Reference

TypeScript

The SDK includes full TypeScript definitions. Import types as needed:

import EaseLive from '@ease-live/ease-live-bridge-web';
import type {
  EaseLiveOptions,
  EaseLiveEvents,
  PlayerPlugin,
  ViewPlugin,
  PlayerState,
  ErrorType,
  LogLevel,
  Environment,
} from '@ease-live/ease-live-bridge-web';

Event Types

interface EaseLiveEvents {
  'player.ready': { player?: unknown; playerContainer?: HTMLElement; instance?: unknown };
  'player.state': { state: PlayerState };
  'player.time': { timecode: number; initialTimecode?: number; maxTimecode?: number };
  'player.speed': { speed: number };
  'player.volume': { volume: number };
  'player.mute': { mute: boolean };
  'player.error': { type: ErrorType; message: string };
  'player.seek': { offset: number };
  'player.position': { position: number; duration?: number };
  'player.metadata': Record<string, unknown>;
  'player.videoscale': { scaleX: number; scaleY: number; pivotX: number; pivotY: number; duration: number };
  'player.controls': { controls: 'visible' | 'hidden' };

  'bridge.ready': Record<string, never>;
  'bridge.error': { type: ErrorType; message: string };

  'stage.clicked': { controls?: 'visible' | 'hidden' };

  'view.ready': { viewContainer: HTMLElement; url: string };
  'view.error': { type: ErrorType; message: string };
  'view.mouseenter': Record<string, never>;

  'app.ready': Record<string, never>;
  'app.status': { status: 'enabled' | 'disabled' | 'hidden' };
  'app.error': { type: ErrorType; message: string };

  'easelive.ready': Record<string, never>;
  'easelive.error': { type: ErrorType; message: string };
}

type PlayerState = 'playing' | 'paused' | 'stopped' | 'seeking' | 'buffering';
type ErrorType = 'fatal' | 'warning';
type LogLevel = 'debug' | 'info' | 'error';
type Environment = 'prod' | 'staging' | 'dev';

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, the project is resolved for the device. If set, that project is always loaded	String	Optional
programId	Program ID	String	Required
env	Which environment to load URL for: prod, staging or dev. Any other value fails to load (view.error). Defaults to "prod"	String	Optional
deviceType	Override the auto-detected device type sent to the overlay and used for project resolution: desktop, tablet, phone or tv. A value that isn't lowercase letters only (a–z) is sent as unknown	String	Optional
deviceOs	Override the auto-detected device OS name sent to the overlay and used for project resolution, e.g. tizen, webos, android. A value that isn't lowercase letters only (a–z) is sent as unknown	String	Optional
deviceOsVersion	Override the auto-detected device OS version sent to the overlay, e.g. 5.0.	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', 'autoplay'].	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
params.userId	Your own ID for the viewer, used to count unique users in analytics. If not set, the overlay generates a random ID and stores it in a cookie on the device, so each device counts as one user until a userId is passed	String	Optional

Project resolution

When projectId isn't set, the SDK loads the program with a single request to the bridge endpoint (GET /api/v2/bridge/program/:programId), sending the device type and OS. The server picks the project:

• if the program's project has device targets configured, the studio project that matches deviceType/deviceOs is used (exact type + OS first, then type only, then a catch-all target);
• if no target matches, there is no overlay for this device: the request returns 404 and view.error is emitted;
• if the project has no device targets, the program's own project is used.

Device type, OS name and version are detected from the user agent. Set deviceType/deviceOs to override the values used for project resolution, for example on Smart TV platforms if the user agent isn't identifed as a TV. When projectId is set, device targets are ignored and that project is loaded.

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. Returns a Promise that resolves when the load has been handled, with false if the bridge request failed (a view.error is emitted too).

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 is resolved for the device
programId	Program ID	String	Required
env	Which environment to load URL for: prod, staging or dev. Any other value fails to load. Defaults to "prod"	String	Optional
params	Parameters to the Ease Live web app. Replaces the params set in the constructor, so pass userId and streamId again	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 on every video timeupdate event (~4x per second). The timecodes should be milliseconds since 1970-01-01T00:00:00Z (Unix timestamp). Use Math.floor() to strip decimals.

Important: This event must be emitted frequently for proper overlay synchronization. Use interpolation between timecode source updates.

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

player.seek

Seek to a relative offset in the video.

Value	Description	Type	Required
offset	Offset in milliseconds from current time	Integer	Required

player.position

Reports the current playback position.

Value	Description	Type	Required
position	Current position in seconds	Float	Required
duration	Total duration in seconds	Float	Optional

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.

Stage

Events

stage.clicked

Fired when user clicks on the overlay background or presses remote Back button. Use this to toggle player controls visibility.

Simple pattern (recommended for web):

easeLive.on('stage.clicked', () => {
  controls.classList.toggle('visible');
});

TV/Spatial navigation pattern:

When user clicked on empty part of the overlay or pressed remote Back button at the root:

• set your player controls visible if they are not visible already
• set focus to some element inside the player controls
• optionally hide the viewContainer to hide the overlay while player controls are visible

When user clicks in the overlay while controls are visible or navigates into a new scene:

• set your player controls hidden if they are not hidden already
• set EaseLive's viewContainer visible if it is not visible already
• set focus to EaseLive using easeLive.focus()

Note: bridge.stage is also emitted for backwards compatibility.

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.

Also fired when the bridge metadata request fails (for example, an invalid programId returns a 404).

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