Content metadata

Content metadata describes a viewable title that will be shown to the user. Content may be any supported type of video and the metadata is used by the UI to format and display the title to the user. Some attributes (e.g. ContentType) affect how the title is displayed on screen, other attributes (e.g. SDPosterURL) specify where to fetch artwork to display with the content and other attributes (e.g. Title) are just rendered as text.

Overview

The content metadata is stored in an associative array by the script and provided to the various screen objects as needed for display. In some cases an array of content metadata may be provided so that the screen can render multiple items as a list. The attribute names are critical and used as the key to look up the attribute at run time. The following table details the attributes in use. Certain attributes are recognized by particular screens, while others are more globally applicable. If the attribute is not a generally recognized attribute, the table below specifies where the attributes are recognized.

Keep in mind that there are two ways to specify stream content metadata, data.Stream and data.Streams:

• data.Stream: This is used when there is one stream URL, typically an HLS or smooth streaming manifest URL.
• data.Streams: This is used when you have a set of fixed bitrate streams. This is typically the case for non-adaptive MP4 streams, in which case multiple variants are specified to simulate true adaptation.

Descriptive attributes

Descriptive metadata attributes can be used to describe the content item to the user, in a user interface element that allows the user to select the item.

Digital rights management (DRM) control attributes

Digital rights management (DRM) content meta-data control attributes are available in the Roku OS through the drmParams parameter of type roAssociativeArray. The table below enumerates all usable attributes of drmParams.

Note: Not all attributes are required, and may not have the same semantic meaning when applied to different DRM systems.

• when encodingType="PlayReadyLicenseAcquisitionAndChallenge", the EncodingKey attribute contains the PlayReady license acquisition URL plus additional custom license acquisition request data in format "URL%%%" Note, this is the same value that used to be specified directly in Content Metadata structure The app just needs to set drmParams.licenseSererUrl.

Passing custom HTTP headers to licensing requests

Developers looking to pass custom HTTP headers with a licensing request can now set those headers using the ifHttpAgent interface methods on the Video node.

Example of configuring a dash stream with Widevine DRM

contMeta = {
    HDPosterUrl:"pkg:/images/BigBuckBunny.jpg"
    SDPosterUrl:"pkg:/images/BigBuckBunny.jpg"
    ShortDescriptionLine1:"Parking Wars(VOD)"
    ShortDescriptionLine2:"dash | widevine"
    Streamformat:"dash"
    SwitchingStrategy:""
    MinBandwidth:500
    VideoUrl: "http://dev.domain.com/mm/dash/vod/173850/85768039/TG_W_WIFI.mpd"
    drmParams: { ' setting up DRM config
        keySystem: "Widevine"
        licenseServerURL: "http://msfrn-ci-cp-dev.mobitv.com/widevine/get_license"
    }
}

Example of wrapping the Widevine license challenge payload

The following code demonstrates how you can wrap the Widevine license challenge payload in the request format (JSON or XML) required by your license server proxy.

// set the content type
// for json it may be set to "application/json
// for xml it may be set to "text/xml" or "application/xml"
// if your license proxy cannot handle these content types,
// don't specify anything. The default content type
// used by Roku firmware is "text/plain", and most proxies
// seem to handle this content type
httpAgent = CreateObject("roHttpAgent")
httpAgent.AddHeader("Content-Type", "<contentType>")
m.video.drmHttpAgent = httpAgent   
videocontent = createObject("RoSGNode", "ContentNode")
videocontent.drmParams = {     
            keySystem: "Widevine"
            name: "Widevine"
            licenseServerURL: "https://proxy.uat.widevine.com/proxy?provider=widevine_test"
            licReqTemplate: "license request template"
            templateType: "JSON"
            requestField: ".parameters[0].body"
            responseField: ".output.widevine2License.license"
        }
...
m.video.content = videocontent   

Content classification attributes

Available since Roku OS 13.0

Developers can use the contentClassifier content metadata attribute to specify the genre of their content (for example, action, sports, or comedy), and the Roku OS will use this attribute to automatically adjust the sound and picture on Roku TVs (if auto mode is selected for the picture or sound settings).

Content classifier value

Content classifier sound and picture modes

The following table details how the different contentClassifier attribute values are mapped to sound and picture modes on Roku TVs.

