Video

Extends Group

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 Roku OS 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.

Fields

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

-  0    no error                                                     
- -1    network error (server down or unresponsive, server is unreachable, network setup problem on the client).
- -2    connection timed out                                         
- -3    unknown/unspecified or generic Error                         
- -4    empty list; no streams were specified to play                
- -5    media error; the media format is unknown or unsupported      
- -6    DRM error

<br />video.subtitleSelectionPreferences = \{ values: [<br />    \{ language: ["es-419", "es", "es-*", "fr", "en-US", "en-UK", "en"] \},<br />    \{ caption: "true" \},<br />    \{ descriptive: ["false"] \},<br />    \{ easyReader: "true" \} ],<br />    overrideSystem: true \}<br />

<br />video.audioSelectionPreferences = \{ values: [<br />    \{ language: ["en-US", "en-UK", "en", "en-*"] \},<br />    \{ descriptive: "false" \} ],<br />    overrideSystem: true \}<br />

Trickplay fields

UI fields

Closed caption fields

Audio fields

Automatic audio track selection

If multiple audio tracks are available for video content, the Roku OS automatically selects the best track based on the preferred audio track settings on the device (language, country code, and descriptive setting) and the quality of the audio track (bitrate/format).

The user can manually set their preferred language in the Settings > Audio > Audio preferred language menu, and the country code and descriptive setting are automatically set when the user selects an audio track. The preferred language setting is also automatically updated when the user selects an audio track (the preferred language is set to the language of the selected track).

For example, if the user chooses Portuguese as their preferred language, the Roku OS will by default select the Portuguese audio track the next time they watch content (if available). If the selected audio track is in Portuguese (Brazil), the user's preferred country is set to Brazil, and the Portuguese (Brazil) audio track is selected by default the next time the user watches content.

It is recommended that apps use the audio track selection logic provided by the Roku OS instead of implementing their own.

Overall, the Roku OS uses the following criteria (listed in order of priority) to determine which audio track to play:

1. Preferred audio track settings:

   a. The track explicitly selected by the user.

   b. The track with the user's preferred language, country code and descriptive setting.

   c. The track with the preferred language and the country code.

   d. The track with the preferred language that is marked as the default audio track.

   e. The track with the preferred language.

   f. The first track.

2. Highest quality audio track (based on bitrate/format)

Any language not included in the provided list of common languages is added to the list as the last entry. The common languages list may only have a single unlisted language. For example, if the user selects Korean as the audio track for a movie, the last entry in the common languages list is Korean, which is used as the preferred language from thereon. If the user then selects a Chinese audio track, Chinese overwrites Korean as the last entry in the common language list and is used as the preferred language.

CDN fields

Developers can receive event-based notifications when the CDN is switched during content playback.

Miscellaneous fields

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

Prior to Roku OS 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. Apps 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>