Versions Compared

Key

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

...

FieldTypeDefaultUse
contentContentNodeInvalid

The ContentNode node with the Content Meta-Data for the video, or a video playlist (a sequence of videos) to be played.

If a video playlist is to be played, the children of this ContentNode node comprise the playlist, and each ContentNode child must have all attributes required to play that video. For example, if the videos "A" and "B" are to be played, three ContentNode nodes must be created: the parent ContentNode (which is largely ignored), one ContentNode child for "A," and one ContentNode child for "B." The parent node is set into this content field, and when video playback is started, all of its children will be played in sequence. Any changes made to the playlist after playback has started are ignored. See the contentIsPlaylist and contentIndex fields, for more information on playlists.

contentIsPlaylistBooleanfalse

If set to true, enables video playlists (a sequence of videos to be played). See the content and contentIndex field for more information on playlists.
Available since firmware version 7.2

contentIndexinteger-1

Read-Only
The index of the video in the video playlist that is currently playing. Generally, you would only want to check this field if video playlists are enabled (by setting the contentIsPlaylist field to true), but it is set to 0 when a single video is playing, and video playlists are not enabled.
Available since firmware version 7.2

nextContentIndexinteger-1

If the contentIsPlaylist field is set to true to enable video playlists, sets the index of the next video in the playlist to be played. Setting this field does not immediately change the video being played, but takes effect when the current video is completed or skipped. By default, this value is -1, which performs the default index increment operation. After the video specified by the index in this field begins playing, the field is set to the default -1 again, so the next video played will be set by the default index increment operation unless the field is set again to a different index.
Available since firmware version 7.2

controloption string"none"

Sets the desired play state for the video, such as starting or stopping the video play. Getting the value of this field returns the most recent value set, or none if no value has been set. To dynamically monitor the actual state of the video, see the state field.

The play and stop commands to commence and discontinue playback should not be used to implement trick modes like rewind, or replay. For that use the seek field.

Section
Column
width400px
OptionEffect
noneNo play state set 
playStart video play
stopStop video play
pausePause video play
resumeResume video play after a pause
replayReplay video
prebufferStarts buffering the video stream before the Video node actually begins playback. Only one video stream can be buffering in the application at any time. Setting the control field to prebuffer for another video stream after setting prebuffer for a previous video stream stops the buffering of the previous video stream.
Available since firmware version 7.2

skipcontent

Skip the currently-playing content and begin playing the next content in the playlist. If the content is not a playlist, or if the current content is the end of the playlist, this will end playback.
Available since firmware version 7.2

statevalue string"none"

Read-Only
Describes the current video play state, such as if the video play has been paused.

Section
Column
width400px
ValueMeaning
noneNo current play state
bufferingVideo stream is currently buffering 
playingVideo is currently playing
pausedVideo is currently paused
stoppedVideo is currently stopped
finishedVideo has successfully completed playback
error An error has occurred in the video play. The error code, message, and error message diagnostics can be found in the errorCode and errorMsg fields errorMsg, and errorStr fields respectively.
errorCodeinteger

0

Read-Only
The error code associated with the video play error set in the state field.

errorMsgstring

""

Read-Only
An error message describing the video play error set in the state field.

errorStr 
Anchor
errorStr
errorStr
string""

Read-Only 
A diagnostic message to help resolve the video play error set in the state field.

The format of the errorStr is as follows: category:{category_name}:error:{error_code}:ignored:{0|1}:{source}:{source_name}:{additional catcher comment}:{error_string}:extra:{error_attributes}

errorStr Field
Type
Description
category_namestringThe type of error, which includes: "http", "drm", "mediaerror", or "mediaplayer".
error_codeintegerThe unique code associated with the error.
ignoredinteger Indicates whether the error generated an exception (0) or was ignored resulting in the next item in the content list being played (1).
sourcestringThe module that generated the error.
source_namestringThe module that generated the error.
additional catcher commentstringTypically, the comment added when the exception is caught.
error_stringstring A text message describing the video play error.
error_attributesstringThe error attribute, which includes the clip_id (the unique ID of the clip that failed to play).


Trickplay Fields

FieldTypeDefaultUse
durationDouble0Read-Only
The duration of the video being played, specified in seconds. This becomes valid when playback begins and may change if the video is dynamic content, such as a live event.
loopBooleanfalseIf set to true, the video or video playlist (if the contentIsPlaylist field is set to true to enable video playlists) will be restarted from the beginning after the end is reached.
Available since firmware version 7.2
position Double0

