BIF "Trick Mode" Support

BIF, or "Base Index Frames", is an archive file format that contains a set of still images supporting enhanced fast-forward and rewind modes during video playback on Roku devices.

"Commercial" channels can use the built-in BIF file creator to generate a BIF file for a video, automatically store the BIF file in an S3 bucket, and write the BIF file's URL into the video's HDBifUrl parameter.

When a BIF file is provided for a video, a timeline of screenshots is provided when fast-forwarding or rewinding through the video:

Without a BIF file, the current frame of video is frozen on-screen when fast-forwarding or rewinding:


A note about Amazon AWS pricing: Amazon's S3 pricing is separate from Instant TV Channel's monthly charges. Amazon has a Free Tier for new customers which may include some or all of your S3 charges. All Amazon S3 charges are billed directly from Amazon, and are dependent mainly on the sizes of the files and how often they are accessed. A BIF file for a 30-minute video using a BIF Interval of 30 seconds and a BIF Image Quality of 6 might be around 1MB in size. You can check the actual sizes of your BIF files by looking in your BIF bucket using the Amazon AWS console. Amazon will bill you approximately $0.0001 (one one-hundredth of one cent) for each download or use of a 1MB BIF file, or about $0.01 (one cent) for every 100 downloads or uses. When a video with a BIF is selected in your Roku channel, the BIF file is usually completely downloaded to the Roku device before the video starts to play.

DISCLAIMER: Instant TV Channel cannot guarantee that this AWS pricing information is accurate or complete. Please visit Amazon at http://aws.amazon.com/s3/pricing/ for current pricing.


How to add BIF to COMMERCIAL channels:

BIF files can be added to your Roku channel several different ways:

  • Using BIF-generation software to create the BIF file. The BIF file must be uploaded to a web server or hosting service. The URL for the BIF file must be manually entered into the video's HDBifUrl parameter.
  • Using Instant TV Channel to create the BIF file. The BIF file is emailed to you, which you must then upload to a web server or hosting service. The URL for the BIF file must be manually entered into the video's HDBifUrl parameter.
  • Using Instant TV Channel to create the BIF file. Instant TV Channel stores the BIF file in a pre-configured S3 bucket, and automatically populates the HDBifUrl parameter.

Reasons for choosing one method or another are:

  • BIF files stored in and served from an AWS S3 bucket may cost more than using a web server or other hosting service.
  • The built-in Instant TV Channel BIF creator is only available for "Commercial" channel types.
Not Using S3? If you are not going to use an S3 bucket to store your BIF files, then skip the following section and continue at Review and Optionally Adjust Other BIF Parameters.
 
Shortcut for Setting Up the S3 BIF Bucket If you have not yet entered keys for the BIF bucket, an AWS Wizard symbol will be visible at the top of the BIF section on the Keys & CDNs page:
AWS Key Wizard
Click on the AWS Wizard symbol (on the Keys & CDNs page) and follow the on-screen directions to create the BIF bucket and keys.

After using the AWS Wizard, skip the following section and continue at Review and Optionally Adjust Other BIF Parameters.

Create the BIF Bucket

  1. Log into your AWS account and go to the S3 section of your AWS control panel.
  2. Click the Create Bucket button.

    This should be a new bucket that is used only for BIF files.

  3. Provide a Bucket Name, for example "my-bif-bucket".

    Very Important: Use only lower-case characters, digits, and dashes in your bucket name. Instant TV Channel does not support the use of upper-case characters or other symbols in bucket names.

    Good Bucket Name: bif-bucket
    Good Bucket Name: bif123
    Bad Bucket Name: bif.bucket (contains unsupported period character ".")
    Bad Bucket Name: bif+123 (contains unsupported plus character "+")
    Bad Bucket Name: BIF-Bucket (contains upper-case characters)
  4. The bucket Region must be set to "US East (N. Virginia)".
  5. Click the Create button, do not click the Next button.

The default ACL (Access Control List) on your new bucket is "Private", meaning that an AWS key is required to access files in the bucket. The bucket cannot be accessed using a plain http:// or https:// URL. This is usually the correct setting for a BIF bucket used in an SDK channel, as it only allows the Instant TV Channel web site and your channel running in a Roku device to access the BIF files.

BIF buckets used for Direct Publisher channels will need to have their permissions modified to allow public read-only access. This is not recommended as it may allow unauthorized access to your BIF files which may result in significant AWS charges. Instructions for configuring a bucket for public access are here.

Create IAM Keys to Access the BIF Bucket

