Mux Data is the best way to monitor video streaming performance.

Integration is easy - just initialize the Mux SDK, pass in some metadata, and you're up and running in minutes.

1. Getting Started

This documents integration instructions for Roku. For other players, see the additional Integration Guides.

2. Architecture

Mux's Roku integration supports Roku SceneGraph applications, in conjunction with standard Video nodes. Mux runs as a Task alongside the Video node, and supports instances where the Video nodes are reused with additional content as well as when the Video nodes are reset between content.

3. Include the SDK

Place the SDK file in your libs folder. The latest version of the SDK can be found at https://src.litix.io/roku/1/mux-analytics.brs.

4. Setup a new Mux Task

Create a new Task XML named MuxTask.xml inside your components folder and give it the following interface. This is used to link the mux-analytics.brs file into your application.

<component name="MuxTask" extends="Task">
  <interface>
    <field id="video" type="node" alwaysNotify="true"/>
    <field id="config" type="assocarray" alwaysNotify="true"/>
    <field id="rafEvent" type="assocarray" alwaysNotify="true"/>
    <field id="error" type="assocarray" alwaysNotify="true"/>
    <field id="view" type="String" alwaysNotify="true"/>
    <field id="exit" type="Boolean" alwaysNotify="true"/>
    <field id="exitType" type="String" alwaysNotify="true" value="hard" />
  </interface>
  <script type="text/brightscript" uri="pkg:/libs/mux-analytics.brs"/>
</component>

5. Setup the task to respond to video events

Within your main application, create the Mux Task node, and pass the Video node that you are tracking to it. This should be done before the content is set into the Video node so that Mux can track the load process.

m.mux = m.top.CreateNode("mux")
m.mux.setField("video", m.video)

muxConfig = {
  property_key: "EXAMPLE_PROPERTY_KEY",
}

m.mux.setField("config", muxConfig)
m.mux.control = "RUN"

' Load the video into the Video node

6. Test It

After you've integrated, start playing a video in the player you've integrated with. A few minutes after you stop watching, you'll see the results in your Mux account. We'll also email you when your first video view has been recorded.

You can also test that Mux is receiving data in the Mux Data dashboard. Login to the dashboard and find the environment that corresponds to your property_key and look for video views.

Note that it may take a few minutes for views to show up in the Mux Data dashboard.

7. Debugging

To help you with the integration process and ensure you have successfully incorporated the SDK within your player, we have provided a number of optional manifest attributes. These attributes can help you better understand how the MUX SDK event tracking works as well as show you the actual data being collected. Some of the benefits of using some of the debugging attributes (mentioned below) are that you will be able to see the SDK events and data collected as it occurs.

NOTE: The outputs illustrated below are printed on a single line within the terminal to reduce clutter.

mux_debug_events

Values

full, partial or none

Description

Outputs the event at the time it occurs. Default value is none

Example output

Property set to partial:

[mux-analytics] EVENT playerready

Property set to full:

