Skip to end of metadata
Go to start of metadata


Content Meta-Data describes a viewable title that will be shown to the user. Content may be any supported type of video and the meta-data 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. 

The content meta-data 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 meta-data 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.  The first variant is used when there is one stream URL, typically an HLS or smooth streaming manifest URL.  The second variant 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 meta-data 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.

AttributeTypeValuesExample

ContentType

String

Indicates content type:
movie
episode
season
series
audio

Attribute missing:
NotSet

"movie"

Title

String

Content title:
movie title for films,
episode title for TV series

"The Dark Knight"

TitleSeason

String

Season title for TV series

"Battlestar Galactica Season 5"

Description

String

Description of content

"Batman, Gordon and Harvey Dent are forced…"

SDPosterUrl

String

URL for SD content artwork

http://www.myco.com/img/sd1932.jpg

HDPosterUrl

String

URL for HD content artwork

http://www.myco.com/img/hd1932.jpg

ReleaseDate

String

Formatted Date String

"3/31/2009"

Rating

String

Selects an icon to be displayed for the corresponding MPAA or TV rating, that is, the value will display as an icon artwork.

See Rating Attribute Icons for a list of the acceptable values and the corresponding icon.

"PG-13"

StarRating

Integer

Specifies the star rating to display as red star icon artwork, as a number from 1 to 100:

20 displays one star
40 displays two stars
60 displays three stars
80 displays four stars
100 displays five stars

Numbers not divisible by 20 are displayed as a fractional star. (A number of 30 will display one and a half stars.)

80

UserStarRating

Integer

Specifies the user star rating to display as yellow star icon artwork, as a number from 1 to 100:

20 displays one star
40 displays two stars
60 displays three stars
80 displays four stars
100 displays five stars

Does not display fractional stars for numbers not divisible by 20.

80

ShortDescriptionLine1

String

Line 1 of Poster Screen Description

"The Dark Knight"

ShortDescriptionLine2

String

Line 2 of Poster Screen Description

"Rent $1.99, Buy $14.99"

EpisodeNumber

String

Episode Number

"1"

NumEpisodesIntegerNumber of episodes for a "season" or "series" contentType40

Actors

roArray

List of Actor Names

[
"Brad Pitt",
"Angelina Jolie"
]

Actors

String

Individual Actor Name

"Brad Pitt"

Directors

roArray

List of Director Names

[
"Joel Coen",
"Clint Eastwood"
]

Director

String

Individual Director Name

"Christopher Nolan"

Categories

roArray

List of Category/Genre Names

[
"Comedy",
"Drama"
]

Categories

String

Individual Category/Genre Name

"Comedy"

Album

String

roSpringboard audio style uses this to display the album

"Achtung"

Artist

String

roSpringboard audio style uses to show artist

"U2"

TextOverlayUL

String

roSlideShow displays this string in Upper Left corner of slide

"Joe's Photos"

TextOverlayUR

String

roSlideShow displays this string in Upper Right corner of slide

"3 of 20"

TextOverlayBody

String

roSlideShow displays this string on the bottom part of slide

"Wanda's 40'th Birthday"

Playback Configuration Attributes

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

Attribute

Type

Values

Example

Live

Boolean

Optional flag indicating video is live. Replaces time remaining in progress bar to display "Live". Default is false.

True

Url

String

Image URL for roSlideShow or roImageCanvas, stream URL for Scene Graph Video node

http://www.myco.com/img/vacation.jpg

SDBifUrl

String

BIF URL for SD trick mode

http://www.myco.com/bif/sd1932.bif

HDBifUrl

String

BIF URL for HD trick mode

http://www.myco.com/bif/hd1932.bif

FHDBifUrlStringBIF URL for FHD trick modehttp://www.myco.com/bif/fhd1932.bif

Stream

roAssociativeArray

Supported by roVideoPlayer and roVideoScreen, but not the Roku Scene Graph Video node. For the Video node, use the top level url, streamformat, etc. attributes. The exception is cases where you don't have adaptive streams (typically MP4) and need to specify different bitrate variants separately. For this use case use the Streams attribute.

roAssociativeArray that has parameters representing the stream settings that were set as individual roArrays in previous firmware revisions. The old method is still supported and descriptions of the parameters can be found under those content-meta data entries. For url please see StreamUrls, for quality it is now a Boolean that is true for HD quality.

KeyType
urlString
bitrateInteger
qualityBoolean
contentidString
stickyredirectsBoolean


url : "http://me.com/big.m3u8"
quality : true 
contentid : "big-hls"
}

Streams

roArray of roAssociativeArrays

