Versions Compared

Key

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

...

Playing any type of video requires just one SceneGraph node class: Video.

To play a video, you must first prepare the files to be served to the Roku Player:

  • the video files must have been encoded in one of the formats supported by a Roku Player (see see Supported Streaming Formats)
  • if you want to use an adaptive bitrate switching scheme, the video files must be configured to use the supported adaptive bitrate scheme you want (see see Adaptive Bitrate Formats)
  • you must also include any supporting files for special playback options you want, such as as trick play (see see Trick Mode Support)

Then, in your application, you must:

  • set the various playback configuration options for your video in a ContentNode node using  node using Content Meta-Data (see see Content Meta-Data) attributes
  • assign the the ContentNode node  node to the the content field  field of the the Video node node
  • set other other Video node  node fields for all other video playback appearance and function configuration you want for your particular video (or videos)

Then, when a user selects a video to play, you set the the Video node  node control field to  field to play, in a callback function triggered by the user selection event.

...

Here are two example applications showing selecting and playing videos. These examples demonstrate the use of the the RowList node  node class to create a custom content grid and and Video node  node for video playback. The second example also shows how to create a very simple details screen for displaying more information about selected content before video playback. They also show how to load and parse an MRSS feed so you can see how to populate your channels with dynamic content.

...

And here is a simple example using the same basic content with a LabelList node  node for selecting the video to play. The XML file containing the the Content Meta-Data is  is included and read from the the pkg:/server/videocontent.xml file file. Since the entire application including the the Content Meta-Data is  is contained within the application package, you can see how the the Content Meta-Data is  is parsed and translated into a ContentNode node node, which supplies the items displayed in the the LabelList node node, and then how the video is played when the user selects a video from the list.

...

Setting Focus on the Video Node

You must set focus on the the Video node  node while playback is occurring for the trick play bar and some other user interface options to be used. After playback has finished, you will generally want to set focus back on the user interface element (usually a list or grid or custom video "details" screen) from which the user selected the video.

...

For your server content meta-data XML files, always ensure that all attribute strings containing the ampersand (&) character is properly escaped by replacing it with the HTML entity entity &. (This is particularly important because many video stream URLs include this character.) Also remember to properly escape all XML special characters in the attribute strings, and use the correct HTML entities to format your descriptive content meta-data attributes.

...

Available since firmware version 7.2

Both the the Audio and  and Video nodes  nodes support the use of playlists, which are lists of several media items to play in sequence rather than a single media item. If a playlist is used, setting the the loop field  field to true causes the entire playlist to play again after the last item in the playlist completes.

To set an an Audio or  or Video node  node to play several media items in sequence:

  1. Set the the content field  field to a ContentNode node  node containing a child child ContentNode node  node for each media item in the playlist.
  2. Set the the contentIsPlaylist field  field to true.

After setting the the control field to  field to play, you can control the playback as follows:

  • to stop playing the current media item in the playlist, or end playback if the current item is the last in the playlist, set the set the skipcontent option  option of the the control field field
  • set the the nextContentIndex field  field to an index of another item in the playlist to be played after the current item finishes, rather than the next item in the sequence
  • for for Audio nodes nodes, you can observe and use the the contentIndex field  field value to control the appearance of the screen while the audio item is playing, such as showing the title of a song when that song begins playing

Configuring Video Stream Buffering

All digital  digital video players must buffer a certain amount of the video data stream before video playback can occur. These buffering operations appear to the user as a delay between the time the user selects the video to play, and the time when the video begins to play. The The Video node  node class includes special internal node instances to indicate to the user that the video data stream is buffering, whether before initial playback, or after buffering must occur again because the video playback is interrupted by an unexpected slowdown in the video stream transfer rate. (Video playback interruptions are more likely to occur if you do not take advantage of some type of adaptive bitrate configuration of the video playback, such as using a segmented adaptive video playback scheme such as HLS, as described in in Adaptive Bitrate Formats.)

To indicate to the user that the video stream is buffering, the the Video node  node class includes two instances of an internal internal ProgressBar node node, which, if set to be visible, appear at the bottom center of the video playback screen area automatically when video buffering is occurring.

...

These progress bars are configured in BrightScript by setting the fields of the internal internal ProgressBar nodes  nodes as follows:

  • retrievingBar for  for the progress bar that appears when the video stream is being buffered prior to initial playback
  • bufferingBar for  for the progress bar that appears when the video stream must be buffered again after an unexpected stream transfer rate slowdown