Read-Only

Time of the current position in the stream. Either UTC time or elapsed since start of stream depending on content type

notificationIntervaltime0.5The interval between notifications to observers of the position field, specified as the number of seconds. If the value is 0, no notifications are delivered. This value may be read or modified at any time.
seek
Anchor
trickplayFields_seek
trickplayFields_seek


timeinvalid

Write-Only
Sets the current position in the video. The value is the number seconds from the beginning of the stream, specified as a double.

timedMetaDataassociative array{ }Read-Only
The most recent timed meta data that has been decoded from the video stream. Only meta data with a key that matches an entry in timedMetaDataSelectionKeys will be set into this field. The value of this field is an associative array which contains arbitrary keys and values, as found in the video stream.
timedMetaDataSelectionKeysarray of strings

[ ]

If the video stream contains timed meta data such as ID3 tags, any meta data with a key matching an entry in this array will be set into the timedMetaData field. If any entry in this array is "*", then all timed meta data will be selected.
streamInfoassociative array invalid

Read-Only
Information about the video stream that is currently playing or buffering.

Section
Column
width400px
KeyTypeValue
isUnderrunBooleanIf true, the stream was downloaded due to an underrun
isResumedBooleanIf true, playback was resumed after trickplay
measuredBItrateIntegerThe measured bitrate (bps) of the network when the stream was selected
streamBitrateIntegerThe bitrate of the stream
streamUrlURIThe URL of the stream


 Available since firmware version 7.2

completedStreamInfoassociative arrayinvalidRead-Only
Information about the video stream that most recently completed playing, due to an error, user action, or end of the stream. The associative array consists of the same keys as for the streaminfo field, with one additional key, isFullResult, a Boolean type that, if true indicates the stream played to completion, or if false, was interrupted by an error or user action. This field is set prior to the state field being changed, so state field observer callback functions can assume that the associative array values are valid when the state field changes.
Available since firmware version 7.2
timeToStartStreamingDouble0

Read-Only
The time in milliseconds from playback being started until the video actually began playing. The minimum valid value is 1 millisecond, and this is only valid if the current value of the state field is playing. When the state field value is not playing, the value will be 0. This field is updated prior to the state field changing, so state field observer callback functions can assume this field is valid after the state field value changes to playing.
Available since firmware version 7.2

bufferingStatusassociative arrayinvalid

Read-Only
Contains information about stream buffering progress and status. This field is valid only while buffering is in progress, both at stream startup or when re-buffering is required. Observers will be notified when any element of the array changes, and also when buffering is complete and the field itself becomes invalid. The array contains the following name - value pairs.

Section
Column
width400px
ValueMeaning
percentagePercent buffering complete as an integer.
isUnderrunBoolean value indicating if a stream underrun occurred.
videoFormatstring""

Read-Only
Contains the format of the currently playing video stream.

Section
Column
ValueMeaning
""No stream playing
noneStream contains no playable video
unknownStream contains unknown video
hevcISO/IEC 23008-2, H.265, HEVC
hevc_bISO/IEC 23008-2 Annex-B, H.265, HEVC
mpeg1

ISO/IEC 11172-2, MPEG-1 part 2, H.261

mpeg2 

ISO/IEC 13818-2, MPEG-2 part 2, H.262

mpeg4_2 

ISO/IEC 14496-2, MPEG-4 part 2, H.263

mpeg4_10b 

ISO/IEC 14496-10, MPEG-4 part 10 Annex-B, H.264, vc-1

mpeg4_15 

ISO/IEC 14496-15, MPEG-4 part 15, H.264, vc-1

AVC
vc1 

vc-1

wmv 

Microsoft Windows Media Video

vp8 

VP8 codec

vp9 

VP9 codec
pauseBufferStart Double0Read-Only
The beginning position of the video buffered when paused. This field is only valid for live video.
pauseBufferEnd Double0Read-Only
The ending position of the video buffered when paused. This field is only valid for live video.
pauseBufferOverflow Boolean

false

Read-Only
Indicates that the video buffer was not able to save all video since being paused. This field is only valid for live video.
streamingSegment

associative array

{ }

Read-Only
Information about the video segment that is currently streaming. This is only meaningful for segmented video transports, such as DASH and HLS. The associative array has the following entries:

