Skip to main content

Media lists

What you learn​

You're instantiating DIVA Player in your Roku front-end and relying on DIVA Back Office as the video streaming source.

The goal of this article is to build the simplest Roku app to stream a video from the DIVA Back Office. That video comes with some related media lists that Roku users can explore at the bottom of the video player.

Before starting​

  • Ensure the DIVA Back Office instance you rely on is up and running.
  • Ask your video engineers team the <video id> and the related <settings URL>.
  • Get read-and-write access to the VideoMetadata file.

Defining media lists​

See medialists definition.

Understanding the media list behaviors​

This section covers:

Priority of media lists over video lists​

MediaList data takes priority over VideoList data.

If the VideoMetaData response includes data for both MediaList (VideoMetaData.MediaLists) and VideoList (VideoMetaData.VideoList), the VideoList data will be ignored and MediaList will be shown.

Also, if data for Recommendations / Related row and Chain play / Up Next item is present in the MediaLists section (VideoMetaData.MediaLists) of the VideoMetaData response, the Related (VideoMetaData.Related) and UpNext (VideoMetaData.UpNext) data will be ignored.

Catching the selected Recommendations / Related item​

When the Recommendations / Related row data is provided via the MediaLists section, you need to update the mechanism for catching the item that the user selects.

Catch the selection of an item in Recommendations / Related with:

m.dpUtilsNode.observeField("onMediaListItemClick", "onMediaListItemClickHandler")

Find more information about the "onMediaListItemClick" field in the Click behavior section.

Note: With legacy video lists, the code for catching the selection of an item in Recommendations / Related was:

dpUtilsNode.observeField("recommendationRowItemSelect", "handleRecommendationRowItemSelect")

Click behavior​

The default behavior when users click on an item is switch, which plays the clicked video.

To override the click behavior, set the callback in the Diva config file by adding:

sub launchDivaPlayer()
    dpUtilsNode = getDivaPlayerUtilsNode()

    ...
    ' Media List Callback
    ' In case the Main application needs to handle and update behavior on selection of the item from the MediaList Row:
    ' dpUtilsNode.activateMediaListCallback = true
    ' observe on "onMediaListItemClick", get data, update data or close DivaPlayer, send data back to Diva Player by set "returnMediaListSelectedItemData"
    ' In case "dpUtilsNode.activateMediaListCallback" is true the Diva Player after selecting the item on the MediaList Row will wait the "returnMediaListSelectedItemData" call back.

    m.dpUtilsNode.activateMediaListCallback = true
    m.dpUtilsNode.observeField("onMediaListItemClick", "onMediaListItemClickHandler")
    ...

end sub

sub onMediaListItemClickHandler(evt as dynamic)
    'This handler triggers when activated: m.dpUtilsNode.activateMediaListCallback
    'Case 1
    ' In case you need to navigate to the other application page (item detail page or etc.):
    ' 1.) Close the Diva Player,
    ' 2.) Navigate to new page

    'Code Case 1
    '     if m.dpUtilsNode <> invalid
    '         m.dpUtilsNode.callFunc("closePlayer")
    '     end if

    '     Navigate to Item Detail Page

    'Case 2
    ' In case you need to update/return data to Diva Player the Selected Item Data:
    ' 1.) Get selected item data
    ' 2.) Update data/do nothing (allow DivaPlayer to work according to the usual workflow)
    ' 3.) Send m.dpUtilsNode.returnMediaListClickData = data

    'Code Case 2
    m.dpUtilsNode.returnMediaListClickData = evt.getData()
end sub

Instantiation​

Write the Basic instantiation code. There's no additional code to write, unless you need to manipulate the media list or insert it after making changes.

Working sample code (.brs)​

sub launchBOAdapter(divaLaunchParams as object)
    ...
    ' Observe BO Adapter VideoMetaDataNode
    m.boAdapterNode.observeField("videoDataNode", "onBOAdapterVideoDataNodeHandler")
    ...
end sub

sub onBOAdapterVideoDataNodeHandler(evt as dynamic)
    data = evt.getData()

    data.addFields({
        mediaLists: [
            {
                "behavior": "multistreamSwitch",
                "listId": "SWITCH",
                "rowTitle": "Watch today's matches",
                "defaultItemType": "video",
                "showInEndOfPlay": true,
                "items": [
                    {
                        "itemId": "videoID_1",
                        "title": "1. Title",
                        "caption": "1. subtitle",
                        "imageUrl": "https://***/425x239.jpg",
                        "adBadge": true,
                        "ccBadge": true,
                        "channelLogo": "https://***/channellogo.png",
                        "lockicon": "https://***/locked.png",
                        "entitledToView": false
                    },
                    {
                        "itemId": "videoID_2",
                        "title": "2. Title",
                        "imageUrl": "https://***/425x239.jpg",
                        "adBadge": true,
                        "ccBadge": true,
                        "channelLogo": "https://***/channellogo.png"
                    },
                    {
                        "itemId": "videoID_3",
                        "title": "3. Title"
                    }
                ]
            },
            {
                "behavior": "multiview",
                "listId": "MULTISTREAM",
                "rowTitle": "Watch match from other cameras",
                "showInEndOfPlay": true,
                "defaultItemType": "video",
                "items": [
                    {
                        "itemId": "videoID_2_1",
                        "title": "1. Title",
                        "caption": "1. subtitle",
                        "imageUrl": "https://***/425x239.jpg",
                        "adBadge": true,
                        "ccBadge": true,
                        "channelLogo": "https://***/channellogo.png",
                        "lockicon": "https://***/locked.png",
                        "entitledToView": false
                    },
                    {
                        "itemId": "videoID_2_2",
                        "title": "2. Title",
                        "imageUrl": "https://***/425x239.jpg"
                    }
                ]
            },
            {
                "listId": "upnext",
                "rowTitle": "UpNext",
                "defaultItemType": "upnext", 'Show only on the End of Play screen (EoP)
                "items": [
                    {
                        "entitledToView": false,
                        "itemId": "videoId",
                        "title": "Title",
                        "imageUrl": "https://***/425x239.jpg",
                        "entitledToView": false
                    }
                ]
            },
            {
                "listId": "related",
                "rowTitle": "Related Videos",
                "defaultItemType": "related", 'Show only on the End of Play screen (EoP)
                "showInEndOfPlay": true,
                "items": [
                    {
                        "itemId": "videoID_1",
                        "title": "1. Title",
                        "caption": "1. subtitle",
                        "imageUrl": "https://***/425x239.jpg",
                        "adBadge": true,
                        "ccBadge": true,
                        "channelLogo": "https://***/channellogo.png",
                        "lockicon": "https://***/locked.png",
                        "entitledToView": false
                    },
                    {
                       "itemId": "videoID_2",
                       "title": "2. Title",
                       "imageUrl": "https://***/425x239.jpg",
                       "adBadge": true,
                       "ccBadge": true,
                       "channelLogo": "https://***/channellogo.png"
                    },
                    {
                        "itemId": "videoID_3",
                        "title": "3. Title"
                    }
                ]
            }
        ]
    })

    ' Setup Diva Player Metadata
    m.dpUtilsNode.callFunc("setMetaData", data)
end sub