Ease Live Bridge SDK for Roku

This is a guide for developers to get up and running with the Ease Live Bridge SDK for Roku.

Ease Live's main UI engine is HTML5 based. Unfortunately, Roku does not support WebViews or web apps in any way, and all apps on the Roku platform is written in BrightScript. Ease Live solves this on the Roku by rendering the UI using a combination of native SceneGraph components and cloud rendered Ease Live graphics.

Recommended Roku devices

Any Roku model that supports OpenGL ES 2.0. This includes all currently manufactured and supported devices by Roku.

Adding the SDK to your app

The Bridge object contains APIs available for the Ease Live Bridge SDK. In order to initialize the SDK, we need to add the component as a component library to a Scene or a SceneGraph component and load it over the network:

m.easeLiveSDK = createObject("roSGNode", "ComponentLibrary")
m.easeLiveSDK.id = "EaseLiveSDK"
m.easeLiveSDK.uri = "https://sdk.easelive.tv/roku/1/easelivesdk.zip"
m.easeLiveSDK.observeField("loadStatus", "onLoadStatusChanged")
m.top.appendChild(m.easeLiveSDK)

Once the loadStatus field of the Ease Live component library changes to ready, we can use it to reference the SDK:

function onLoadStatusChanged()
  if m.easeLiveSDK.loadStatus = "ready"
    ' ...
  end if
end function

m.easeLive = createObject("roSGNode", "EaseLiveSDK:EaseLive")
m.easeLive.id = "easeLive"

Next up, add the SDK to your SceneGraph layout:

m.top.appendChild(m.easeLive)

Loading a project

To load an Ease Live overlay, call the load function with the following configuration:

m.easeLive.callFunc("load", {
  accountId: "<ID>"
  projectId: "<ID>"
  programId: "<ID>"
})

Required fields

• accountId: The shorthand ID for the Ease Live account
• projectId: The ID for the project
• programId: The ID for the program

Optional fields

• env: In your project setting you can configure which Studio URL to load in different environments, such as in prod or staging. If you're not sure, just leave it out and it will select prod automatically. Values are prod, staging or dev.
• version: Specify a project version to load. If you leave it out, the SDK will automatically find the latest project version.
• streamId: A custom ID which can be used in timecode settings to configure offsets for custom contexts. To change this during runtime, call the setStream function.

Handling focus

The Roku app should implement handling of moving focus to and from the overlay, and send key events to the overlay while it has focus.

Give focus to Ease Live like this:

m.easeLive.setFocus(true)

When the user decides to leave the Ease Live overlay, for instance to go back to the video player controls or go out of the video stream entirely, you can listen for this by observing focusChanged:

m.easeLive.observeField("focusChanged", "onFocusChanged")

function onFocusChanged()
  if m.easeLive.focusChanged = "unfocused"
    ' return focus to your own components
  end if
end function

Bridge message with focus metadata

When the SDK releases focus, it sends a view.focus event over the bridge. This event has metadata that includes a value with the focus state, and the reason for the change as trigger.

Triggers:

• view.hide – app hidden by program or project configuration
• view.leave – scene does not handle "back"
• focus.none – no focusable targets left
• user.back – user pressed back on the remote

Payload example:

{
  "event": "view.focus",
  "metadata": {
    "value": false,
    "trigger": "user.back"
  }
}

Synchronizing the graphics

Player time

A key feature of Ease Live is the ability to synchronize the overlay graphics with the video. To do this, pick up on timing information in your video player and pass it to Ease Live as a Unix timestamp (milliseconds since 1st of January 1970) in UTC (time zone 0).

m.easeLive.callFunc("setPlayerTime", 1674641327000)

The data type for the timecode, and any variables used to pre-calculate this value, should be of type LongInteger. This is to prevent unexpected overflow.

Player state

Whenever the player is paused, buffering, seeking or just playing, let Ease Live know about the player state:

m.easeLive.callFunc("setPlayerState", "playing")

Supported values are:

• playing
• seeking
• buffering
• paused
• stopped

Set Stream

You can set a streamId to apply a matching timecode offset configured in project and program settings. A streamId declares the stream a client is watching, and any other information used to differentiate between settings. See Managing timecodes for more information.

To set streamId, either pass it along with the other parameters to the load function (can only be called once per instance):

m.easeLive.callFunc("load", {
  ...
  streamId: "stream-1-on-roku"
})

or during runtime (i.e. after load has been called) by using the setStream function:

m.easeLive.callFunc("setStream", "stream-2-on-roku")

Debugging

If the stream is configured with an offset, you should see it change in the debug overlay.

Bridge messages

Going beyond player synchronization, sometimes it's necessary to communicate back and forth between the OTT app and the Ease Live overlays. Example: A native app button opening up a panel within Ease Live.

The actual event name needs to be decided together with the ones working in Studio setting up the project UI. The name can be anything as long as it's a string, but we recommend prefixing it with app. or <yourProduct>..

Send messages

To send a message to the overlays, use the following syntax.

m.easeLive.callFunc("sendMessage", {
  event: "app.myMessage"
})

Receive messages

To listen for messages being sent from the overlays to your app, observe message:

m.easelive.observeField("message", "onMessage")

sub onMessage(event)
  payload = event.getData()

  ' if payload.event = "..."
  '   handleSomeEvent(payload.metadata)
  ' end if
end sub

Video scaling

In Studio, you can use the Bridge -> Send video scale action with the intent to resize and move the video player in your Roku app. Ease Live can't modify the player directly, which is why we send a bridge message player.videoscale with the values necessary for you to implement this in your app.

Event metadata