Section
Column
width400px
KeyTypeValue
segBitrateBpsintegerBitrate of the segment in bits per second
segSequenceintegerThe sequence number of the segment in the video
segStartTimetimeThe start time of the segment from the start of the video, specified in seconds
segUrlstringURL of the segment
downloadedSegmentassociative arrayinvalid
Read-Only
Information about the video segment that was just downloaded. This is only meaningful for segmented video transports, such as DASH and HLS. The associative array has the following entries:
Section
Column
width200px
KeyTypeValue
StatusintegerStatus of the download: 0 = success, nonzero = error
SequenceintegerStream segment sequence number
SegUrlstringStream segment URL (i.e., .ts file for HLS, stream fragment URL for smooth)
DownloadDurationintegerAmount of time spent downloading the segment, in milliseconds
SegSizeintegerSegment size, in bytes
SegTypeintegerType of data in the segment: 1=audio, 2=video, 3=captions, 0=mux
BitrateBPSintegerBitrate of the segment, in bits per second
manifestDataassociative array{ }

This function is available in firmware 7.7 or later.

"manifestData" detect the periods in a DASH manifest before they are played back. One major use case for this is to display ad markers in the trickplay progress bar.

The manifestData field has two elements:

  • "mpd" — roAssociativeArray of string values
  • "periods" — roArray of roAssociativeArrays of string values

The property minimumUpdatePeriod has also been added to control the .mpd element.

The “periods” element includes a Period key for each period in the manifest, with a value of attributes in the Period key. For example, a period might contain the following values: 
{ id="p24895847", start="PT1492010820S", duration="PT60S" }

Some examples of how to access the manifestData would include:

  1. Get a known attribute:
    video.manifestData.mpd.minimumUpdatePeriod

  2. Get a known attribute which has a semicolon in the name:
    video.manifestData.mpd["xmlns:ns1"]

  3. Get a known attribute from existing period:
    video.manifestData.period[0].id

  4. Get number of available periods:
    video.manifestData.periods.Count()

  5. Iterate through all available MPD attributes:
    for each item in video.manifestData.mpd.Items()
      print item.key, "=", item.value
    end for

...

FieldTypeDefaultUse
widthfloat0.0Sets the width of the video play window in pixels. If set to 0.0 (the default), the video play window is set to the width of the entire display screen.
heightfloat0.0Sets the height of the video play window in pixels. If set to 0.0 (the default), the video play window is set to the height of the entire display screen.
enableUIBooleantrue

If set to true (the default), the entire Video node user interface (such as ProgressBar and TrickPlayBar nodes, and BIF navigation) appear in response to stream events and remote control key presses.

If set to false, most of the Video node user interface will not be shown, and the application is expected to implement the UI. The one exception is the closed-caption dialog, which always appears when the video is playing fullscreen and the user presses the * (Info) button

When using the Roku Advertising Framework (RAF), the RAF library may temporarily set this field to false while playing ads.
Available since firmware version 7.2

enableTrickPlayBooleantrue

Controls whether trickplay is allowed during playback. When set to false the user trickplay buttons on the remote will have no effect. This only applies when enableUI is set to true.

bifDisplayBifDisplay nodeinternal instance default 

Component that displays BIFs and allows navigation. The fields of this internal node are as follows:

Section
Column
width400px
FieldTypeDefaultUse
frameBgBlendColorcolor0xFFFFFFFFA color to be blended with the image displayed behind individual BIF images displayed on the screen. The blending is performed by multiplying this value with each pixel in the image. If not changed from the default value, no blending will take place.
frameBgImageUriuri""The URI of an image to be displayed behind individual frames on the screen. The actual frame image is displayed opaquely on top of this background, so only the outer edges of this image are visible. Because of that, this background image typically appears as a border around the video frame. If the frameBgBlendColor field is set to a value other than the default, that color will be blended with the background image.
getNearestFrametimeinvalid

Available starting since firmware version 9 

Write-Only Requests the nearest BIF to the time specified. This would normally be an offset from the current playback position. The getNearestFrame request is passed to the BifCache which uses the getNearestFrame() method implemented on all BIF storage classes. Existing BifCache functionality is then used to retrieve the bitmap data and load it into the texture manager.

nearestFramestring""

Available starting since firmware version 9 

Read-Only Contains the URI of the requested BIF. The returned URIs will be of the form 'memory://BIF_%d_%d'. These URIs can then be used directly in the 'uri' field of a Poster SGN (or similar).

