Roku SDK Documentation : Trick Mode Support

Table of Contents

Two types of trick mode support (FF/REW/SEEK) are provided. For developers who generate and publish image archives in the Roku BIF (Base Index Frame) file format, scene-based trick-mode using index frames will be supported. A specification is available below which details the BIF file format and data required. If this data is published and available for a given title, scene-based trick-modes will be available. The content meta-data indicates the availability of this data on a per title basis by providing URLs for the HD and SD versions of these assets. 

In cases where the BIF file is either not supported or unavailable, the system will present a time-based method of supporting trick modes. The user will be presented with a progress bar showing their location in the show and be allowed to seek using the normal trick play controls. Since scene information is not available, the user will only have a visual timeline and numeric time information to locate their desired position in the movie. Once the new location is selected, the system will buffer a minimal amount of stream data and begin playback.

BIF File Creation using the Roku BIF Tool

Roku provides command-line tools for Mac, Windows, and Linux that lets you generate BIF files for your videos.

Mac and Linux

Mac Installation

Prerequisites:

• Xcode
• Homebrew*
• FFmpeg

Homebrew is a command-line package manager for Mac OS X. It is not required to use Roku's BIF tool, but it can be used to easily install FFmpeg.

After you have Xcode and Homebrew installed, open your terminal application and run: $ brew install ffmpeg

Download and Unzip: biftool_mac.zip

Linux Installation

Prerequisites:

• ffmpeg-lib

On RedHat and Fedora Core, you can typically install ffmpeg-lib by running this yum command as root: $ yum install ffmpeg-libs

Download and Unzip: biftool_linux.zip

The executables are compiled for Linux x86 64-bit machines. Make sure that the biftool and biftool_processor executables are in the same directory on the development machine.

Mac and Linux Usage

The BIF tool will automatically generate three .bif files: one for SD, one for HD, and one for FHD.

Example:

$ path/to/biftool ~/public_html/Movies/HarryPotter/HLS/600000/*.ts 
Finding candidate frames in 917 files 
Detected stream PTS offset of 10033ms 
Captured 2368 candidate frames in 79s 
Selected 915 BIFs 
Success: ./fileSequence0000-fhd.bif (size=14.096MiB, numImages=915, avgSize=15.767KiB) 
Success: ./fileSequence0000-hd.bif (size=8.528MiB, numImages=915, avgSize=9.535KiB) 
Success: ./fileSequence0000-sd.bif (size=3.920MiB, numImages=915, avgSize=4.378KiB)

Windows

Windows Installation

Download and Unzip: biftool_windows.zip

Windows Usage

The simplest way to use the command-line tool is to open your favorite terminal application, and drag the biftool executable to its window. After that, just add the path to a video and biftool will generate the BIF files and save them to your current directory.

For example: $ ./path/to/biftool ./path/to/video-file.mp4

You can also type --help after dragging the biftool executable, and the terminal will display a help message containing more details and options about using the tool.

We recommend generating two .bif archives for each piece of content, one for SD and one for HD. Roku devices automatically select which version will be used depending on the user UI. That is why it is important to generate HD .bif archives even if the content is SD. If there is no HD .bif available, the player will fallback to using the SD .bif.

Example: 

$ mkdir abc-sd abc-hd 
$ ffmpeg -i abc.mp4 -r .1 -s 240x180 abc-sd/08d.jpg 
$ ffmpeg -i abc.mp4 -r .1 -s 320x240 abc-hd/08d.jpg 
$ path/to/biftool -t 10000 abc-sd 
$ path/to/biftool -t 10000 abc-hd

This will result in two new files: abc-sd.bif and abc-hd.bif.

There are two caveats here:

• FFmpeg generates the JPG files starting with index 1. This means that all the timestamps will be off by 10 seconds. To fix this, use the following command (make sure you are in the directory containing the .bif files):

  $ % j=00000000.jpg; for i in *; do mv ${i} ${j}; j=${i}; done;

• The SD frames should have a width of 240, and the HD frames should have a width of 320. Their height should be specified to coincide with their aspect ratio. The commands above assume a 4x3 aspect ratio. Unfortunately, FFmpeg doesn't let you specify only a width, keeping the original aspect ratio. If your source file is not 4:3, you should calculate the height used in the commands above using the width and the aspect ratio.

Here are some common resolutions:

Executable Help

biftool <options> <target(s)>

Three types of <target(s)> are allowed:

1) A single <target> which is a directory. All files in the directory will be archived into single BIF file with the same name as the directory.

2) A single <target> which is a file with a .bif suffix. Its contents will be extracted into a new directory with the same name as the file. E.g., extracting mymovie-hd.bif will create and populate a directory named mymovie-hd.

3) One or more <targets> which are files that do not have a .bif suffix. These files are assumed to be video files, such as .mkv, .mp4 and .ts files. Frames will be extracted from the first video stream in each file, to create a single .bif file with the same base name as the first video file specified. If more than one video file is specified, they are expected to be segments of the same video and must be specified in playback order, based on the presentation timestamps (PTSes) within the files

Available options:
  --target arg                      The file(s) or directory on which to
                                   operate.
  -t [ --timestamp-multiplier ] arg The absolute presentation timestamp (PTS)
                                    in milliseconds is the filename multiplied
                                    by this value.
  -v [ --verbose ]                  Be verbose about activity.
  -h [ --help ]                     Help message.

BIF File Specification

The following specification describes the implementation of the BIF (Base Index Frames) file archive. The BIF archive is used to encapsulate a set of still images for supporting video trick modes (e.g. FF/REW) on the Roku Streaming Player. This format has been optimized for the usage pattern inherent in this model and is well-suited and capable of facilitating those patterns in an efficient manner.

Requirements and Usage Patterns

It is important that the file format have the following features:

• It must be easy to find and interpret the archive metadata.
• It must be network-access friendly.
• It must minimize levels of indirection.
• It must be compact.
• It must easily accommodate the entire range of possible data.

The format should also be capable of providing future extensions should they be needed.

Conventions

This specification assumes that all values are stored little-endian. 

File Format

All multibyte integers are stored in little-endian format. That is, the first byte is the least significant byte and the last byte is the most significant.

Magic Number

This is a file identifier. It contains enough information to identify the file type uniquely.

Version

This space is reserved for a revision number. The current specification is file format version 0. The value should be incremented for non-backward-compatible revisions of this document.

Number of BIF images

This is an unsigned 32-bit value (N) that represents the number of BIF images in the file. The number of entries in the index will be N+1, including the end-of-data entry.

Framewise Separation

This specifies the denomination of the frame timestamp values. In order to obtain the "real" timestamp (in milliseconds) of a frame, this value is multiplied by the timestamp entry in the BIF index.  If this value is 0, the timestamp multiplier shall be 1000 milliseconds.

Reserved

These bytes are reserved for future expansion. They shall be 0.

BIF index

This space is used for the BIF index entries. There are N+1 entries. Each entry contains two unsigned 32-bit values.

Because the size of each BIF is determined by subtracting its offset from the offset of the next entry in the index, the BIFs shall appear in the index in the same order as they appear in the data section, and they shall be adjacent. 

The absolute timstamps of the BIF captures can be obtained by multiplying the frame timestamp by the timestamp multiplier.

Data section

This section contains the BIF images. It begins after the index, though it is not necessary that the first image appear immediately after the index. Each image in the data section must begin at the offset specified in the BIF index.

Sample channels

You can download and install sample channels that demonstrate different ways to incorporate thumbnails for trick play.