These internal internal ProgressBar nodes  nodes have fields for configuring their appearance, such as setting the color of the portion of the bar that indicates the amount of buffering that has been accomplished. These fields must be set in BrightScript. Other Other Video node  node fields are available for configuring other aspects of the internal internal ProgressBar nodes nodes, such as setting the color of the text of the progress bar. These fields can be set in either BrightScript or XML markup.

To set the internal node fields in BrightScript, the the Video node  node object must be available within the scope of the BrightScript function that will set the fields. For example, if a Video node  node was declared and partially defined in XML markup, you must use the the findNode() function  function to declare the node object and access the internal retrieving bar node fields:

m.video = m.top.findNode("channel_video_node_id") 
...
 
m.video.retrievingBar.internal_node_field = internal_node_field_value 
...

Note
Since you should always set the control field of a Video node in BrightScript, you should always declare a Video node object in BrightScript anyway, either by creating the object in BrightScript, or using the findNode() function.

...

Available since firmware version 7.2

Both the the Audio and  and Video node  node classes also include a special control option to reduce or eliminate the apparent delay before media playback begins (fast start). All digital video requires some time after a video is selected to begin playback, and video (and audio) files streamed over HTTP add network transfer rates to this buffering time. You can configure your application to reduce or eliminate this apparent delay to the user by setting the the Video (or or Audio) node node control field to  field to prebuffer, at a time when the user has moved focus to a description of the media item, but before the user actually starts the playback. The media stream will buffer in the background while the user is reading the description of the media item. Then, if and when the user actually selects the media item to play, you can set the the control field to  field to play as  as usual.

For example, if you have designed your SceneGraph application to have a screen that shows a description of a video, with a button to actually begin playback, you can use the the prebuffer option  option of the the control field  field in a callback function triggered by the screen focus event as follows: 

...

For MPEG-4 (mp4) video files without segmented adaptive bitrate switching files, set the the ContentNode node  node streamformat meta meta-data attribute to to mp4, and the the url attribute  attribute to the URL of the MPEG-4 video file.

...

For the most basic segmented video playback, you only need to set the URL and  and StreamFormat field values in a ContentNode node node, assign the the ContentNode node  node to the the content field  field of the the Video node node, then set the the Video node  node control field  field value to to play to  to start the video. For example:

videoContent = createObject("RoSGNode", "ContentNode") 
videoContent.url = "video_URI" 
videoContent.streamformat = "hls" 
m.video = m.top.findNode("video_node_ID") 
m.video.content = videoContent videoContent 
m.video.control = "play"

Segmented Video Playback with PlayReady DRM

If you include PlayReady DRM in your DASH video stream, set the following Content Meta-Data attributes  attributes in your your ContentNode node node:

  • encodingtype
  • encodingkey
  • streamformat
  • url

...

For more advanced video playback (for example, incorporating "trick play" DVD-like scene indexing functionality), there are fields in the the Video node  node and the associated associated ContentNode node  node to provide this functionality.

...

To support trick play for a video, you must generate and provide a set of BIF files for the video. See Trick Mode Support for  for information on BIF file generation and usage.

After you have created the BIF files for a video, you must place the files on a server, and then configure the the Video node  node to access the files by setting the associated associated ContentNode node  node using the trick play attributes described in in Content Meta-Data (see Content Meta-Data).

Configuring Trick Play Appearance

The The Video node  node class includes an internal internal TrickPlayBar node  node to provide the user interface for trick play. You can customize the appearance of this internal node by accessing its fields in BrightScript in the same manner as the internal internal ProgressBar nodes  nodes (see see Configuring the ProgressBar Nodes).

...

Adding closed caption support is a simple matter of configuring the subtitleconfig video node content element. See See SceneGraphCaptionsDemo.zip for an example of using side loaded TTML captions in your channel.

...

Generally you will want to have all of your content meta-data configuration of a particular video in an XML/JSON file on your server. You can then read this file, convert it to a ContentNode node node, and set up the related user interface and video configuration for your video in your Roku application.

This XML/JSON file should contain the strings or links to all the information you need to present the video to the user for selection, and to configure the video playback. In almost all cases, you should be able to use the attributes listed in in Content Meta-Data (see Content Meta-Data), which are all recognized as field names for a ContentNode node node. In the rare cases where you require a custom attribute not found in in Content Meta-Data, you can create a custom custom ContentNode node  node by adding adding <interface> fields fields, or possibly by setting up a parallel associative array that can be accessed using the same user interface element node indexing that you use for accessing accessing ContentNode nodes nodes.

