Created by Jeff Bush, last modified by Linda Kyrnitszke on Nov 03, 2018

This component is deprecated.

Beginning July 1st, 2017, any new channels using this component will be rejected during certification.

Beginning January 1st, 2018, any updates to existing channels using this component will be rejected during certification.

The Video Screen object implements the video playback portion of the user interface.

Supported Interfaces

Supported Events

Description

The API's to the video screen allow the developer to setup a fully featured playback environment with minimal coding. The developer is responsible for initial playback setup and providing the required data (e.g. StreamURLs, SteamsBitrates, etc.) as part of the Content Meta-Data. Once created and displayed, the screen will respond to events and manage the playback experience for the user.

The roVideoScreen is designed for streaming content. The preferred implementation should provide multiple bitrates (ideally four) of video to provide a high quality user experience under a variety of network conditions. Using the StreamBitrates and StreamURLs provided in the content meta-data for the item, the roVideoScreen will automatically monitor and select the best stream based on the users measured bandwidth. If network performance changes, the system will adapt and rebuffer to stream at a different bandwidth if necessary. Note that the StreamURLs, StreamBitrates, StreamQualities and StreamStickyHttpRedirects are all arrays that are aligned with each other. For example, the first stream listed would be the 0th element of all of these arrays.

The bitrates should represent the actual bitrate of the stream. The bitrate is used for both the display of the dots as well as the stream selection algorithm.
The dots work a follows: If the stream bitrate equals:

  •      0 = no dots
  • < 500 Kbps= 1 dot
  • < 800 Kbps = 2 dots
  • <1.1 Mbps = 3 dots
  • >= 1.1 Mbps = 4 dots

The dots are displayed automatically based on the bitrate of the stream selected unless there is a single stream and the bitrate is set to zero, then it won't show any dots. The StreamQuality attribute is used to select streams and indicates if a stream is HD or not. If the attribute for HDBranded is set to true and the stream is HD, the HD icon will show beside the quality dots. If the StreamQuality is set to HD, and the user display type is set to SD, the HD stream will not be selected.

The roVideoScreen automatically provides trick mode for all supported content types. There are two type of trick modes supported; scene based selection and time-based selection. If BIF image files are provided for a title, scene-based trick modes will appear. (See the BIF File format Documentation for more information) The user will be presented with the images and progress bar needed for SEEK, FF, REW within a stream. The following image shows how trick modes are rendered with BIF files:

The FF/REW functionality provides three speeds; slow, medium and fast. At slower speeds, the system displays the current frame in the center of the screen and additional frames on the side for contextual information. At higher speeds, the side frames disappear and only the center image is displayed. The I-frames within the video do not need to precisely align with the time stamp of the image frames in the BIF file. When the user stops and selects a frame, the video playback begins at the first I-frame less than or equal to the time position of the selected frame.

When BIF images are not available, the system will default to a time based trick play behavior. The user control is still the same, but only the progress bar is displayed and the user will not see individual scenes within the video. This mode is the default, so if images are not available for an individual title, the system will always provide this functionality by default.

The system will only seek to locations on an I-Frame boundary. Window Media (WMA9 or VC-1) uses the simple index object to determine the I-frame locations and H.264 uses the MOOV atom to determine the correct offsets. If the BIF images are at a consistent time intervals which do not align to I-Frame boundaries, the system will use the nearest I-Frame less than or equal to the time of the BIF image. MP4 or Windows Media are the preferred formats.

