Offline Playback with the Native Player SDKs

Product(s)
Video Cloud
Role(s)
Device SDK Developer
Task(s)
Develop with the Native SDKs
Topic(s)
Playback
SDK
Android

In this topic, you will learn how offline playback works with the Brightcove Native Player SDKs.

Overview

Offline Playback with the Brightcove Native Player SDKs for iOS and Android allows publishers to reach their viewers in entirely new ways while ensuring their content remains secure. Our SDKs offer powerfully simple solutions for complex offline playback problems including download management, offline catalog management, analytics, DRM, and of course playback.

Using offline playback, users can download both DRM-protected and clear (non-encrypted) video content to their devices and watch it when they are not connected.

Supported versions

The Brightcove Native Player SDKs support offline playback with the following versions:

Device OS version

  • iOS 10.0+, but 10.3+ is recommended
  • Android 5.0+

Brightcove Native SDK version

  • Native SDK for iOS 6.0.1+
  • Native SDK for Android 5.0.3+

Content delivery

Streaming video takes advantage of Video Cloud's multi-bitrate streaming feature which detects bandwidth at the source and delivers the best quality for the device. The offline playback feature supports the following streaming types:

  • Android: Dynamic Adaptive Streaming over HTTP (DASH)
  • iOS: Apple HTTP Live Streaming (HLS)

Security

The protection of downloaded content is top-of-mind with our Offline solution. The Brightcove Native Player SDKs provide the following functionality to ensure your content is stored safely on viewers' devices:

DRM-protected content

  • For DRM-protected content, the Native SDKs use the following technologies:
  • Video content can only be watched on the device and app that has downloaded the content.
  • Video content can only be watched until a specific date and time expiration.
  • Video URLs returned to the client will expire so that others can not use them.

All content

  • When the app is deleted, all downloaded content is removed.
  • Your app can delete locally stored content at any time.

Download management

The Brightcove Native Player SDKs handle the complexities of downloading content to a viewer's device, greatly simplifying the process for native applications.

  • Publishers can choose the rendition quality of the content to download.
  • Captions can be downloaded and displayed while offline.
  • Multiple audio tracks are supported by the Native SDKs. For details about adding additional tracks with the Native SDK for iOS, see the iOS App Developer's Guide for Offline Playback.

The following functionality can be added to your apps to support download management:

Display content

Display a list of content available for streaming or download.

When you set a video's offline_enabled property to true, the Native SDKs will mark this video as downloadable.

Prepare videos

To mark a video as downloadable, you need to do the following:

  1. Contact your account manager to enable your account for offline playback.
  2. For each video that you want to be downloadable, set offline enabled by doing one of the following:

    Use Video Cloud Studio

    Use Video Cloud Studio to enable offline playback.

    Offline enabled
    Offline enabled

    Use CMS API

    You can also use the CMS API to set the offline_enabled field to a value of true.

    Here is an example using curl:

    curl --header "Authorization: Bearer $oauth_token" --request PATCH --data '
    {"offline_enabled" : true}
    ' https://cms.api.brightcove.com/v1/accounts/your account id/videos/your video id
    
Display content
Display content

When working with clear content, see the Best practices section for tips on how to display your content.

Check download size

Before a download is requested, you should make sure there is enough space in device storage for the download. To get an estimate of the total size of the video download, follow these steps:

  • For iOS, review the information in the Check Download Size section of the iOS App Developer's Guide to Offline Playback.
  • For Android, you can get an estimate in the OnDownloadStarted callback from the DownloadEventListener. Here is an example of how to set the event listener:

    MediaDownloadable.DownloadEventListener downloadEventListener = new MediaDownloadable.DownloadEventListener() {
    //Your implementation.
    }
    OfflineCatalog catalog = new OfflineCatalog(context, eventEmitter, accountId, policyKey);
    catalog.addDownloadEventListener(downloadEventListener);

 

Show local storage space

Inform the user when there is not enough local storage to complete downloading the current item and any items in the queue.

The SDKs provide the estimated size and progress so that you can determine if there is sufficient space for downloads.

Show download status

Display the current download along with its status.

Total estimated size, current download status and percent of downloading progress information will be returned by the SDKs.

Manage the download queue

Create and manage the download queue.

The Native SDKs will allow multiple videos to be queued for downloads. For example, a user can download multiple episodes of a season and the Native SDKs will manage the process by providing download status for each asset.

Pause/resume/cancel download

Allow the user to pause, resume or cancel content download.

