Skip to end of metadata
Go to start of metadata

Table of Contents


Extends: Group

Description

The Video node class provides a controlled play of live or VOD video.

The Video node includes a wide variety of internal nodes to support trick play, playback buffering indicators, and so forth. Playback buffering indicators, to indicate buffering before initial playback as well as re-buffering, use an internal instance of a ProgressBar node. For trick play, an internal instance of a TrickPlayBar node is provided. For display of BIF images for DVD-like chapter selection, an internal instance of a BIFDisplay node is provided.

Starting from firmware 8, the behavior of the Roku system overlay is such that the system overlay now slides in whenever the * button is pressed, the Video node is in focus, and the app does not have its OnKeyEvent() handler fired. When the Video node is not in focus, the system overlay does not slide in and the OnKeyEvent() handler is fired.

Field Types

Playback Fields

To set the specific video playback parameters for a particular video, set the Content Meta-Data attributes for the video in a ContentNode node, and assign the ContentNode node to the content field of the Video node.

Video playback can then be controlled by setting the value of the control field, such as setting the field value to play to begin playback.

The control field includes a prebuffer option, which allows the video to begin buffering without showing the video. You can use this option to begin buffering of a video before a user has actually selected and started the video, such as when the user is looking at information about various video offerings in a list or grid or another type of UI element. This can eliminate much or all of the apparent delay in starting the video due to buffering the video for the user. For example, you could set the control field value to prebuffer in a callback function triggered by the itemFocused events that occur as a user scrolls down a list of video offerings that also display information about each video. When the user makes the selection, you can begin the actual video playback by setting the control field value to play in a callback function triggered by the itemSelected event for the list.

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.

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.

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 and error message can be found in the errorCode and errorMsg 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.


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

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.

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.

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.

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:

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:
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

 

UI Fields

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:

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 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 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:

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:

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.  


Closed Caption Fields

FieldTypeDefaultUse

globalCaptionMode

option string"Off"

Sets the value of the global Roku closed-caption mode. This can be used to allow the user or the application to change the closed-caption mode in an application just before or during video playback. The possible options are:

OptionEffect
"Off"Turns the global Roku closed-caption mode off.
"On"Turns the global Roku closed-caption mode on.
"Instant replay"Sets the global Roku closed-caption setting to display captions only during instant replay.
"When mute"Sets the global Roku closed-caption setting to display captions only when the volume is muted. (This only applies to Roku TVs.)

Orthogonal functionality - The channel should set the subtitleTrack regardless of the selected Caption Mode.

suppressCaptions

booleanfalse

Suppresses the closed caption for the purpose of resolving conflicts in cases where UI elements are drawn.

Note that most of the disabling/enabling of the captions are done by the firmware, including enabling closed caption for Instant Replay.

subtitleTrack

string""

The identifier of the selected subtitle track. Subtitles may or may not be visible on the screen, depending upon the user's caption mode setting. Reading this field will return the identifier of the current subtitle track, and setting the field will change the track.

Subtitle track should always be set regardless of the mode.

See also: globalCaptionMode

availableSubtitleTracksarray of associative arrays

[ ]
empty array 

Read-Only
The list of subtitle tracks available in the video stream. The array is initially populated with the tracks specified in the Content Meta-Data, and additional tracks are added if they are detected by the digital video player. Each associative array has the following entries:

KeyTypeValue
DescriptionstringDescriptive name of the subtitle track
LanguagestringISO 639-2 three-letter language code
TrackNamestringThe track identifier. The value of this field may be used to select the subtitle track.
captionStyle
Associative
array
System
default
Allows channels to style closed captions. For any keys that are absent from the associative array, or for unexpected values, the Default value is assumed for that property. Following are the possible key names and values for this field:

 

Property
Possible Values
Text style

Default
Serif Fixed Width
Serif Proportional
Sans Serif Fixed Width
Sans Serif Proportional
Casual
Cursive
Small Caps

Text edge effect

Default
None
Raised
Depressed
Uniform
Drop shadow (left)
Drop shadow (right)

Text size

Default
Large
Medium
Small

Text color

Default
White
Black
Red
Green
Blue
Yellow
Magenta
Cyan

Text opacity

Default
25%
75%
100%

Background Color

Default
White
Black
Red
Green
Blue
Yellow
Magenta
Cyan

Background Opacity

Default
Off
25%
75%
100%

Window Color

Default
White
Black
Red
Green
Blue
Yellow
Magenta
Cyan

Window Opacity

Default
Off
25%
75%
100%

 

Available since firmware version 8.


Audio Fields

FieldTypeDefaultUse
muteBooleanfalse

Set to true to mute the audio of the video currently playing in the Video node. Set to false to restore audio.

