The attributes, methods and events.
Enums
Name | Type | Description |
---|
ErrorCategory | associative array | Provides a dictionary of Error category names and integer values. |
ErrorCode | associative array | Provides a dictionary of Error code names and integer values. |
Event | associative array | Provides a dictionary of Event type names and string values. |
Attributes
Name | Type | Default | Access Permission | Description |
---|
ads | Ads | Ads | read | Provides events, properties and methods relating to ad playback in the player. See below for more info. |
audioTracks | array of associative arrays | [] | read | Provides information about audio tracks detected automatically in video. Each Associative array has the following fields: id - track identifier, label - track name, language - track language, enabled - true if track is current track |
autoplay | boolean | false | read,write | Whether the player should play the video as soon as it is able after the source has been set. |
controls | boolean | true | read,write | Allows to enable or disable player controls ( true to show controls, false to hide controls). |
currentTime | integer | | read,write | Current timestamp of video. |
duration | integer | | read | Duration of video. |
enableTrickPlay | boolean | true | read,write | Whether trick playback of the media is enabled, and whether the remote buttons will allow trickplay. NOTE: controls must be set to true for this to have any effect. |
subtitleSelectionPreferences | associative array | | write | The significance and priority order of the attributes and values for the subtitle tracks available in the video stream. The selected subtitle track is reflected in the textTracks with mode as "showing" when visible in full screen or "hidden" when not in full screen. Refer to subtitleSelectionPreferences section of Roku's video node documentation. To select a subtitle track, based on user input, use the mode field of the textTracks . |
ended | boolean | false | read | Whether playback of the media is ended. |
errorObject | associative array | | read | The last error that occurred for the current source, if any. |
loop | boolean | false | read,write | Whether playback of the media is looped. |
muted | boolean | false | read,write | Set true to mute and false to un-mute the currently playing video |
paused | boolean | true | read | Whether the player is paused. |
poster | string | | read,write | The poster of the current source. |
seeking | boolean | | read | true when player is seeking, false when player is not seeking now. |
source | Source Description | | read,write | Describes source of current video. |
src | string | | read | The current URL of the media resource. |
textTracks | array of associative arrays | [] | read,write | Provides information about Closed Captions tracks detected automatically in video. Each Associative array has the following fields: id - track identifier, label - track description, language - track language,mode - determines track state, available values: disabled, showing, hidden |
Source Description
The following key/value pairs are supported on the source
attribute of the THEOsdk:THEOplayer
:
Name | Type | Description |
---|
sources | roArray | An array of Typed Sources. When specifying multiple source descriptions, the sources attribute will be interpreted as a playlist where the first typed source will play first and subsequent sources will play when its preceding typed source has ended. |
poster | string | The URL of an image to optionally use as the poster for the media source. This is used for SDPosterUrl, HDPosterUrl, and FHDPosterUrl. |
live | boolean | Whether the asset is live or not. |
drmHttpAgentHeaders | roAssociativeArray | An optional key-value dictionary that contains additional HTTP headers that will be sent for DRM key/license requests. The keys represent the HTTP header names and the values represent their corresponding values. |
ads | roArray | An optional array of AdDescriptions. |
Typed Source
The following key/value pairs are supported on the sources
attribute of a Source Description:
Name | Type | Description |
---|
src | String | The URL of the media resource. |
type | String | The content type (MIME type) of the media resource. Possible values are application/dash+xml and application/x-mpegURL |
title | String | The title of the media resource. |
description | String | The description of the media resource. |
playStart | Number | The position in the stream the user starts playback at. Use negative numbers to offset from the live edge. |
contentProtection | Content Protection | Parameters for DRM playback |
SDBifUrl | String | "Base Index Frames" URL for SD trick mode. |
HDBifUrl | String | "Base Index Frames" URL for HD trick mode. |
FHDBifUrl | String | "Base Index Frames" URL for FHD trick mode. |
ads | roArray of AdDescriptions | Array of the ad description for the ads to play during the content. |
"Base Index Frames" or BIF, is an archive file format that contains a set of still images, also known as "trick play thumbnails", supporting enhanced fast-forward and rewind modes during video playback.
Ad Descriptions
Name | Type | Description |
---|
sources | AdSource or string | Either an AdSource or the URL of the ad XML to load. |
integration | string | The kind of ad integration this uses. Currently the only supported value is csai . |
timeOffset | string or number | An optional value determining when to show the ad. It can either be the number of seconds representing the timecode in the video when the ad should play, or it can be start or end to play the ad either before or after the video. Additionally it could be a percent of the content's duration, like 25% , or a timecode in the format HH:MM:SS . NOTE: This is for VAST ads only. Do not use this with VMAP ads. |
Ad Sources
Name | Type | Description |
---|
src | string | The URL of the XML file to load for the ad break. |
type | string | The optional type of the ad. Supported values are either vast or vmap . Otherwise the default value is inferred from the AdDescription's timeOffset property. |
Content Protection
The following key/value pairs are supported on the contentProtection
attribute of a Typed Source:
Name | Type | Description |
---|
integration | String | Optional attribute. The key system the player should use. Possible values are playready , widevine . |
licenseUrl | String | The licence acquisition URL |
certificate | String | The actual certificate string for Widevine purposes, which must be obtained out-of-band (OOB) by the channel. Leave this unset unless Widevine is used for DRM. |
drmParams | DRM Parameters | An alternative way to set parameters for DRM playback. This attribute is only used when the integration attribute is not set. |
Example DRM source with VuDRM specific headers
To play videos protected using VUDRM, you need to supply a token. Replace the token vualto-demo|2018-06-19T09:18:24Z|YSnJPmEceo
in the code below with your own token as well as the associated values of the keys src
and licenseUrl
.
vuDrmSource = {
sources: [
{
src: "https://d1chyo78gdexn4.cloudfront.net/vualto-demo/big-buck-bunny/big-buck-bunny.ism/manifest.mpd"
type: "application/dash+xml"
contentProtection: {
integration: "widevine"
licenseUrl: "https://widevine-proxy.drm.technology/proxy"
}
}
]
drmHttpAgentHeaders: {
"x-vudrm-token": "vualto-demo|2018-06-19T09:18:24Z|YSnJPmEceo"
"Content-Type": "application/json"
}
}
DRM Parameters
The following key/value pairs are supported on the drmParams
attribute of a Content Protection:
Name | Type | Description |
---|
KeySystem | String | "playready" or "widevine". This value is case-insensitive. The default is an empty string. |
licenseRenewURL | String | A URL location for sending license renewal requests. If not specified, the Roku OS will send renewal requests to the URL specified in the licenseServerURL. This only works with widevine. |
licenseServerURL | String | A URL location of a license server. This URL may include CGI parameters. |
serializationURL | String | A server address used for device provisioning |
serviceCert | String | The actual certificate string for Widevine purposes, which must be obtained out-of-band (OOB) by the channel. Leave this unset unless Widevine is used for DRM. |
lic_acq_window | String | The maximum amount of time (in milliseconds) that a channel waits before rotating its Widevine DRM keys. The channel can generate a random wait time between 0 and the value specified in the lic_acq_window field, and use the random wait time to instruct when the Video node should make its next Widevine license request. Available since Roku OS 10.5 |
Ads API
The Ads API exposes the following properties, methods, and events.
Property | Type | Access Permission | Description |
---|
currentAdBreak | AdBreak | read | The current AdBreak if ads are playing, or invalid if they are not playing. |
currentAds | array of Ads | read | Array of the current Ads in the current AdBreak, or invalid if ads are not playing. |
events | assocarray | read | Map of the event types the Ads API will emit. |
playing | boolean | read | Whether an ad is currently playing. |
rafProxy | RafProxyNode | read | roSGNode that exposes data from the internal RAF library. |
scheduledAdBreaks | array of assocarrays | read | Array of the scheduled breaks that haven't played. These may either be a source object or a resolved AdBreak. |
scheduledAds | array of Ads | read | Array of the ads that are scheduled and have not played. Only shows one break's ads with VAST. |
Method | Description |
---|
addEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string) | Add a listener for the specified player event. |
removeEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string) | Remove a listener for the specified player event. |
schedule(adDescription as AdDescription) | Schedule an ad break. |
Event | Class | Description |
---|
adbegin | AdEvent | The current creative has begun playing. |
adbreakbegin | AdBreakEvent | The player is entering an ad break. |
adbreakend | AdBreakEvent | The player is exiting an ad break. |
adbuffering | AdEvent | The current ad is buffering during playback. |
addadbreak | AdBreakEvent | An ad break has been manually added. |
adend | AdEvent | The current ad has completed playing. |
aderror | Event | There was an error loading or playing an ad. |
adfirstquartile | AdEvent | The viewer has watched the first quartile of the current ad. |
adimpression | AdEvent | The ad has begun playing. |
adloaded | Event | The XML for an ad has been loaded. |
admidpoint | AdEvent | The viewer has watched the half of the current ad. |
adsmanagerloaded | Event | When the RAF ad manager has been initialized. |
adthirdquartile | AdEvent | The viewer has watched the third quartile of the current ad. |
AdEvent and AdBreakEvent
The AdEvent is an event object with the follow properties:
Property | Type | Description |
---|
type | string | The current AdBreak if ads are playing, or invalid if they are not playing. |
date | integer | The current epoch time in milliseconds. |
ad | Ad | The ad associated with the event. |
The AdBreakEvent exposes the same properties as the AdEvent, but adds in a property with the current ad break:
Event | Class | Description |
---|
adBreak | AdBreak | The ad break the event relates to. |
AdBreak
The AdBreak object is an associative array that can have the following properties:
Property | Type | Description |
---|
ads | roArray | An array containing the Ads in the AdBreak. |
customData | assocarray | An associative array with any additional information for this ad break. |
integration | string | The integration that generated the AdBreak. Currently the only supported value is csai . |
maxDuration | integer | The length of the break in seconds. |
timeOffset | integer | The time in the video at which the ad break should play, in seconds. 0 indicates preroll, and -1 indicates postroll. |
The Ad object is an associative array that can have the following properties:
Property | Type | Description |
---|
adBreak | AdBreak | The AdBreak this Ad belongs to. |
adSystem | string | The ad system used to load this ad. |
clickThrough | string | The clickthrough URL for this ad. |
companions | roArray | An array of any CompanionAds associated with this ad. |
creativeId | string | The creative ID for this ad. |
customData | assocarray | An associative array with any additional information for this ad. |
duration | integer | The duration of this ad. |
height | integer | The height of the creative for this ad. |
id | string | The ad ID for this ad. |
integration | string | The integration that generated the ad. Currently the only supported value is csai . |
resourceUri | string | The URI for the creative played in this Ad. |
type | string | The type of ad. Currently only linear is supported. |
width | integer | The width of the creative for this ad. |
The CompanionAd object is an associative array that can have the following properties:
Property | Type | Description |
---|
adSlotId | string | The ad slot id for this companion ad, if any. |
clickthrough | string | The clickthrough URL for this companion ad, if any. |
height | integer | The height of the creative. |
resourceUri | string | The URI of the creative. |
provider | string | The provider of the companion ad, if any. |
width | integer | The width of the creative. |
RafProxyNode
The RAF proxy node has several fields that can be observed to consume data generated by the internal RAF library. This way, an application can access information traditionally available via the getLibVersion
, setRafTrackingCallback
and setAdBufferRenderCallback
methods on RAF.
Property | Type | Access Permission | Description |
---|
bufferRenderUpdate | assocarray | read | An associative array with the properties eventType and ctx . |
libVersion | string | read | The string indicating the version of the RAF library. |
trackingUpdate | assocarray | read | An associative array with the properties eventType and ctx . |
Methods
Method | Description |
---|
addEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string) | Add a listener for the specified player event. |
configure(configuration as THEOPlayerConfiguration) | Configure the SDK, passing in the license ({license: "MY_THEO_LICENSE"} ). |
destroy | Destroy the player. |
getVideoNode | Returns the interior Roku video node. |
pause | Pause playback. |
play | Start playback. |
removeEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string) | Remove the specified listener for the specified player event. |
setCopyGuardManagementSystem(cgms as Integer) | Sets Copy Guard Management System. Acceptable Values: 0 - No Copy Restriction,1 - Copy No More,2 - Copy Once Allowed,3 - No Copying Permitted. |
setDestinationRectangle(w as Integer, h as Integer, x as Integer, y as Integer) | Sets width, height, x, y of player. |
setMaxVideoResolution(width as Integer, height as Integer) | Sets maximum video resolution. |
setPlayerFocus(focused as Boolean, focusReceiver (optional) as roSGNode) | Gives or removes the focus from the internal player. If passing false , you may pass an optional roSGNode to receive the focus. If not passed, the THEOplayer SDK receives focus. |
Events
The event consists of:
- date (timestamp) of occurrence
- type (string) of the event
- extra data
There are several player events being emitted.
addedaudiotrack
: Fired when audio track has been added
addedtexttrack
: Fired when text track has been added
bitratechange
: Fired when the bitrate changes, the extra data emitted is the bitrate
canplay
: Fired when the player can resume playback of the media data, the extra data emitted is the currentTime
canplaythrough
: Fired when the player can resume playback of the media data and buffering is unlikely, the extra data emitted is the currentTime
destroy
: Fired when the the player is destroyed, there is no extra data emitted along
durationchange
: Fired when the duration changes, the extra data emitted is the duration
emptied
: Fired when the player's source is cleared, there is no extra data emitted along
ended
: Fired when playback has stopped because the end of the media resource was reached, the extra data emitted is the currentTime
error
: Fired when an error occurs, the extra data emitted is an associative array e.g.:
{
"error": "<string:error>",
"errorObject": {
"code": <integer:code>,
"message": <string:message>
}
}
loadeddata
: Fired when the player can render the media data at the current playback position for the first time, the extra data emitted is the currentTime
loadedmetadata
: Fired when the player determines the duration and dimensions of the media resource, the extra data emitted is the currentTime
pause
: Fired when the "paused" changes to true, the extra data emitted is the currentTime
play
: Fired when the "paused" changes to false, the extra data emitted is the currentTime
playing
: Fired when playback is ready to start after having been paused or delayed due to lack of media data, the extra data emitted is the currentTime
seeked
: Fired when the "seeking" changes to false after the current playback position was changed, the extra data emitted is the currentTime
seeking
: Fired when "seeking" changes to true, and the player has started seeking to a new position, the extra data emitted is the currentTime
sourcechange
: Fired when the player's source changes, the extra data emitted is an associative array e.g.:
{
"source": {
"sources": [
{
"liveOffset": 4,
"nativeUiRendering": false,
"contentProtection": {
"drmParams": {
KeySystem: "widevine"
licenseServerURL: "https://example.com/license"
}
},
"src": https://example.com/stream.mpd,
"type": "dash"
}
]
}
}
timeupdate
: Fired when the current playback position changed as part of normal playback or in an especially interesting way, for example discontinuously, the extra data emitted is the currentTime