Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

...

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.

Note

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.

Note

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"

Note

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:

"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.

Note
Starting from firmware version 8.1, this attribute is made obsolete. The existing PlayStart attribute does the same thing, and there is no need to have two attributes to set the play start time. The firmware will continue to support BookmarkPosition to maintain the backward compatibility, but channels should use PlayStart.

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.

Starting from firmware 8.0, content metadata supports negative PlayStart values. This feature allows the media players to start playbacks distanced from the edge of the live stream. 

0

PlayDuration

Integer

Optional Playback Max Duration in Seconds

Note
PlayDuration has been deprecated is is no longer used by the media player starting from firmware version 8.1.

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 ormkvmanifest. Forexampleif anmkvfile 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 sideloaded caption tracks, the TrackName is the url from where the caption track can be downloaded. Sideloaded caption formats can include srt,ttml, anddfxp.

Specifying eia608/1 will trigger the firmware to search for embedded 608/708 captions in the stream.

In the 8.0 firmware, automatic track selection based on a preferred caption language setting is introduced. Omit setting a URL here to avoid interfering with the automatic track selection. It is sufficient to add the URLs to 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.

For sideloaded caption tracks the TrackName is the URL from where the caption track can be downloaded. Sideloaded 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
TheEncodingKey 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.
 
"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.

"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
filterCodecProfilesBoolean

Filters out any video profile/codec level combinations that the specified hardware cannot play. The default value is false, in which case no filtering occurs. 

Note
Note that this currently only works for DASH streams.

Available since firmware version 8.0

True
LiveBoundsPauseBehaviorString

Allows a channel to customize Media Player behavior on live streams when playing in the earliest part of a DVR buffer. The stream remains paused even though it is playing in the earliest part of the buffer of a live stream when the value of the attribute is set to "pause." This enables the firmware to distinguish between live streams and live streams that eventually transition to video on demand.

The possible values of this attribute are "resume", "stop", "pause", with resume being the default value.

Note
Currently, this attribute will work only with Smooth and Dash streams.

Available since firmware version 8.1

Resume
ClipStartFloat

ClipStart sets the clip start position of the playback. The unit of ClipStart is seconds.

Available since firmware version 8.1

00.0
ClipEndFloat

ClipEnd sets the clip end position. The unit of ClipEnd is seconds.

Available since firmware version 8.1

00.0
preferredaudiocodecString

Specifies the audio codec that should be used during playback. The Media Player will select and report to the channel only those audio renditions that are encoded with the specified codec. Renditions that are encoded with a different codec are ignored.

Possible values of this attribute are "aac", "ac3" and "eac3".

Available since firmware version 9.0

aac

Scene Graph Certificate Attributes

...