Playback configuration attributes

Playback configuration meta-data attributes are used to configure the playback of the content item.

video_details = {
    streamFormat: "mp4"
    ignoreStreamErrors: true
    streams: [{bitrate: 537, height: 360, width: 640, url: “https://..."}]
}

CDN switching

Content Delivery Networks (CDNs) can be switched during playback to load balance traffic and failover to different servers in order to help optimize performance. The CdnConfig attribute can be used for managing load balancing and failovers.

Example

this.cur_clip.CDNConfig = [
    {URLFilter:"http://cdn1.xyz.com/abc/", ContentFilter, “testProgram”, priority: 1, weight: 50, serviceLocation: "west"},
    {URLFilter:"http://cdn2.xyz.com/abc/", ContentFilter, “testProgram”, priority: 1, weight: 50, serviceLocation: "east"},
    {URLFilter:"http://cdn1.xyz.com/abc/", ContentFilter, “testProgram”, priority: 2, weight: 50, serviceLocation: "west"},
    {URLFilter:"http://cdn2.xyz.com/abc/", ContentFilter, “testProgram”, priority: 2, weight: 50, serviceLocation: "east"},
]

SceneGraph certificate attributes

The SceneGraph certificate meta-data attributes are used to configure the use of HTTP certificates and cookies by the Audio and Video nodes. Please note that when setting any of the following four attributes on a Video or Audio node, you need to be careful that the values are set on the correct HTTPAgent. If the node does not have its own HTTPAgent, set by explicitly calling setHttpAgent() on the node, the Roku OS will traverse up the scene graph hierarchy until it finds the first node in the Video or Audio node's ancestry that has set an HTTPAgent. If none is found, the values will be set on the global HTTPAgent which is always guaranteed to exist. Therefore if you expect the header, etc. values set to only apply to your Audio and Video nodes, create a unique instance of roHttpAgent for them and assign it directly. For example, for a Video node you should do the following:

'Assume video is a valid Video node instance

httpAgent = CreateObject("roHttpAgent")
video.setHttpAgent(httpAgent)

drmHttpAgent for handling DRM key/license requests separately

Since Roku OS 9.3, you can create a separate agent to handle DRM key and license requests, apart from other types of requests.

Once you have created your agent, you can set the Video node's drmHttpAgent field directly to designate that the special agent is to supersede any currently-set agent in the case of DRM key and license requests. The drmHttpAgent field must be configured before setting the content in the Video node.

' Configure the DRM HttpAgent before setting content in the Video node
 httpAgent = CreateObject("roHttpAgent")
 httpAgent.AddHeader("DRM-Specific-1", "weqweqweqweqweqweqeqeqeqeqwe")
 httpAgent.AddHeader("DRM-Specific-2", "fgfgfgfgfgfgfgfgfg")
 httpAgent.AddHeader("DRM-Specific-3", "zxzxzxzxxzxzxzxzxzx")
 m.video.drmHttpAgent = httpAgent    
 m.video.content = videocontent

If drmHttpAgent is not set (the default), uri fetches for video involving the DRM URLs (serializationURL, licenseServerURL, licenseRenewURL) of ContentMetaData will use the video's regular HttpAgent. However, if the drmHttpAgent is set, the agent cited in the field will be used for those fetches instead.

The "SceneGraph Certificate Attributes" mentioned above all have "Drm" versions, with names formed by the prefixing "Drm" to the "regular" names (e.g., HttpCookies becomes DrmHttpCookies, and so forth). These attributes take precedence over those of the drmHttpAgent.

Playback control attributes

The playback control meta-data attributes are used to control the playback parameters for the content item.

Track ID attributes

roListScreen attributes

Rating attribute icons

The Rating attribute contains the MPAA or TV rating stored as a string. At runtime, the ratings are shown with an icon instead of rendering the string as text. The following table shows the list of valid values for the Rating attribute, and the resulting icon that will be displayed for each value.

Value	Icon
G
NC-17
PG
PG-13
R
UR
UNRATED
NR
TV-Y
TV-Y7
TV-Y7-FV
TV-G
TV-PG
TV-14
TV-MA

Content feed video lesson

You can learn how to link the content metadata in your app's feed to a ContentNode by watching the Creating the content feed video lesson in Roku's SceneGraph: Build an App online video course.