Important Notes on Video Playback

  1. The dimensions vary on a title-by-title basis depending on the source material and the target aspect ratio for the encode (e.g. 4:3 or 16:9).  Content is always encoded at full width and the height is adjusted.  For example, a 1.66 aspect ratio source is encoded as a 720x432 video and displayed as letterboxed for a 4:3 display.
  2. The frame rate used for encoding is dependent on the source material. Film content is generally 23.976 fps, while video content is generally at 29.97.
  3. For typical streaming video applications, we recommend a range of ~384Kbps to ~4.5Mbps. For USB playback, we recommend that you stay under 8.0 Mbps. This provides a good balance between quality and support for a wide number of users. In some cases lower and higher bitrates have been used, but this frequently results in poor quality or limits the % of the installed base that can view this encoding
  4. It is critical that the StreamURLs, StreamBitrates, StreamQualities and StreamStickyHttpRedirects arrays are all aligned with each other. For example, the first stream listed would be the 0th element of all of these arrays. You may have multiple streams in the arrays and the system will automatically pick the most appropriate stream based on the users available bandwidth and video settings.
  5. The StreamQualities array identifies streams as either SD or HD. If the user is configured for SD the system will not select HD streams for playback.
  6. The optional StreamStartTimeOffset is the offset into the stream which is considered to be the new origin of playback.
  7. Live – declares the video as live and replaces the time remaining text in the progress bar with "live".
  8. HLS Http Live Streaming support is included in the firmware (Introduced in firmware v2.6). We currently support version 3 of the Http Live Streaming protocol (Pantos – Draft submitted to IETF November 19, 2010 http://tools.ietf.org/html/draft-pantos-http-live-streaming-05 ). When using HLS, the StreamUrls and StreamQualities array should each have exactly one element.  If the HLS stream has only a single bitrate stream, the StreamBitrates array should contain one element specifying that bitrate.  If the stream contains more than one variant stream at multiple bitrates, the StreamBitrates array should contain one element with a value of zero. Please see the Video Encoding Guide for information about creating HLS .m3u8 files and segmented .ts files from your current h264 encoded video or distributing live video over HLS to the Roku box.
  9. In addition to the support for version 2 of the HLS Pantos draft spec, the Roku box supports .m3u8 files that are compressed via deflate or gzip. 
              The HTTP response for a query that returns a gzip-compressed file must contain the header:          Content-Encoding: gzip
              The HTTP response for a query that returns a deflate-compressed file must contain the header:       Content-Encoding: deflate
  10. "Trick Modes" and seeking work a little differently with HLS streams. There are a couple of ways that seeking works with HLS and they are different than other streams.
             One way of seeking uses the "target duration" specified in the .m3u8 file. The first segment in an m3u8 file is assigned a time offset:
             T = G * N
             where G is the "target duration" value and N is the sequence number of the segment. Each subsequent segment is assigned a time offset equal to T (the time    
    offset of the first segment) plus the duration value of all earlier segments. The duration of a segment is determined by the EXTINF line before that segment. 
  11. Smooth Streaming (since v4.7) and later by setting the StreamFormat to "ism" and setting the streamURL to the MANIFEST url.
    • The player type (ContentMetaData.StreamFormat) is "ism"
    • The stream URL is the URL that points to the manifest
    • Only H.264 and/or AAC encoding formats are currently supported.
    • Only direct PlayReady licensing is supported. Indirect licensing is currently unsupported. That is, for decryption to work, the ProtectionHeader must be available in the manifest and the LA_URL should contain a valid URL to an accessible PlayReady license server.
    • If there are multiple audio tracks, a track will be chosen based on the StreamIndex.Language attribute in the manifest. If the StreamIndex.Language attribute is not populated, the audio track will be chosen arbitrarily. To select a specific audio track before playback, set the ContentMetaData.TrackIDAudio field to the desired track's StreamIndex.Name attribute.
    • If there are multiple video tracks, a track will be chosen arbitrarily. To select a specific video track before playback, set the ContentMetaData.TrackIDVideo field to the desired track's StreamIndex.Name attribute.
  12. Standard PlayReady SDK 2.0 Direct License Acquisition Over-the-Air (since v4.8) works by reading the Rights Management Protection Header in the Smooth Streaming Manifest Url.  The Roku firmware retrieves the license from the PlayReady license server at the license acquisition url endpoint in the Protection Header.
#EXT-X_TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:37
#EXTINF:10
url1
#EXTINF:8
url2
#EXTINF:10
url3

The segment url1 has a time offset of 370, url2 is 380, and url3 is 388. Note that if no TARGETDURATION is specified, the default is 1, so the first segment in the file will have a nonzero time offset (equal to the target duration). The PlayStart content-meta data value allows direct seeking to an offset that is valid within the window of data in the current .m3u8 file.

There is a second way to seek in an HLS stream. If the m3u8 file has #EXT-X-PROGRAM-DATE-TIME entries, you can seek to a particular date/time by passing a value equal to a modified Unix epoch value. The modified epoch is 1/1/2004 rather than the standard Unix epoch of 1/1/1970. A Unix time value can be converted to an HLS seek time by subtracting 1072915200 (the number of seconds between 1/1/1970 and 1/1/2004). Once again, setting the PlayStart content meta data value allows direct seeking to a specific time offset.

For example, to seek to the segment marked with the date/time of 7/4/2010 11:30, set PlayStart to 205327800. An example shell expression showing this arithmetic is:
% expr `date -d "7/4/2010Z11:30:00.000" +%s` - 1072915200
205327800

In BrightScript, the same calculation might be:

dt = CreateObject("roDateTime")
dt.fromISO8601String("7/4/2010T11:30:00.000")
itemContentMetaData.PlayStart = dt. asSeconds() - 1072915200 '205327800
  1. In firmware version 2.6, we've introduced support for SRT files. Please see the content meta-data parameter SubtitleUrl for pointing to a matching SRT file for your video content.
  2. In firmware version 2.7, we've introduced 1080p support. Please see the content meta-data parameter FullHD for specifying 1080p resolution. Playback at 1080p resolution will only occur when the user has set the display type to HDTV 1080p. Another content meta-data parameter, FrameRate, specifies the frames per second of the video. Valid values are 24 and 30. If the user's display type is set to 1080p and FullHD for the content is false or not set, HD playback will be at 720p resolution. If the user's display type is set to HDTV 720p and FullHD content is set to 1080p resolution, the box will downscale the content to 720p resolution.

This object is created with no parameters:

CreateObject("roVideoScreen")
Example
 
 '**********************************************************************
 ' This example function is passed an associative array representing a ' piece of content (e.g. a TV episode) There are other attributes 
 ' (title, description, etc.) but this example focuses on showing
 ' attributes required for initiating playback. It creates a video 
 ' screen, sets the content and starts playback by calling Show()
 '**********************************************************************
 Function showVideoScreen(episode As Object)
     if type(episode) <> "roAssociativeArray" then
         print "invalid data passed to showVideoScreen"
         return -1
     endif 
     port = CreateObject("roMessagePort")
     screen = CreateObject("roVideoScreen") 
    ' Note: HDBranded controls whether the "HD" logo is displayed for a 
    '       title. This is separate from IsHD because its possible to
 ' have an HD title where you don't want to show the HD logo 
 ' branding for the title. Set these two as appropriate for 
 ' your content
    episode.HDBranded = false
    episode.IsHD = false 
    ' Note: The preferred way to specify stream info in v2.6 is to use
 ' the Stream roAssociativeArray content meta data parameter. 
 
 episode.Stream = { url:"http://myserver.mydomain.com/mycontent.mp4",
 bitrate:2000
 quality:false
 contentid:"mycontent-2000"
 }
 episode.StreamFormat: "mp4" 
    ' now just tell the screen about the title to be played, set the 
    ' message port for where you will receive events and call show to 
    ' begin playback.  You should see a buffering screen and then 
    ' playback will start immediately when we have enough data buffered. 
     screen.SetContent(episode)
     screen.SetMessagePort(port)
     screen.Show() 
    ' Wait in a loop on the message port for events to be received.  
    ' We will just quit the loop and return to the calling function 
    ' when the users terminates playback, but there are other things 
    ' you could do here like monitor playback position and see events 
    ' from the streaming player.  Look for status messages from the video 
    ' player for status and failure events that occur during playback 
     while true
        msg = wait(0, port)
    
        if type(msg) = "roVideoScreenEvent" then
            print "showVideoScreen | msg = "; msg.GetMessage() " | index = "; msg.GetIndex()
            if msg.isScreenClosed()
                print "Screen closed"
                exit while
             else if msg.isStatusMessage()
                   print "status message: "; msg.GetMessage()
             else if msg.isPlaybackPosition()
                   print "playback position: "; msg.GetIndex()
             else if msg.isFullResult()
                   print "playback completed"
                   exit while
             else if msg.isPartialResult()
                   print "playback interrupted"
                   exit while
             else if msg.isRequestFailed()
                   print "request failed - error: "; msg.GetIndex();" - "; msg.GetMessage()
                   exit while
             end if
        end if
     end while 
 End Function

Closed Captions

roVideoScreen supports a variety of options for displaying closed captions.  Refer to Closed Caption Support for complete details.

ID3 Tag Support

The 5.2 firmware release added ID3 tag support to the Roku platform to provide access to timed metadata that may be included in ausio and video streams.  In addition to roVideoScreen, support for ID3 tags is also available in roVideoPlayer and roAudioPlayer.  Timed metadata is used to embed information such as ad tracking beacons, links to additional information about the content being played such as IMDB entries of movies, player stats in sports channels, current song album art, or any other metadata with associated timecodes that match the audio or video.  Roku supports ID3 tags in HLS, Smooth Streams, MPEG-4 video and MP3 audio.

A BrightScript channel registers its interest ID3 tags in a stream by calling the SetTimedMetaDataForKeys() function defined on the ifVideoScreen, ifVideoPlayer, and ifAudioPlayer interfaces.  The channel passes an array of metadata key names to this function that corresponds to the set of metadata the channel wants to read.  When the PTS timecode of an ID3 tag equals the current PTS, the video or audio player component fires an isTimedMetaData() event which contains the details of the metadata.  See roVideoPlayerEvent and SetTimedMetaDataForKeys for details.

 

Attachments:

worddavdc8a50b63d70082736fbebee19c18eff.png (application/octet-stream)