Skip to main content
Version: 9.3.0

Player API

The attributes, methods and events.

Enums

NameTypeDescription
ErrorCategoryassociative arrayProvides a dictionary of Error category names and integer values.
ErrorCodeassociative arrayProvides a dictionary of Error code names and integer values.
Eventassociative arrayProvides a dictionary of Event type names and string values.

Attributes

NameTypeDefaultAccess PermissionDescription
adsAdsAdsreadProvides events, properties and methods relating to ad playback in the player. See below for more info.
audioTracksarray of associative arrays[]readProvides 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
autoplaybooleanfalseread,writeWhether the player should play the video as soon as it is able after the source has been set.
controlsbooleantrueread,writeAllows to enable or disable player controls ( true to show controls, false to hide controls).
currentTimeintegerread,writeCurrent timestamp of video.
durationintegerreadDuration of video.
enableTrickPlaybooleantrueread,writeWhether 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.
subtitleSelectionPreferencesassociative arraywriteThe 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.
endedbooleanfalsereadWhether playback of the media is ended.
errorObjectassociative arrayreadThe last error that occurred for the current source, if any.
loopbooleanfalseread,writeWhether playback of the media is looped.
mutedbooleanfalseread,writeSet true to mute and false to un-mute the currently playing video
pausedbooleantruereadWhether the player is paused.
posterstringread,writeThe poster of the current source.
seekingbooleanreadtrue when player is seeking, false when player is not seeking now.
sourceSource Descriptionread,writeDescribes source of current video.
srcstringreadThe current URL of the media resource.
textTracksarray of associative arrays[]read,writeProvides 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 :

NameTypeDescription
sourcesroArrayAn 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.
posterstringThe URL of an image to optionally use as the poster for the media source. This is used for SDPosterUrl, HDPosterUrl, and FHDPosterUrl.
livebooleanWhether the asset is live or not.
drmHttpAgentHeadersroAssociativeArrayAn 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.
adsroArrayAn optional array of AdDescriptions.

Typed Source

The following key/value pairs are supported on the sources attribute of a Source Description:

NameTypeDescription
srcStringThe URL of the media resource.
typeStringThe content type (MIME type) of the media resource. Possible values are application/dash+xml and application/x-mpegURL
titleStringThe title of the media resource.
descriptionStringThe description of the media resource.
playStartNumberThe position in the stream the user starts playback at. Use negative numbers to offset from the live edge.
contentProtectionContent ProtectionParameters for DRM playback
SDBifUrlString"Base Index Frames" URL for SD trick mode.
HDBifUrlString"Base Index Frames" URL for HD trick mode.
FHDBifUrlString"Base Index Frames" URL for FHD trick mode.
adsroArray of AdDescriptionsArray 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

NameTypeDescription
sourcesAdSource or stringEither an AdSource or the URL of the ad XML to load.
integrationstringThe kind of ad integration this uses. Currently the only supported value is csai.
timeOffsetstring or numberAn 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

NameTypeDescription
srcstringThe URL of the XML file to load for the ad break.
typestringThe 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:

NameTypeDescription
integrationStringOptional attribute. The key system the player should use. Possible values are playready , widevine.
licenseUrlStringThe licence acquisition URL
certificateStringThe 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.
drmParamsDRM ParametersAn 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:

NameTypeDescription
KeySystemString"playready" or "widevine". This value is case-insensitive. The default is an empty string.
licenseRenewURLStringA 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.
licenseServerURLStringA URL location of a license server. This URL may include CGI parameters.
serializationURLStringA server address used for device provisioning
serviceCertStringThe 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_windowStringThe 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.

PropertyTypeAccess PermissionDescription
currentAdBreakAdBreakreadThe current AdBreak if ads are playing, or invalid if they are not playing.
currentAdsarray of AdsreadArray of the current Ads in the current AdBreak, or invalid if ads are not playing.
eventsassocarrayreadMap of the event types the Ads API will emit.
playingbooleanreadWhether an ad is currently playing.
rafProxyRafProxyNodereadroSGNode that exposes data from the internal RAF library.
scheduledAdBreaksarray of assocarraysreadArray of the scheduled breaks that haven't played. These may either be a source object or a resolved AdBreak.
scheduledAdsarray of AdsreadArray of the ads that are scheduled and have not played. Only shows one break's ads with VAST.
MethodDescription
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.
EventClassDescription
adbeginAdEventThe current creative has begun playing.
adbreakbeginAdBreakEventThe player is entering an ad break.
adbreakendAdBreakEventThe player is exiting an ad break.
adbufferingAdEventThe current ad is buffering during playback.
addadbreakAdBreakEventAn ad break has been manually added.
adendAdEventThe current ad has completed playing.
aderrorEventThere was an error loading or playing an ad.
adfirstquartileAdEventThe viewer has watched the first quartile of the current ad.
adimpressionAdEventThe ad has begun playing.
adloadedEventThe XML for an ad has been loaded.
admidpointAdEventThe viewer has watched the half of the current ad.
adsmanagerloadedEventWhen the RAF ad manager has been initialized.
adthirdquartileAdEventThe viewer has watched the third quartile of the current ad.

AdEvent and AdBreakEvent

The AdEvent is an event object with the follow properties:

PropertyTypeDescription
typestringThe current AdBreak if ads are playing, or invalid if they are not playing.
dateintegerThe current epoch time in milliseconds.
adAdThe ad associated with the event.

The AdBreakEvent exposes the same properties as the AdEvent, but adds in a property with the current ad break:

EventClassDescription
adBreakAdBreakThe ad break the event relates to.

AdBreak

The AdBreak object is an associative array that can have the following properties:

PropertyTypeDescription
adsroArrayAn array containing the Ads in the AdBreak.
customDataassocarrayAn associative array with any additional information for this ad break.
integrationstringThe integration that generated the AdBreak. Currently the only supported value is csai.
maxDurationintegerThe length of the break in seconds.
timeOffsetintegerThe 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:

PropertyTypeDescription
adBreakAdBreakThe AdBreak this Ad belongs to.
adSystemstringThe ad system used to load this ad.
clickThroughstringThe clickthrough URL for this ad.
companionsroArrayAn array of any CompanionAds associated with this ad.
creativeIdstringThe creative ID for this ad.
customDataassocarrayAn associative array with any additional information for this ad.
durationintegerThe duration of this ad.
heightintegerThe height of the creative for this ad.
idstringThe ad ID for this ad.
integrationstringThe integration that generated the ad. Currently the only supported value is csai.
resourceUristringThe URI for the creative played in this Ad.
typestringThe type of ad. Currently only linear is supported.
widthintegerThe width of the creative for this ad.

The CompanionAd object is an associative array that can have the following properties:

PropertyTypeDescription
adSlotIdstringThe ad slot id for this companion ad, if any.
clickthroughstringThe clickthrough URL for this companion ad, if any.
heightintegerThe height of the creative.
resourceUristringThe URI of the creative.
providerstringThe provider of the companion ad, if any.
widthintegerThe 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.

PropertyTypeAccess PermissionDescription
bufferRenderUpdateassocarrayreadAn associative array with the properties eventType and ctx.
libVersionstringreadThe string indicating the version of the RAF library.
trackingUpdateassocarrayreadAn associative array with the properties eventType and ctx.

Methods

MethodDescription
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"}).
destroyDestroy the player.
getVideoNodeReturns the interior Roku video node.
pausePause playback.
playStart 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