[object Object] Icon

Learn how to create, start, manage and modify Encodings

[object Object] Icon

Learn how to create, start, manage and modify Players

[object Object] Icon

Learn how to create, start, manage and modify Analyticss

Docs Home
User shortcuts for search
Focus by pressing f
Hide results by pressing Esc
Navigate via   keys

Thu Sep 13 2018

Offline playback with the Bitmovin Android SDK

OverviewLink Icon

The Bitmovin Android SDK minimizes offline content management and playback to a few API calls, and allows fast integration of offline capabilities.

SetupLink Icon

In a default offline setup there are no additional steps required to the basic SDK setup.

Note: Depending on the location the offline data are saved, it may be required to add the STORAGE permission to the AndroidManifest:

1<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

API UsageLink Icon

The core component to handle offline content is the OfflineContentManager. It allows to fetch the current offline state, request state changes and generate SourceItems for offline playback.


One OfflineContentManager is linked with one SourceItem. When instantiating an OfflineContentManager, it is required to provide a storage location, a unique ID for the content, and a listener of type OfflineContentManagerListener.

1SourceItem sourceItem = new SourceItem("//url.to/online/resource.mpd");
2String downloadFolder = "/path/to/offline/folder/";
3String uniqueID = "uniqueID";
4OfflineContentManagerListener listener = new OfflineContentManagerListener() {
5 @Override
6 public void onCompleted(SourceItem sourceItem, OfflineContentOptions offlineContentOptions) { }
8 @Override
9 public void onError(SourceItem sourceItem, ErrorEvent errorEvent) { }
11 @Override
12 public void onProgress(SourceItem sourceItem, float progress) { }
14 @Override
15 public void onOptionsAvailable(SourceItem sourceItem, OfflineContentOptions offlineContentOptions) { }
17 @Override
18 public void onDrmLicenseUpdated(SourceItem sourceItem) { }
21OfflineContentManager offlineContentManager =
22 OfflineContentManager.getOfflineContentManager(sourceItem, downloadFolder, uniqueID, listener, androidContext);


Interaction with the OfflineContentManager is mostly done asynchronously. The results when calling getOptions, process and renewDrmLicense are received by the OfflineContentManagerListener, which is passed at creation of the OfflineContentManager. Only calls to getRemainingOfflineLicenseDuration, getOfflineSourceItem and release are synchronous and return their values immediately.


The OfflineContentManagerListener provides five callbacks:

  • onOptionsAvailable Is called after a getOptions call, or when the state of an OfflineOptionEntry has been changed. The states can be NOT_DOWNLOADED,DOWNLOADED, DOWNLOADING or DELETING.
  • onProgress Is called when the progress for an ongoing operation has changed e.g. the download progress.
  • onCompleted Is called when an operation has completed. This could be the downloading or deleting of content.
  • onDrmLicenseUpdated Is called when the stored DRM license was updated.
  • onError Is called when an error occurs.


OfflineContentOptions can be received by calling getOptions on the OfflineContentManager for a specific SourceItem.OfflineContentOptions represent the "offline state" of a stream and each available track (video, audio, captions/subtitles). It contains three lists, separating the different types video, audio and text (captions/subtitles).

Downloading Content

Once an OfflineContentManger was created, downloading content can be started. To gain knowledge of the available tracks and their state, getOptions must be called.


As this is an asynchronous call, the response must be handled in the OfflineContentManagerListener callback.

1public void onOptionsAvailable(SourceItem sourceItem, OfflineContentOptions offlineContentOptions) {
2 // Handling offline content options

From the received OfflineContentOptions the separated video, audio and text OfflineOptionEntry can be received and selected for download (or deletion). As an example, the VideoOfflineOptionEntry with the highest bitrate will be selected for download:

1List videoOptions = offlineContentOptions.getVideoOptions();
2VideoOfflineOptionEntry bestVideoOption = getOptionWithHighestBitrate(videoOptions);
4try {
5 bestVideoOption.setAction(OfflineOptionEntryAction.DOWNLOAD);
6} catch (IllegalOperationException e) {
7 // Action is not allowed in current state

Note: Depending on the current state of the OfflineOptionEntry it might be not possible to set a wanted action. For example: Already downloaded content cannot be downloaded again.

After successfully preparing the download, by setting the wanted actions, the OfflineContentOptions object is pushed back to the (correct) OfflineContentManager using the process(...) call.


This should trigger an onOptionsAvailable(...) listener callback. The OfflineOptionEntry entries which were selected to be downloaded, should have the state DOWNLOADING now. Until the onCompleted(...) listener is invoked, the onProgress(...) listener is called frequently with updated information about the ongoing operation.

1private T getOptionWithHighestBitrate(List entries) {
2 if (entries == null || entries.size() == 0) {
3 return null;
4 }
6 T entryWithHighestBitrate = null;
7 for (T entry : entries) {
8 if (entryWithHighestBitrate == null) {
9 entryWithHighestBitrate = entry;
10 continue;
11 }
13 if (entryWithHighestBitrate.getBitrate() < entry.getBitrate()) {
14 entryWithHighestBitrate = entry;
15 }
16 }
18 return entryWithHighestBitrate;

Playback of Offline Content

When the onCompleted(...) listener callback was invoked in the past, meaning at least one OfflineOptionEntry has the DOWNLOADED state, an OfflineSourceItem can be requested from the OfflineContentManager for playback

1OfflineSourceItem offlineSourceItem = offlineContentManager.getOfflineSourceItem();

With this OfflineSourceItem a PlayerConfiguration or SourceConfiguration can be created and passed to the BitmovinPlayer as usual.

3SourceConfiguration sourceConfiguration = new SourceConfiguration();

Now the bitmovinPlayer is configured and ready to play back offline stored content.

Give us feedback