We will create two sets of keys to grant access to your BIF bucket. One set of keys will grant read-write access to the bucket and will be used by the Instant TV Channel web site to write new BIF files into your S3 BIF bucket. The other set of keys will grant read-only access to the BIF bucket and will be used to load BIF files directly into any Roku device that has your channel installed. Because the Roku device does not need to alter the contents of the BIF bucket or BIF files, its keys can be read-only. The use of read-only keys is optional, if not present then any Roku device with your channel installed will use the read-write keys.

  1. Go to the IAM (Identity and Access Management) section of your AWS control panel.
  2. Click the Policies link on the left side of the page.
  3. Click the Create policy button near the top of the page.
  4. Click the JSON tab, and erase the sample lines of JSON text.
  5. Copy the security policy below and paste it into the JSON text box. Replace the two instances of
    my-bif-bucket
    in the policy with the name of the bucket that you just created. This security policy allows files in the BIF bucket to be created, read, modified, or deleted.
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:*"
          ],
          "Resource": [
            "arn:aws:s3:::my-bif-bucket",
            "arn:aws:s3:::my-bif-bucket/*"
          ]
        }
      ]
    }
  6. Click the Review policy button near the bottom of the page. An error message will be displayed if there are any errors in the JSON text. After correcting the errors, click the Review policy button again.
  7. Provide a Policy Name, for example "my-rw-bif-policy" ("rw" stands for read-write).
  8. Click the Create policy button near the bottom of the page.
  9. Click the Groups link on the left side of the page.
  10. Click the Create New Group button near the top of the page.
  11. Provide a group name, for example "my-rw-bif-group", then click the Next Step button near the bottom of the page.
  12. The "Attach Policy" page is displayed. Scroll down the list of policies until the "my-rw-bif-policy" policy that you just created is visible, or type the name of your newly created policy in the "Filter" box. You may need to scroll through a large number of built-in AWS policies until your policy is visible.
  13. Click the check-box to the left of your policy name, making sure that no other check-boxes are checked, then click the Next Step button near the bottom of the page.
  14. Click the Create Group button near the bottom of the page.
  15. Click the Users link on the left side of the page.
  16. Click the Add User button near the top of the page.
  17. Enter a new user name, for example "my-rw-bif-user".
  18. Select an Access type of "Programmatic access".
  19. Click the Next: Permissions button near the bottom of the page.
  20. Click the check-box to the left of the previously created Group name, then click the Next: Tags button near the bottom of the page.
  21. Click the Next: Review button near the bottom of the page.
  22. Click the Create user button near the bottom of the page.
  23. Click the Show link beneath "Secret access key" or click the Download .csv button to copy and save the Access Key ID and Secret Access Key. These keys will be used exclusively for read-write access to your BIF bucket. They cannot be used to access any other AWS buckets or services. Make sure that you save the keys for future use, Amazon will not display them again. If you misplace the keys you will have to create a new IAM user.
  24. After copying the Security Credentials, click the Close button near the bottom of the page.

    At this point we have a new IAM user that is a member of a new IAM group - the user has the keys and the group has the security policy. The keys for this IAM user can be used in the Roku channel to access the BIF bucket specified by the security policy.

  25. Repeat each of the steps above, beginning with Go to the IAM (Identity and Access Management) section... to create a read-only IAM group, policy, user and keys. This time use the security policy below for the Policy Document box, replacing the two instances of
    my-bif-bucket
    in the code below with the name of the bucket that you previously created. This security policy allows files in the BIF bucket to be read, but not created, modified, or deleted.
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:Get*",
            "s3:List*"
          ],
          "Resource": [
            "arn:aws:s3:::my-bif-bucket",
            "arn:aws:s3:::my-bif-bucket/*"
          ]
        }
      ]
    }
  26. The same BIF bucket and keys can be used for other channels. It is not necessary to create a new bucket and keys for each channel. You can use the BIF Bucket Prefix parameter on the Keys & CDNs page to organize the BIF files for each channel into separate folders within the bucket.

Copy the BIF Bucket Name & Keys to your Channel

  1. Sign into Instant TV Channel and select the channel that you want to configure for BIF.
  2. Go to the channel's Keys & CDNs page.
  3. Under AWS S3 BIF Storage, copy the new BIF bucket name into the BIF Bucket Name box.
  4. Copy the read-write IAM user's Access Key ID into the BIF Read-Write Access Key ID box.
  5. Copy the read-write IAM user's Secret Access Key into the BIF Read-Write Secret Access Key box.
  6. Copy the read-only IAM user's Access Key ID into the BIF Optional Read-Write Access Key ID box.
  7. Copy the read-only IAM user's Secret Access Key into the BIF Optional Read-Write Secret Access Key box.
  8. Click the TEST S3 BIF STORAGE button and verify that the S3 BIF bucket Read-Write and Read-Only tests OK message is displayed. If the test fails, verify that your S3 keys were copied correctly and try again.