Used by roVideoPlayer and roVideoScreen to specify the content metadata for a set of fixed bitrate streams. Each array item specifies the URL, bitrate, etc. for one stream variant.

Please note that setting stream content metadata using the Streams value is recommended for non-adaptive video (such as MP4 progressive download) only. For adaptive streaming, use the Stream metadata value.

KeyType
urlString
bitrateInteger
qualityBoolean
contentidString
stickyredirectsBoolean



url : "http://me.com/x-384.mp4",
bitrate : 384
quality : false
contentid : "x-384"
},
{
url : "http://me.com/x-2500.mp4",
bitrate : 2500
quality : true
contentid : "x-1500"
}
]

StreamBitrates

roArray

Array of bitrates in kbps for content streams used.

Please note that setting stream bitrates using this value is recommended for non-adaptive video (such as MP4 progressive download) only.

Must be used in conjunction with StreamUrls and StreamQualities.


[
384,
500,
1000,
1500
]

StreamUrls

roArray

Array of URL's for content streams.

Please note that setting stream urls using this value is recommended for non-adaptive video (such as MP4 progressive download) only.

Must be used in conjunction with StreamBitrates and StreamQualities.


[
"http://www.myco.com/vid/1932-1.mp4",
"http://www.myco.com/vid/1932-2.mp4",
"http://www.myco.com/vid/1932-3.mp4",
"http://www.myco.com/vid/1932-4.mp4"
]

StreamQualities

roArray

Array of Strings quality indicators identifying a stream as "SD" or "HD"

Must be used in conjunction with StreamBitrates and StreamUrls.

[
"SD",
"SD",
"SD",
"HD"
]

StreamContentIDs

roArray

Array of String values logged in Roku logs to identify stream and bitrate played.

[
"myco-19321-384.mp4",
"myco-19321-500.mp4",
"myco-19321-1000.mp4",
"myco-19321-1500.mp4"
]

StreamStickyHttpRedirects

roArray

Array of Boolean values indicating if the HTTP endpoint should be sticky and not subject to change on subsequent requests. Default is false.

[
false,
false,
false,
false
]

StreamStartTimeOffset

Integer

Optional. Default is 0.
The offset into the stream which is considered the beginning of playback. Time in seconds.

3600

(one hour)

StreamFormat

String

Type of content Default: H.264/AAC in .mp4 Container

Valid values: mp4, wma, mp3 Note: mp4 will also accept .mov and .m4v files.

"hls"

"ism" (smooth streaming)

"dash" (MPEG-DASH)

"mkv", "mka","mks"

Deprecated Since Firmware version 4.1:

"wmv"

 

Length

Integer

Movie Length in Seconds

Length zero displays at 0m, Length not set will not display.

3600

(one hour)

BookmarkPosition

Integer

BookmarkPosition sets the default start position, in seconds, for this content. The player will start playback at this position in the content unless an explicit seek position was set. An explicit seek position can be set by calling seek on the player or after a user has selected a starting point via the trickplay UI.

Users are allowed to seek to positions prior to BookmarkPostion in the content. This value takes precedence over the PlayStart value.

1950

(32 minutes, 30 seconds)

PlayStart

Integer

PlayStart defines the start position of the content, in seconds. The player is not allowed to move to a position prior to this point. Any seek operation prior to this point will be clipped to PlayStart.

Channels can use PlayStart and PlayDuration to split one content piece into multiple clips and insert these clips with other content (typically advertisements) into one content list.

0

PlayDuration

Integer

Optional Playback Max Duration in Seconds

120

(two minute preview)

ClosedCaptionsBooleanBoolean indicating if CC icon should be displayed.True

HDBranded

Boolean

Boolean indicating if HD branding should be displayed

True

IsHD

Boolean

Boolean indicating if content is HD

True

SubtitleColor

String

Theme metadata attribute that specifies the color to use when rendering subtitle text

"#FF0000"

SubtitleConfig

roAssociativeArray:
{
TrackName:
String
}

Specifies the caption settings for content playback. TrackName sets the name of the caption track to render. This string is a concatenation of the track source and track id, separated by a "/". Valid track sources are: "ism", "mkv", "eia608" and "dvb".The track id must match the track identifier in the smooth or mkv manifest. For example if an mkv file has a caption track called “english1” the TrackName to select this track is “mkv/english1”.

When the track source is "dvb", the track id is the three-letter language code, with "_sdh" appended for subtitles for the deaf and hard of hearing. For example, "dvb/eng_sdh" are English subtitles for the deaf and hard of hearing and "dvb/nor" are normal Norwegian subtitles.