Descriptive Content Meta-Data

...

Note
If you participate in the Roku Search program, you can use the information in the XML feed you supply to Roku for many of the meta-data attributes listed above. See Roku Search for complete details.

Video Configuration Meta-Data

See See Content Meta-Data for  for the complete list of video configuration meta-data. 

Example Video Meta-Data XML Task Node File Reader

The following is an example of a Task node  node that reads an XML file from a server containing descriptive and configuration meta-data for videos. The The Task node  node converts the XML file attributes for each video, and builds the corresponding corresponding ContentNode node  node with the attribute data. The The Task node  node should be created, have an observer callback set for the the videocontent <interface> field field, configured with the URL of the server XML file as the the metadatauri <interface> field field, then run. When the the ContentNode node  node is complete, it is assigned to the the videocontent <interface> field  field of the the Task node node, which then triggers the callback function to configure lists or grids for each video item, and allow the configuration meta-data to be assigned to a Video node  node that plays the video. 

Code Block
languagexml
titleExample Video Content Meta-Data Task Node
<component name = "MetaDataCR" extends = "Task" >

  <interface>
    <field id = "metadatauri" type = "uri" value = "" />
    <field id = "videocontent" type = "node" />
  </interface>

  <script type = "text/brightscript" >

    <![CDATA[

    sub init()
      m.top.functionName = "getContent"
    end sub

    sub getContent()
      videocontent = createObject("RoSGNode","ContentNode")
      metadataxml = createObject("roXMLElement")

      ' uncomment/conditionalize for development package XML transfers (pkg:/server/foo.xml)
      xmlstring = ReadAsciiFile(m.top.metadatauri)
      metadataxml.parse(xmlstring)

      ' uncomment/conditionalize for published channel Internet XML transfers (http://serverdomain/foo.xml)
      ' readInternet = createObject("roUrlTransfer")
      ' readInternet.setUrl(m.top.metadatauri)
      ' metadataxml.parse(readInternet.GetToString())

      if metadataxml.getName()="MetaData"
        for each video in metadataxml.GetNamedElements("video")
          videoitem = videocontent.createChild("ContentNode") 
          videoItem.setFields(video.getAttributes())
        end for
      end if
      m.top.videocontent = videocontent
    end sub

    ]]>

  </script>

</component>

Broadcast Video

The following example illustrates how to play broadcast or cable content on a Roku TV that includes a tuner in a SceneGraph application.  SimpleTuner.zip contains a complete side-loadable example.

Code Block
languagexml
titlePlaying Broadcast and Cable Content from a Tuner
<?xml version="1.0" encoding="utf-8" ?>

<!--********** Copyright 2016 Roku Corp.  All Rights Reserved. **********-->

<component name="SimpleTunerScene" extends="Scene" >

  <script type="text/brightscript">
    <![CDATA[

    function init()
      m.video = m.top.findNode("myVideo")
      playVideo()
    end function

    function playVideo() as void
      tuner = CreateObject("roTuner")
      if (tuner <> invalid)
        channels = tuner.GetChannelList()
        channelInfo = tuner.GetChannelInfo(channels[0])
        if channelInfo <> invalid
          cm = channelInfo.content_metadata
          stream = {}
          stream.AddReplace("url", "file://")
          stream.AddReplace("channelnumber", cm.ChannelNumber)
          vidContent = createObject("RoSGNode", "ContentNode")
          vidContent.url = "file://"
          vidContent.streams = stream
          vidContent.title = cm.Title
          vidContent.streamformat = cm.StreamFormat
          m.video.content = vidContent
          m.video.control = "play"
        end if
      endif
    end function

    ]]>
  </script>

  <children>

    <Video id="myVideo" width="1280" height="720" />

  </children>

</component>

Sample Channels

The table below summarizes all of the downloadable samples demonstrating the video playback features introduced in this section.

Sample ChannelDescription
Simple_Grid_and_Video.zipVideo player in a simple grid UI.
Simple_Grid_with_Details_and_Video.zipVideo player in a simple grid UI with details page.
PanelSet_and_Video.zipVideo player in a simple PanelSet UI.
VideoList.zipVideo player with content selected from a LabelList.
FastVideoStart.zipSample demonstrating how to use Fast Video Start.
SceneGraphCaptionsDemo.zipSample demonstrating how to integrate closed caption support.
SimpleTuner.zipSample demonstrating live TV tuner integration.