Review and Optionally Adjust Other BIF Parameters

  • The BIF Bucket Prefix parameter can be used with a value such as "my-channel/" to store the BIF files for this channel in a separate folder within the bucket.
  • The BIF file name is usually created from the Title of the video. Change the BIF Filename Source parameter to use a different source for the BIF file name. Available sources are:
    • Title
    • DeepLinkId
    • Stream 1 URL
    • ShortDescriptionLine1
    • ShortDescriptionLine2
    • Content UID
  • The BIF Filename Prefix must be "bif://" in order to use the secure BIF bucket keys. When using BIF files in a Direct Publisher channel the secure keys cannot be used, and it is necessary that all BIF files have public URLs. This can be accomplished by changing the BIF Filename Prefix to a public prefix such as http://s3.amazonaws.com/bucketname/ along with configuring a public access policy for the BIF bucket.
  • If you are not using an S3 bucket to host your BIF files, the BIF Filename Prefix parameter can be set the URL of your BIF web server or hosting service, for example http://my.webserver.com/roku/bifs/
  • The BIF Interval, the length of time between each BIF image, can be increased or decreased. The allowable range is from 5 seconds to 60 seconds. Smaller BIF Interval values will result in larger BIF file sizes and higher bandwidth costs. In general, channels containing mostly short-form video content should have a smaller BIF Interval value, and channels containing mostly long-form video content can safely have a larger BIF Interval value.
  • The BIF Offset should usually remain at 1. Increasing this value will shift the BIF images relative to the corresponding positions in the video.
  • In order to overwrite already-existing BIF images stored in the BIF bucket, it is necessary to change BIF File Overwrite Enable to "Yes". Leave BIF File Overwrite Enable at "No" to prevent existing BIF files from being accidentally overwritten.
  • Increasing the BIF Image Quality from the default value of 6 will improve the sharpness of the BIF images, at the expense of a larger BIF file size and bandwidth cost.

Create BIF Files

The automated Instant TV Channel BIF file creator can be used only after the BIF S3 bucket and keys have been configured on the Keys & CDNs page.

To request a BIF file for any video in your channel:

  • Click the Create BIF button next to the HDBifUrl parameter on the video item's Content page.
  • BIF files can be created from MP4, MKV, non-live HLS, and Vimeo video stream URLs. Other stream URL formats are not yet supported.
  • The SDBifUrl and FHDBifUrl parameters are not used at this time.
  • It may take several hours for your BIF file to be generated. It's OK to leave the Content page or edit a different content item, your BIF file request will still be processed.
  • Your video's HDBifUrl parameter will be automatically filled-in after the BIF file has been created, and will be visible when you return to this content item.
  • You can refresh the content item by clicking on the item's icon in the content tree.
  • Erasing the HDBifUrl "BIF file has been requested" message while the request is being processed may prevent the BIF URL from being written into the HDBifUrl parameter, however this will not prevent the BIF file from being created and stored into the S3 bucket or emailed to you.
  • If you are storing your BIF files into an S3 bucket, a brief email report will be optionally sent to you after each BIF file is successfully stored, if enabled on the "Account" page. A separate email is sent for each BIF file.
  • If you are not storing your BIF files into an S3 bucket, each BIF file will be sent to you as an email attachment. After receiving the BIF file you will need to upload it to your hosting service.
  • Don't forget to check that the automatically-generated HDBifURL works correctly with your hosting service. It can be adjusted using the BIF Filename Prefix parameter on the Keys & CDNs page.


How to add BIF to FREE and UNLIMITED channels, or if not using AWS S3:

Your Instant TV Channel account Developer Mode must be set to Advanced in order to view or change the BIF parameters in older content items. You can change the Developer Mode from the Instant TV Channel Account page.

Technical details on BIF are here: https://sdkdocs.roku.com/display/sdkdoc/Trick+Mode+Support#TrickModeSupport-BIFFileSpecification



Want to know how to make a Roku channel in 5 minutes? Check out this Instant TV Channel Walk-Through!

 

Instant TV Channel is a cloud-based tool for Roku developers and content providers that shortens development time and eases maintenance after deployment.



Access Code: U463
Check out Instant TV Channel by adding our latest demonstration channel to your Roku player, or watch the YouTube video.

Need help with your Roku?

We are unable to provide technical support for your Roku device.

Please visit www.roku.com for assistance.



Instant TV Channel is not affiliated with nor endorsed by Roku Inc.