For side loaded caption tracks the TrackName is the url from where the caption track can be downloaded. Side loaded caption formats can include srt, ttml, and dfxp.

The SubtitleConfig content metadata attribute was added to the Roku platform with the 5.4 firmware for the Roku Streaming Stick HDMI Version.

Note that this setting is used to specify the default closed caption track to render. If a piece of video content support multiple side loaded (not in stream) caption tracks, they all also need to be defined in SubtitleTracks.

{
TrackName :  "mkv/english1"
}

 

SubtitleTracks

roArray of roAssociativeArray:
[{
Language:
String
Description:
String
TrackName:
String
},...]

SubtitleTracks sets the list of available caption tracks available to the stream. This list is added to the track list in the closed caption configuration dialog that is displayed during video playback when the user presses the Roku remote control * button. The captions from the selected track are then displayed on the screen.

Language specifies the ISO 639.2B 3 character language code. This string is used to match the proper caption track with the audio language.

Description specifies the text that will be shown for the corresponding track in the closed caption configuration dialog.

TrackName sets the name of the caption track to render. This string is a concatenation of the track source and track id, separated by a "/". Valid track sources are: "ism", "mkv", and "eia608". The track id must match the track identifier in the smooth or mkv manifest. For example if an mkv file has a caption track called “english1” the TrackName to select this track is “mkv/english1”.

For side loaded caption tracks the TrackName is the url from where the caption track can be downloaded. Side loaded caption formats can include srt, ttml, and dfxp.

The SubtitleTracks metadata is generally only used for side loaded captions. The Roku firmware detects in-stream captions and thus specifying SubtitleTracks in this case is not necessary.

 

SubtitleUrl

String

Specifies the path to an SRT or TTML formatted file used to render subtitles or closed captions, respectively. This is supported on roVideoScreen only.  See Closed Caption Support for additional details.

"http:// www.myco.com/vid/1932.srt"

"http://www.myco.com/vid/1932.xml"

VideoDisableUIBoolean

If set to true, hides the Scene Graph Video node trick play UI

If set to false (the default) shows the Scene Graph Video node trick play UI

video = createObject("roSGNode", "Video")

video.content.VideoDisableUI = true

EncodingTypeString

Specifies the encoding scheme for PlayReady DRM, by setting to one of the following values:

PlayReadyLicenseAcquisitionUrl
If specified, the EncodingKey attribute contains the PlayReady license acquisition URL

PlayReadyLicenseAcquisitionAndChallenge
If specified, the EncodingKey attribute contains the PlayReady license acquisition URL plus additional custom request data

 

EncodingKeyString

Specifies the PlayReady license acquisition URL, and additional custom request data, determined by the EncodingType attribute value specified:

PlayReadyLicenseAcquisitionUrl
The EncodingKey attribute contains the PlayReady license acquisition URL

PlayReadyLicenseAcquisitionAndChallenge
The EncodingKey attribute contains the PlayReady license acquisition URL. It also contains additional custom license acquisition URL request data. In this case the EncodingKey string uses the format "URL%%%<customdata>. For example:

EncodingKey =  "http://ipaddress/mylicense%%%data"

 

SwitchingStrategy

String

roVideoPlayer or roVideoScreen:
Specify different stream switching algorithms to be used in HLS adaptive streaming. Only has an effect on HLS streams. Default is "full-adaptation".
 
Possible strategy values:

"unaligned-segments"
This strategy does not require segments to align across variants. Also does not switch as often as full-adaptation.

"full-adaptation"
Uses measured bandwidth and buffer fullness to determine when to switch. This strategy requires that segments align across variants as the HLS spec requires. This is the new default.

"minimum-adaptation"
Uses only measured bandwidth in determining switching strategy. This strategy requires that segments align across variants as the HLS spec requires.

"no-adaptation"
Only switches bitrates on a rebuffer.

"full-adaptation"

Watched

Boolean

Flag indicating if content has been watched

True

ForwardQueryStringParamsBoolean

Controls whether query string parameters from initial HLS stream manifest requests are forward to subsequent segment download requests. The default value is set to true for backwards compatibility.

Available since firmware version 7.5

True
IgnoreStreamErrorsBoolean

When set to true the media player will not stop playback when it runs into a streaming related error for this content. Instead, it will skip to the next item in the content list. If this was the last item in the content list the media player will send a regular completion event (like isFullResult).

Channels are still notified of any errors via an isRequestFailed notification but a new attribute in the event’s GetInfo object tells the channel the error was ignored. See the changes related to isRequestFailed for more information. The default value is false.