trickPlayBarTrickPlayBar nodeinternal instance default 

The visible TrickPlayBar node. The fields of this internal node are as follows:

Section
Column
width400px
FieldTypeDefaultUse
currentTimeMarkerBlendColorcolor0xFFFFFFFFThis is blended with the marker for the current playback position. This is typically a small vertical bar displayed in the TrickPlayBar node when the user is fast-forwarding or rewinding through the video.
textColorcolorsystem defaultSets the color of the text next to the trickPlayBar node indicating the time elapsed/remaining.
Available since firmware version 7.2
thumbBlendColorcolor0xFFFFFFFFSets the blend color of the square image in the trickPlayBar node that shows the current position, with the current direction arrows or pause icon on top. The blending is performed by multiplying this value with each pixel in the image. If not changed from the default value, no blending will take place.
Available since firmware version 7.2
filledBarBlendColorcolor0xFFFFFFFFThis color will be blended with the graphical image specified in the filledBarImageUri field. The blending is performed by multiplying this value with each pixel in the image. If not changed from the default value, no blending will take place.
Available since firmware version 7.2
filledBarImageUriuri""A 9-patch or ordinary PNG of the bar that represents the completed portion of the work represented by this ProgressBar node. This is typically displayed on the left side of the track. This will be blended with the color specified by the filledBarBlendColor field, if set to a non-default value.
Available since firmware version 7.2
trackBlendColorcolor0xFFFFFFFFThis color is blended with the graphical image specified by trackImageUri field. The blending is performed by multiplying this value with each pixel in the image. If not changed from the default value, no blending will take place.
Available since firmware version 7.2
trackImageUriuri""A 9-patch or ordinary PNG of the track of the progress bar, which surrounds the filled and empty bars. This will be blended with the color specified by the trackBlendColor field, if set to a non-default value.
Available since firmware version 7.2
bufferingBarProgressBar nodeinternal instance default 

Component that shows the progress of re-buffering, after video playback has started. The fields of this internal node are as follows:

Section
Column
width400px
FieldTypeDefaultUse
widthfloatsystem defaultSets a custom width for an instance of the ProgressBar node
Available since firmware version 7.2
heightfloatsystem defaultSets a custom height for an instance of the ProgressBar node
Available since firmware version 7.2
emptyBarBlendColorcolor0xFFFFFFFFA color to be blended with the graphical image specified in the emptyBarImageUri field. The blending is performed by multiplying this value with each pixel in the image. If not changed from the default value, no blending will take place.
emptyBarImageUriuri""A 9-patch or ordinary PNG of the bar presenting the remaining work to be done. This is typically displayed on the right side of the track, and is blended with the color specified in the emptyBarBlendColor field, if set to a non-default value.
filledBarBlendColorcolor0xFFFFFFFFThis color will be blended with the graphical image specified in the filledBarImageUri field. The blending is performed by multiplying this value with each pixel in the image. If not changed from the default value, no blending will take place.
filledBarImageUriuri""A 9-patch or ordinary PNG of the bar that represents the completed portion of the work represented by this ProgressBar node. This is typically displayed on the left side of the track. This will be blended with the color specified by the filledBarBlendColor field, if set to a non-default value.
trackBlendColorcolor0xFFFFFFFFThis color is blended with the graphical image specified by trackImageUri field. The blending is performed by multiplying this value with each pixel in the image. If not changed from the default value, no blending will take place.
trackImageUriuri""A 9-patch or ordinary PNG of the track of the progress bar, which surrounds the filled and empty bars. This will be blended with the color specified by the trackBlendColor field, if set to a non-default value.
percentageintegertopThe percentage of the work that is done. Setting this field controls the visual appearance of the ProgressBar node.
bufferingTextColorcolorsystem defaultThe color of the text displayed near the buffering bar defined by the bufferingBar field, when the buffering bar is visible. If this is 0, the system default color is used. To set a custom color, set this field to a value other than 0x0.  
retrievingBarProgressBar nodeinternal instance default Component that shows the progress of initial retrieving of the video, prior to starting playback. The fields of this internal node are the same as for the bufferingBar field, which are the fields of the internal ProgressBar node.
retrievingTextColorcolorsystem default  The color of the text displayed near the retrieving bar, when the retrieving bar defined in the retrievingBar field is visible. If this is 0, the system default color is used. To set a custom color, set this field to a value other than 0x0.  

...