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.
| Field | Type | Default | Use | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| content | ContentNode | Invalid | 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 | |||||||||||||||||||||||||||
| contentIsPlaylist | Boolean | false | If set to true, enables video playlists (a sequence of videos to be played). See the | |||||||||||||||||||||||||||
| contentIndex | integer | -1 | Read-Only | |||||||||||||||||||||||||||
| nextContentIndex | integer | -1 | If the | |||||||||||||||||||||||||||
| control | option 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 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.
| |||||||||||||||||||||||||||
| state | value string | "none" | Read-Only
| |||||||||||||||||||||||||||
| errorCode | integer | 0 | Read-Only | |||||||||||||||||||||||||||
| errorMsg | string | "" | Read-Only | |||||||||||||||||||||||||||
| errorStr | string | "" | Read-Only 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}
|
Trickplay Fields
| Field | Type | Default | Use | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| duration | Double | 0 | Read-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. | ||||||||||||||||||||||||||||||
| loop | Boolean | false | If 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 | Double | 0 | Read-Only Time of the current position in the stream. Either UTC time or elapsed since start of stream depending on content type | ||||||||||||||||||||||||||||||
| notificationInterval | time | 0.5 | The 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 | time | invalid | Write-Only | ||||||||||||||||||||||||||||||
| timedMetaData | associative 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. | ||||||||||||||||||||||||||||||
| timedMetaDataSelectionKeys | array 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. | ||||||||||||||||||||||||||||||
| streamInfo | associative array | invalid | Read-Only
Available since firmware version 7.2 | ||||||||||||||||||||||||||||||
| completedStreamInfo | associative array | invalid | Read-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 | ||||||||||||||||||||||||||||||
| timeToStartStreaming | Double | 0 | Read-Only | ||||||||||||||||||||||||||||||
| bufferingStatus | associative array | invalid | Read-Only
| ||||||||||||||||||||||||||||||
| videoFormat | string | "" | Read-Only
| ||||||||||||||||||||||||||||||
| pauseBufferStart | Double | 0 | Read-Only The beginning position of the video buffered when paused. This field is only valid for live video. | ||||||||||||||||||||||||||||||
| pauseBufferEnd | Double | 0 | Read-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
| ||||||||||||||||||||||||||||||
| downloadedSegment | associative array | invalid | 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:
| ||||||||||||||||||||||||||||||
| manifestData | associative 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:
The property 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: Some examples of how to access the manifestData would include:
|
UI Fields
| Field | Type | Default | Use | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| width | float | 0.0 | Sets 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. | ||||||||||||||||||||||||||||||||||||||||
| height | float | 0.0 | Sets 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. | ||||||||||||||||||||||||||||||||||||||||
| enableUI | Boolean | true | 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. | ||||||||||||||||||||||||||||||||||||||||
| enableTrickPlay | Boolean | true | 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. | ||||||||||||||||||||||||||||||||||||||||
| bifDisplay | BifDisplay node | internal instance default | Component that displays BIFs and allows navigation. The fields of this internal node are as follows:
| ||||||||||||||||||||||||||||||||||||||||
| trickPlayBar | TrickPlayBar node | internal instance default | The visible TrickPlayBar node. The fields of this internal node are as follows:
| ||||||||||||||||||||||||||||||||||||||||
| bufferingBar | ProgressBar node | internal instance default | Component that shows the progress of re-buffering, after video playback has started. The fields of this internal node are as follows:
| ||||||||||||||||||||||||||||||||||||||||
| bufferingTextColor | color | system default | The 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. | ||||||||||||||||||||||||||||||||||||||||
| retrievingBar | ProgressBar node | internal 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. | ||||||||||||||||||||||||||||||||||||||||
| retrievingTextColor | color | system 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
| Field | Type | Default | Use | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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:
Orthogonal functionality - The channel should set the subtitleTrack regardless of the selected Caption Mode. | ||||||||||||||||||||
suppressCaptions | boolean | false | 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 | ||||||||||||||||||||
| availableSubtitleTracks | array of associative arrays | [ ] | Read-Only
| ||||||||||||||||||||
| 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:
Available since firmware version 8. |
Audio Fields
| Field | Type | Default | Use | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| mute | Boolean | false | Set to true to mute the audio of the video currently playing in the Video node. Set to false to restore audio. | ||||||||||||||||||||||||||||||||||||||
| audioTrack | string | "" | 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. | ||||||||||||||||||||||||||||||||||||||
| availableAudioTracks | array of associative arrays | [ ] empty array | Read-Only
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. | ||||||||||||||||||||||||||||||||||||||
| audioFormat | string | "" | Read-Only
| ||||||||||||||||||||||||||||||||||||||
| supplementaryAudioVolume | int | 50 | 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
| Field | Type | Default | Use | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| MaxVideoDecodeResolution | vector2d | [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. | ||||||||||
| cgms | integer | 0 | Sets the CGMS (Copy Guard Management System) on analog outputs to the desired level. The valid values are:
| ||||||||||
| enableScreenSaverWhilePlaying | Boolean | false | Set 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. | ||||||||||
| disableScreenSaver | Boolean | false | Set this to true to suppress the screensaver. This is typically used to suppress the screensaver when playing audio-only streams. | ||||||||||
| contentBlocked | Boolean | false | 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:
HttpCertificatesFileHttpCookiesHttpHeadersHttpSendClientCertificates
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:
<Video id="musicvideos" width="1280" height="720" translation="[0,0]" />
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.
<script type="text/brightscript" >
<![CDATA[
sub init()
m.top.setFocus(true)
setVideo()
end sub
function setVideo() as void
videoContent = createObject("RoSGNode", "ContentNode")
videoContent.url = "https://roku.s.cpl.delvenetworks.com/media/59021fabe3b645968e382ac726cd6c7b/60b4a471ffb74809beb2f7d5a15b3193/roku_ep_111_segment_1_final-cc_mix_033015-a7ec8a288c4bcec001c118181c668de321108861.m3u8"
videoContent.title = "Test Video"
videoContent.streamformat = "hls"
m.video = m.top.findNode("musicvideos")
m.video.content = videoContent
m.video.control = "play"
end function
]]>
</script>