Available since firmware version 7.5

video_details = {

    streamFormat: "mp4"

    ignoreStreamErrors: true

    streams: [{bitrate: 537, height: 360, width: 640, url: “https://..."}]

}

AdaptiveMinStartBitrateInteger

Minimum startup bitrate specified in kbps. Streaming will start with a variant equal to or greater than this value. If this value is not set or if it's set to zero, any minimum start bitrate will be ignored.

Available since firmware version 7.5

5000
AdaptiveMaxStartBitrateInteger

Maximum startup bitrate specified in kbps. Streaming will start with a variant less than or equal to this value. If this value is not set, it will default to 2500 kbps.

Available since firmware version 7.5

2000

Scene Graph Certificate Attributes

The Scene Graph 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:

Attribute

Type

Values

Example

HttpCertificatesFileuri

If set, the Scene Graph Audio or Video node loads this public certificate bundle, to authenticate the server. The protocol must be https for this to have any effect.

When used with a Scene Graph Audio or Video node, the node or global HttpAgent is found, as explained elsewhere in this documentation. When playing this content, the agent is updated in the following manner:

  • If this attribute is defined, the file URI is set into the HttpAgent instance. However, if this attribute is specified and the value is the empty string (""), then no changes will be made to the HttpAgent.
  • If this attribute is not defined, the behavior depends upon whether the Content Meta-Data (CMD) contains secure (https) URLs:
    • If no secure URLs exist in the meta-data, then no certificates file path is set into the agent.
    • If a secure URL does exist, the platform's default certificates are set into the agent.
 
HttpCookiesarray of strings

If set, the Scene Graph Audio or Video node send the cookies to the server. Each cookie must have the following syntax: dom=domain;path=path;name=name;val=value;

When used with a Scene Graph Audio or Video node, the node or global HttpAgent is found, as explained elsewhere in this documentation. When this Content Meta-Data is played and this attribute is set, all HTTP cookies in the agent are cleared and replaced with the cookies defined by this attribute.

 
HttpHeadersarray of strings

If set, the Scene Graph Audio or Video node sends these headers to the server. Each string must be of the format "name:value"

When used with a Scene Graph Audio or Video node, the node or global HttpAgent is found, as explained elsewhere in this documentation. When this Content Meta-Data is played and this attribute is set, all HTTP headers in the agent are cleared and replaced with the headers defined by this attribute.

 
HttpSendClientCertificateBoolean

If true, the Scene Graph Audio or Video node sends the client device certificate to the server, for client authentication. The protocol must be https for this to have any effect.

When used with a Scene Graph Audio or Video node, the node or global HttpAgent is found, as explained elsewhere in this documentation. When this Content Meta-Data is played and this attribute exists, the value of this attribute (true or false) is set into the HttpAgent.

 

Playback Control Attributes

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

AttributeTypeValuesExample

MinBandwidth

Integer

roVideoPlayer or roVideoScreen:
Will only select variant streams with a bandwidth higher than this minimum bandwidth. Units are kbps.
By default Wowza servers set streams to 64 kbs, so you might want to set this parameter to something smaller than 64 when first testing Wowza streams. You will eventually want to specify the Wowza bitrates with a smil file (Please see the encoding guide.)

48

MaxBandwidth

Integer

roVideoPlayer or roVideoScreen:
Will only select variant streams with a bandwidth less than this maximum bandwidth. Units are kbps.

2500

AudioPIDPref

Integer

roVideoPlayer or roVideoScreen If the specified preferred PID audio stream exists, it will be chosen. Otherwise the last audio stream will be chosen.  This is valid only for HLS streams.

This attribute is deprecated.  Use AudioLanguageSelected instead for channels running on 4.8 and later firmware.

483

FullHD

Boolean

roVideoPlayer or roVideoScreen
Specify that this stream was encoded at 1080p resolution.

true

FrameRate

Integer

roVideoPlayer or roVideoScreen
Specify the 1080p stream was encoded at 24 or 30 fps.

24

Track ID Attributes

AttributeTypeValuesExample

TrackIDAudio 

String

roVideoPlayer or roVideoScreen:
Used in SmoothStreaming (StreamFormat = "ISM") to specify

Set the TrackIDAudio field to the desired track's StreamIndex.Name attribute from the manifest file.

"Spanish"

TrackIDVideoString

roVideoPlayer or roVideoScreen:
Used in SmoothStreaming (StreamFormat = "ISM") to specify

Set the TrackIDVideo field to the desired track's StreamIndex.Name attribute from the manifest file.

"h264video"
TrackIDSubtitleString

roVideoPlayer

Used to specify a closed caption track in a video stream that supports 608/708 captions.

"eia608/1"
AudioFormatString

roSpringboardScreen

If set to "dolby-digital", will display a "5.1 ))" icon in the lower left of a movie style springboard screen.

"dolby-digital"
AudioLanguageSelectedString

roVideoPlayer or roVideoScreen:

An ISO-639 3-letter language code.  If multiple language tracks are available in the content, this specifies the one that should be used.

"eng"

roListScreen Attributes

AttributeTypeValuesExample
SDBackgroundImageUrlString

roListScreen:

URL for the SD background image

http://www.myco.com/images/bg1_sd.jpg

HDBackgroundImageUrlString

roListScreen:

URL for the HD background image

http://www.myco.com/images/bg1_hd.jpg

roImageCanvas Attributes

AttributeTypeValuesExample

SourceRect

Associative Array:
{
x: Integer
y: Integer
w: Integer
h: Integer
}

roImageCanvas:
The rectangle from the image that should be drawn. The default is the entire image at the origin.

Note the values must be of type Integer.  Other numeric types such as Float will be ignored and treated as 0.
Note that BrightScript returns a Float by default when doing division.
You can convert calculated values to integer values using the Int() or Fix() functions, for example, if needed.

{
x : 100,
y : 100,
w : 200,
h : 200
}

TargetRect

Associative Array:
{
x: Integer
y: Integer
w: Integer
h: Integer
}

roImageCanvas:
The rectangle where the text/or image should be drawn. The default is the entire image at the origin.

Can also be used with roFontMetrics to provide a target rect for the desired font size.

Note the values must be of type Integer.  Other numeric types such as Float will be ignored and treated as 0.
Note that BrightScript returns a Float by default when doing division.
You can convert calculated values to integer values using the Int() or Fix() functions, for example, if needed.

{
x : 400,
y : 200,
w : 200,
h : 200
}

TargetTranslation

Associative Array:
{
x: Integer
y: Integer
}

roImageCanvas: The amount to translate the coordinate system prior to drawing the image and/or text.
Translation is done before rotation.
Default: {0, 0}

Note the values must be of type Integer.  Other numeric types such as Float will be ignored and treated as 0.
Note that BrightScript returns a Float by default when doing division.
You can convert calculated values to integer values using the Int() or Fix() functions, for example, if needed.

{
x : 100,
y : 100
}

TargetRotation

Float

roImageCanvas:
The angle (in degrees) to rotate the coordinate system
prior to drawing the image and/or text.
Default: 0

90.0

CompositionMode

String

roImageCanvas:
Either "Source" (where source pixels completely replace destination pixels) or "Source_Over" (where source pixels are alpha blended with destination pixels).

"Source_Over"

Text

String

roImageCanvas:
The text is drawn into the
TargetRect.

"Hello ImageCanvas"

TextAttrs

Associative Array

See TextAttrs Attribute Keys for descriptions of the array keys.

{
Color : "#FFCCCCCC", 
Font : "Medium", 
HAlign : "HCenter", 
VAlign : "VCenter",
Direction : "LeftToRight"
}

TextAttrs Attribute Keys

KeyTypeDescriptionExample

Color

String

roImageCanvas (applies to text and other colors):
A color can be specified as an opaque color 24-bit RGB value (#RRGGBB) or as a color with alpha 32-bit ARGB value (#AARRGGBB). AA (alpha), RR (red), GG (green), and BB (blue) are 8-bit values specified as hexadecimal values 00..FF.

When specified as a 32-bit color, the alpha channel bits in the color value range from 00=transparent to FF=opaque. The alpha channel enables blending the background with the images.

Default: "#FFFFFF" (opaque white)

"#FF0033FF"

Font

String

roImageCanvas (applies to text):
"Small","Medium","Large", or "Huge".
Default: "Medium"
Also can use any fonts registered by the roFontRegistry Object and returned by its Get() method

"Large"

HAlign

String

roImageCanvas (applies to text):
Controls the horizontal alignment of the text in the TargetRect.
Options are: "Left", "HCenter" / "Center" /  "Middle", "Right", "Justify"
Default: "HCenter"

"Right"

VAlign

String

roImageCanvas (applies to text):
Controls the vertical alignment of the text in the TargetRect.
Options are: "Top", "VCenter" / "Center" / "Middle", "Bottom"
Default: "VCenter"

"Bottom"

TextDirection

String

roImageCanvas (applies to text):
"LeftToRight" or "RightToLeft"
Default: "LeftToRight"

"RightToLeft"

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

  • No labels