• scaleX: Horizontal scale factor, between 0 and 1
• scaleY: Vertical scale factor, between 0 and 1
• pivotX: Horizontal anchor for the scaling animation, between 0 and 1
• pivotY: Vertical anchor for the scaling animation, between 0 and 1
• duration: Duration of the scale animation in milliseconds, example 400 (ms)

Code sample

You can use the following code as a reference on how to animate your video player to the values provided in the metadata.

Note

In this example, m.video is the target node. An id is required for the animation to know which node to apply the transformation to.

m.easelive.observeField("message", "onMessage")

...

' Handle bridge events
sub onMessage(event)
  payload = event.getData()

  if payload.event = "player.videoscale"
    scaleVideo(payload.metadata)
  end if
end sub

' Initialize video scale
sub initVideoScale()
  if m.videoScale <> invalid then return

  m.videoScale = {
    origin: m.video.boundingRect()
  }

  ' Create animation and interpolator nodes
  m.videoScale.animation = createObject("roSGNode", "Animation")

  ' Scale interpolator
  m.videoScale.scaleInterp = createObject("roSGNode", "Vector2DFieldInterpolator")
  m.videoScale.scaleInterp.setFields({
    key: [0.0, 1.0]
    fieldToInterp: m.video.id + ".scale"
  })
  m.videoScale.animation.appendChild(m.videoScale.scaleInterp)

  ' Pivot point interpolator
  m.videoScale.pivotInterp = createObject("roSGNode", "Vector2DFieldInterpolator")
  m.videoScale.pivotInterp.setFields({
    key: [0.0, 1.0]
    fieldToInterp: m.video.id + ".scaleRotateCenter"
  })
  m.videoScale.animation.appendChild(m.videoScale.pivotInterp)

  m.top.appendChild(m.videoScale.animation)
end sub

' Animate video scale
sub scaleVideo(options)
  initVideoScale()

  ' Scale from and to
  fromScaleX = m.video.scale[0]
  fromScaleY = m.video.scale[1]
  toScaleX = options.scaleX
  toScaleY = options.scaleY

  m.videoScale.scaleInterp.keyValue = [
    [fromScaleX, fromScaleY]
    [toScaleX, toScaleY]
  ]

  ' Pivot from and to
  fromPivotX = m.video.scaleRotateCenter[0]
  fromPivotY = m.video.scaleRotateCenter[1]
  toPivotX = m.videoScale.origin.width * options.pivotX
  toPivotY = m.videoScale.origin.height * options.pivotY

  m.videoScale.pivotInterp.keyValue = [
    [fromPivotX, fromPivotY]
    [toPivotX, toPivotY]
  ]

  ' Update duration and start animating
  m.videoScale.animation.duration = options.duration / 1000
  m.videoScale.animation.control = "start"
end sub

To test your implementation, you can use the example project for video scaling.

Debugging

Enable debug mode to display information about the project, program and player on the screen.

m.easeLive.debug = true

When debug is off (default), you can also open up the debug panel by by pressing the following combination on the remote:
Longpress Left for 5 seconds → Up → Right → Left
Using the shortcut again will close the overlay.

Overriding the shortcut

It is recommended to keep the default shortcut, as users are unlikely to trigger it by accident, as well as having a minimal effect on the interface.
Keeping that in mind, you can override it by adding a line to your manifest file like this:

ease_live_debug_overlay_default_shortcut=...

Replace ... with your shortcut in this pattern: key.long+key+key
For example, the default shortcut looks like this: left.long+up+right+left

Alternatively, there's a developer shortcut option that only works while in developer mode:

ease_live_debug_overlay_dev_shortcut=...

Find the supported key strings in the official documentation.

Debugging nodes

To enable debugging of nodes, set this in your manifest:

ease_live_debug_nodes=true

This will render node names, IDs and rectangles around the nodes.

Unload the overlay

To safely remove the overlay from SceneGraph, call the unload function:

m.easeLive.callFunc("unload")

If you want to be notified when the SDK is done removing itself, observe the statusChanged field for unloaded:

m.easeLive.observeField("statusChanged", "onStatusChanged")

function onStatusChanged()
  if m.easeLive.statusChanged = "unloaded"
    ' ...
  end if
end function

SDK status

By observing statusChanged you will know which state the SDK is in. Available states are:

• loading: The SDK is currently loading in the project, graphics and data
• unloaded: The SDK has finished tearing down the UI
• ready: The SDK and overlay is all setup and is ready to be used
• failed: Something went wrong and you should remove the SDK from the scene

Project and program status

The project and program that is loaded into the app, can be visible or hidden based on settings. These can be changed during runtime. Example: Something goes wrong during a game and you want to hide the graphics for everyone already watching.

m.easeLive.observeField("appStatusChanged", "onAppStatusChanged")

function onAppStatusChanged()
  if m.easeLive.appStatusChanged = "disabled"
    ' ... unload the overlays
  end if
end function

• enabled: The overlay is running normally and is displayed on screen
• hidden: The overlay is loaded in, but the graphics are hidden. They can be turned on/off in project and program settings. Whenever the graphics are hidden, focus is given back to the app
• disabled: The project or program is disabled, and you should likely unload the entire SDK

Error handling

If something critical happens and the SDK isn't able to handle it, the error event is triggered. Observe it to make sure you can catch the error and remove the overlay:

m.easeLive.observeField("error", "onError")

function onError(e)
  print e.message
end function

TIP

If an error is thrown, m.easeLive.statusChanged will also be set to failed.

Initial load timeout error

If it takes more than 20 seconds to load the overlays, it means the Bridge hasn't received any data from the API. statusChanged will be set to failed and the following error event will be triggered:

{
  message: "Application load timed out after 20 seconds"
}