[mux-analytics] EVENT playing 
{
  viewer_application_name:Roku, 
  mux_api_version:2.1, 
  view_seek_duration:0, 
  viewer_application_version:9.20, 
  player_name:Reset Player, 
  viewer_time:1582317809984, 
  view_start:1582317808627, 
  player_model_number:4660X, 
  video_source_mime_type:mp4, 
  event:playing,
  ...

mux_debug_beacons

Values

full, partial or none

Description

Outputs the data (full) or event(s) (partial) that is being sent (at the time of sending). Default value is none.

Example output

Property set to partial:

[mux-analytics] BEACON (2) [  playerready viewstart ]

Property set to full:

[mux-analytics] BEACON (2)
[
  {
    viewer_application_name:Roku, 
    mux_api_version:2.1, 
    view_seek_duration:0, 
    viewer_application_version:9.20, 
    player_name:Reset Player, 
    viewer_time:1582317809984, 
    view_start:1582317808627, 
    player_model_number:4660X, 
    video_source_mime_type:mp4, 
    event:playerready,
    ...
  }, {
    viewer_application_name:Roku, 
    mux_api_version:2.1, 
    view_seek_duration:0, 
    viewer_application_version:9.20, 
    player_name:Reset Player, 
    viewer_time:1582317809984, 
    view_start:1582317808627, 
    player_model_number:4660X, 
    video_source_mime_type:mp4, 
    event:viewstart,
    ...
  }
]

mux_base_url

Values

Protocol + domain name. Eg. https://img.litix.io

Description

Controls to which domain the data should be sent. Useful for environmental builds of your project

8. Add Metadata

The Roku SDK supports adding metadata via two different mechanisms.

The majority of the metadata should be passed inside the muxConfig object that is passed to the Mux Task. You can read detailed information about the fields that are supported in Metadata. To update any field, update this within muxConfig and then call m.mux.setField("config", muxConfig).

Some other underlying information is mapped from standard Roku content metadata, most of which you probably already set when creating your video. In particular, the metadata fields that you should set (if you do not already) are:

• ContentType
• Url
• Live
• StreamFormat
• Length

9. Advertising Configuration

If advertising is to be used, you must send the appropriate events to the Mux Task, as shown below.

function setUpRokuAdFramework
  adIface.SetTrackingCallback(adTrackingCallback, adIface)
end function

function adTrackingCallback(obj = Invalid as Dynamic, eventType = Invalid as Dynamic, ctx = Invalid as Dynamic)
  m.mux = GetGlobalAA().global.findNode("mux")
  m.mux.setField("rafEvent", {obj:obj, eventType:eventType, ctx:ctx})
end function

10. Additional Configuration

In some situations, it is necessary to directly signal the beginning or ending of a view to Mux. This is necessary when the Video Node is recycled (i.e. more pieces of content are loaded into the same Node), or when using advertising, as the ads run outside of the lifecycle of the Video.

Note: A view is defined as the user watching a single piece of content, which includes any advertising.

mux = GetGlobalAA().global.findNode("mux")

' To signal the start of a view:
mux.setField("view", "start")

' To signal the end of a view:
mux.setField("view", "end")

The exitType setting controls the behavior of the task when a request to exit/terminate the thread is invoked (via mux.exit=true). The default value of exitType is hard.

If the value is set to hard then the thread terminates immediately and any data that has not propagated already to the MUX servers is lost.

If the value is set to soft then the thread sends all the remaining data to the MUX servers and terminates afterwards.

To change value to soft call m.mux.setField("exitType", "soft")

NOTE: This means that there might be a time difference between you calling mux.exit=true and the task thread actually terminating. Please ensure you have a single MUX Task running at any given time.

Release Notes

Current Release

v1.0.1

• Fix an issue where the player playhead position was not reported. This has no impact on collected metrics, but fixes a display issue within the dashboard when viewing individual views.

Previous Releases

v1.0.0

• Fix an issue where viewer_user_id was overwritten unintentionally.
• Fix an issue where player_mux_plugin_name and device type were set incorrectly.
• Fix an issue where the seeked event was incorrectly named.
• Provide updated device information to match the intended uses for each field.
• Fix an issue where certain metrics (large numbers) were sent in scientific notation, causing incorrect values to be stored.
• Fix an issue where error code and message were incorrectly sent with aderror events.

v0.2.0

• Remove the debug option of mux_minification. If you set this, it will have no action. Instead, all events and beacons will be logged in an unminified version, while everything will be sent to the Mux backend minified.
• Update such that player_instance_id (controlled by the Mux SDK) is sent as a GUID rather than a different format of ID.

v0.1.0

• Add exitType configuration option
• Fix an issue where source duration is reported incorrectly
• Fix an issue where on certain devices rebuffer percentage could be reported incorrectly (e.g. extremely high)
• Fix an issue where watch_time may have been calculated incorrectly in certain situations
• Fix an issue to allow correctly tracking exits before video start