Roku SDK Documentation : Fast Video Start

Table of Contents

Available since firmware version 7.2

Fast Video Start is a user interface design technique for VOD channels that reduces the amount of time apparent to the user that the video stream buffers before actual playback begins.

All digital video requires some time after a video is selected to begin playback, and video files streamed over HTTP add network transfer rates to this buffering time. Typically, to play back a video, the Content Meta-Data for a video is set, and an roSpringboardScreen component (or equivalent) is shown to the user with descriptive details about the video. When the user actually selects the video for playback, calling play() on the roVideoScreen or roVideoPlayer object shows a "loading" screen before actual playback, while the video stream is buffering. "Fast start" allows this video stream buffering to take place before the user has actually selected a video for playback, by initiating the buffering process while the user is deciding whether to play a certain video.

To implement Fast Video Start, you create a roVideoScreen or roVideoPlayer component prior to showing a roSpringboardScreen (or equivalent) for a video, and call Prebuffer(). The video stream will buffer for as long as the user is reading the description of the video on the screen. Then when the user actually selects the video for playback, call play(). Depending on how much time the user spent reading the video description, the video may begin actual playback immediately, or with a much reduced amount of time that the "loading" screen is shown.

Calling Prebuffer() starts buffering the video specified by a previous SetContentList() (for roVideoPlayer) or SetContent() (for roVideoScreen) call. If the video has not been specified in one of these ways, calling Prebuffer() has no effect.

roVideoPlayer and roVideoScreen Use Cases

Prebuffer Before Playback: roVideoPlayer

The following code demonstrates this use case.

port = CreateObject( "roMessagePort" )

content = {
  Stream: { url : "http://play.this.url.com/video.m3u8" }
  StreamFormat: "hls"
}

' First   create the player and set content list
player = CreateObject( "roVideoPlayer" )
player.setMessagePort( port )
player.setContentList( content )
' Prebuffer the data
player.Prebuffer()

' Show the springboard screen and wait for an event
' from user asking to playback the content
while true
  msg = wait( 0, port)
  ' break out if correct message is received
end while

' Start   playback now
player.play()

' Handle user requests here
while true
  msg = wait( 0, port )
  ' process msg here
end while

For this use case, the video player event handling has to occur in two event loops, one while prebuffering from the roSpringboardScreen (or equivalent), and one during playback. This is necessary since the firmware may encounter errors during prebuffer that should be handled by the channel.

Playback Canceled After/While Prebuffering: roVideoPlayer

If the channel calls Stop() while prebuffering, prebuffered video data is discarded. The channel can subsequently call SetContentList(), Prebuffer() and Play() to play back a new video.

Prebuffer Before Playback: roVideoScreen

port = CreateObject( "roMessagePort" )

content = {
  Stream: { url : "http://play.this.url.com/video.m3u8" }
  StreamFormat: "hls"
}

player = CreateObject( "roVideoScreen" ) 
player.setMessagePort( port )
player.setContent( content ) 
player.Prebuffer()

' Playback starts with the show() call
player.show()

while true
  msg = wait( 0, port ) 
  ' process msg here
end while

Prebuffer Resume: roVideoScreen

This use case is for a channel that implements a resume playback feature. Channels using the roVideoScreen component can detect when the user has left the video screen and returned to the previous screen (such as a roSpringboardScreen) by handling the isScreenClosed event. After such an event, the channel could return to the springboard screen, update the user interface to include a Resume button, recreate the roVideoScreen, and begin playback at the point the video playback was interrupted. In this case the channel would set the Content Meta-Data PlayStart position to the appropriate bookmark timestamp, and proceed as in the previous use case:

port = CreateObject( "roMessagePort" )

content = {
  Stream: { url : "http://play.this.url.com/video.m3u8" }
  StreamFormat: "hls"
  PlayStart: ' bookmark value in milliseconds
}

player = CreateObject( "roVideoScreen" )
player.setMessagePort( port )
player.setContent( content )
player.Prebuffer()

' Playback starts with the show() call 
player.show()
 
while true
  msg = wait( 0, port )
  ' process msg here
end while

Additional Considerations

To make use of the "fast start" feature, when a channel enters the springboard (or movie details) screen, it must create a roVideoPlayer or roVideoScreen, and prebuffer the video. There are a few things to consider.

Prebuffer Position

Channels may have multiple play options on the springboard screen, including resuming playback and playback from start. A bookmarked position may be set in Content Meta-Data to indicate the playback start position. Each play option will have a different play position associated with it. The bookmark position will have to default to one of the play positions and prebuffer the content from here. If the user selects the other play option, the data must be buffered again.

Resuming Playback: roVideoScreen

There are two ways that a user may be shown a springboard screen. The first is by selecting a video, and the second is by pressing the back key while the video is playing.

When a user first enters the springboard screen by selecting a video, the channel has an opportunity to prebuffer content. It may offer an option to resume from a previously bookmarked position. To play from a bookmarked position, follow these steps:

1. Create Content Meta-Data, and set the BOOKMARKPOSITION
2. Create a roVideoScreen object
3. Call SetContent() with the Content Meta-Data
4. Call Prebuffer() with the Content Meta-Data

Then, if the user selects the resume option, the channel should call Show() to playback from the buffered position, which should be the same as BOOKMARKPOSITION.

When the user returns to the springboard screen by press the BACK key, the channel must still be ready to resume from the last viewed position. It should have cached the last position reported by roVideoScreen. Currently, roVideoScreen channels will repeat the steps listed above. However, the data will be buffered in roVideoScreen. It should be possible for roVideoScreen channels to simply unpause the video for a better end user experience.

Resuming Playback: roVideoPlayer

A user may exit playback to go back to the springboard screen, and then resume playback of the same video. Since the roVideoPlayer will have buffered the data, the channel will ideally just resume playback. When going back to the springboard screen, Roku recommends that playback should be paused on roVideoPlayer. A user request to resume playback will take effect instantaneously. If the user starts playback from the beginning, then the roVideoPlayer must be stopped first, the BOOKMARKPOSITION modified in Content Meta-Data, and a new playback session started.