Download functionality will resume where it left off if the user pauses/resumes or if the download is interrupted. For example, it you lose Wi-Fi connection during download, it will resume where it left off when you are reconnected.

If you cancel a video download, then any progress made will be erased.

Local catalog management

The Brightcove Native Player SDKs simplify the process of managing downloaded local content.

The following functionality can be added to your apps to support local catalog management:

Show downloaded content

Show all of the downloaded episodes for each show/season.

The SDKs return metadata and playback details for all downloaded content. This metadata includes video title, description, thumbnails, available captions, available audio tracks, etc.

There are new metadata properties specific to offline playback, which include the following:

DRM-protected content

  • Token identifier
  • License expiration date

All content

  • Download start and end time
  • Downloaded thumbnail name along with its file URL
  • Downloaded poster name along with its file URL
  • Relative and derived file URL of the video bundle

You can then filter the results for your specific implementation.

Delete local content

Allow users to delete content from local storage.

The SDKs expose a method to delete a video along with its metadata and related assets.

Content playback

The Native SDKs allow you to play content in the following situations:

  • Play a video while it downloads.
  • Play a video after it has been downloaded. Downloaded content can be played back locally when the device is offline or online. The offline video can only be played from local storage.
  • If you choose to stream an online version of the video, you should retrieve a new video object from the Playback Service.

Analytics

Analytics have been introduced for measuring data related to the Offline flow. For details, see the Analytics Related to Offline Playback with the Native SDKs document.

Samples

The following table contains links to code samples to show you how to get started with offline playback:

Sample Application Description
iOS Offline Playback Download and play HLS videos, including those protected with FairPlay encryption. For developer details, see the iOS App Developers Guide for Offline Playback.
Android Offline Playback Download and play DASH videos, including those protected with Widevine encryption.

Notes

The following notes apply to the offline playback feature supported by the Native SDKs:

All

Currently, HLSe content is not supported with offline playback using the Brightcove Native SDK for Android, iOS or tvOS.

Android

When the app is deleted, all downloaded content is removed. This is true as long as the default storage location is not overridden.

iOS

As a security feature, you cannot stream an offline HLS video to an AirPlay device for playback. This is confirmed by Apple to be an AVFoundation limitation.

FAQ

Below you will find answers to some general questions.

DRM-protected content

Can the user change the system clock to bypass the expiration date?

Android: Absolute expiration determines the date and time until which a license is valid. This is enforced by Widevine and the Android DRM layer. Theoretically, the DRM layer in Android must prevent the user from bypassing the expiration period. Any issues that we may have found is described in the Android OS release notes.

iOS: License expiration is enforced by FairPlay. iOS handles all checking for clock changes, etc. An app has the option of checking the license expiration to alert the user that the license has expired. This may be preferable to simply playing back an expired video and then receiving a playback error.

Will the license and offline videos continue loading while the app is in the background?

Android: Yes. Typically, the license is downloaded immediately, but even the license can be downloaded while the app is backgrounded.

iOS: License loading should happen in the foreground. We have a method to preload the license. Downloading of the main video content can happen while the app is in the background.

All content

What is the video format used for downloading offline content?

Android: DRM-protected DASH or non-encrypted DASH.

iOS: HLS steaming. You can specify a bitrate for the download to use a specific variant.

Will downloaded videos playback locally or streaming when the user is online?

A downloaded video can be played back while online or offline, but it will always use the downloaded video. If you choose to play back an online version of the video, you should retrieve a new video object from the Playback Service. The offline video can only be played from local storage.

Will the release of Android OS v8.0 affect the Offline Playback feature?

The release of Android OS v8.0 will have new background service limitations. We will test and make any changes needed for continued support of Offline Playback with the Native Player SDK for Android.

Best practices

The following guidelines should help when developing your app for offline playback.

Displaying pause/cancel buttons

The pause and cancel buttons should be displayed when video download has started.

Android: You should display the pause and cancel buttons as part of calling the onDownloadStarted callback in the DownloadEventListener. For details, see the Offline Playback sample app.

iOS: For details about how to create an app for Offline Playback, see the iOS App Developer's Guide.

Displaying clear content

If your account is not DRM-enabled or you are working with clear content, the Brightcove Native SDKs will not perform a server-side license request. Therefore, clear content is not considered available for rental or purchase. In most cases, for clear content, it is recommended that you hide the rent and buy buttons and display a single download button instead.

Enabling the feature

Contact your account manager to learn about pricing and to enable the Offline Playback feature for your account.