Skip to end of metadata
Go to start of metadata

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:

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:

 


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: 

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):

  • 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:

DisplayAspect RatioWidthHeight
SD4:3240180
HD4:3320240
HD16:9320180
HD2.35320136

Executable Help

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.

byte01234567
value0x890x420x490x460x0d0x0a0x1a0x0a

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.

byte 8 9 1011
valueVersion

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.

byte12131415
valueNumber of BIF images (N)

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.

byte16171819
valueTimestamp Multiplier
(in milliseconds)

Reserved

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

byte20     ...     63
value0x00 / / 0x00

BIF index

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

byte6465666768697071

index 0

Frame 0 timestampabsolute offset of frame
index 1 Frame 1 timestampabsolute offset of frame
index 2Frame 2 timestampabsolute offset of frame
...        
index N-1Frame N-1 timestampabsolute offset of frame
index N0xfffffffflast byte of data + 1 

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.

 

 

  • No labels