audioTrackstring""The track identifier of the audio being played. Reading this field will return the track identifier of the audio being played, and writing this value will change the audio track.
availableAudioTracksarray of associative arrays[ ]
empty array

Read-Only
Each associative array has the following entries:

KeyTypeValue
LanguagestringISO 639-2 three-letter language code
NamestringDescriptive name of the audio track
TrackstringThe track identifier. The value of this field may be used to select the audio track.

 

The field also retrieves audio description tracks which are typically seen on broadcast TV. An audio description track is mixed with the main audio track.

audioFormatstring"" 

Read-Only 
Contains the format of the currently playing audio.

ValueMeaning

""

No stream playing

none 

Stream contains no playable audio

unknown 

Stream contains unknown audio

aac 

ISO/IEC 14496-3, Advanced Audio Coding

aac_adif 

ISO/IEC 14496-3, Advanced Audio Coding, ADIF container

aac_adts 

ISO/IEC 14496-3, Advanced Audio Coding, ADTS container

aac_latm 

ISO/IEC 14496-3, Advanced Audio Coding, LATM container

ac3 

Dolby Digital

alac

Apple Lossless

dts 

DTS Coherent Acoustics

eac3 

Dolby Digital Plus

flac 

Free Lossless Audio Codec

mp2 

ISO/IEC 11172-3, MPEG Audio Layer II

mp3 

ISO/IEC 11172-3, MPEG Audio Layer III

pcm 

linear PCM

vorbis 

Ogg Vorbis

wma 

Microsoft Windows Media Audio

wmapro 

Microsoft Windows Media Pro Audio
supplementaryAudioVolumeint50
This field sets the volume of the description tracks separately from the main audio track. The field value can range from 0 to 100.

Available since firmware version 8.


Miscellaneous Fields

FieldTypeDefaultUse
MaxVideoDecodeResolution

vector2d
(width, height)

[0,0]

Sets the max resolution required by your video.

Video decode memory is a shared resource with OpenGL texture memory. The Brightscript 2D APIs are implemented using OpenGL texture memory on Roku models that support the Open GL APIs (please see Roku Models and Features for a list of these models).

On models that do not support Open GL APIs, this field exists for API compatibility but has no effect on actual memory allocations.

Video decode memory allocation is based on a resolution of 1920x1080 or 1280x720 as the maximum supported resolution for a particular Roku model (please see Roku Models and Features for a list of these models).

This field enables applications that want to use both the 2D APIs and video playback with a lower resolution than 1080p. Without this field, these applications are likely to not have enough memory for either video playback or UI rendering.

If width is 0 (the default), it is unlimited. If height is 0 (the default), it is unlimited.
Available since firmware version 7.2

cgmsinteger0

Sets the CGMS (Copy Guard Management System) on analog outputs to the desired level. The valid values are:

ValueEffect
0No copy restriction
1Copy no more
2Copy once allowed
3No copying permitted
enableScreenSaverWhilePlayingBooleanfalseSet this to true to allow the screensaver to activate even if video is playing, as long as that video does not cover 50% or more of the screen. Set to false to block the screensaver activating if any video is playing. Note that this field
has no effect when the video node plays audio only streams. For screensaver control with audio only streams, use the disableScreenSaver field. 
disableScreenSaverBooleanfalseSet this to true to suppress the screensaver. This is typically used to suppress the screensaver when playing audio-only streams.
contentBlockedBooleanfalse
Read-Only
Determines whether the current content is blocked.

Available since firmware version 8.

Data Bindings

See Content Meta-Data for the required and optional play parameters, and descriptive information for video playback. Set these parameters in a ContentNode node, and assign the ContentNode node to the content field of the Video node to apply the parameters to a particular video content item.

For HTTPS access, note the following Content Meta-Data attributes:

  • HttpCertificatesFile
  • HttpCookies
  • HttpHeaders
  • HttpSendClientCertificates

These attributes must be set to handle secure HTTP transfers of video files. Note that this is a different HTTPS mechanism than used for other SceneGraph nodes as described in roHttpAgent.

In firmware versions prior to 7.2, each Audio and Video node created and configured an HttpAgent only when the first content was played in a given Audio or Video node instance. This sometimes meant that additional content would fail to play in the same node because headers, cookies, and certificates were not updated or correctly replaced from the new content record. Channels that are dependent upon this behavior will need to be updated to set the required data into the Content Meta-Data for each piece of content, or to programmatically set those values into the HttpAgent before playing each piece of content.

Example

To play video in an application, you first need to create a Video node, either in BrightScript using the roSGNode ifSGNodeChildren interface, or in XML markup. For example, in XML markup:

The Video node is then scripted to specify the URL of the video stream, streaming format, video title, and any other Content Meta-Data attributes needed for the particular playback. Once the video properties are specified, the video can be played by setting the Video node control field value to play.

  • No labels