## Overview

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

## Setup

In order to use offline functionality, the following dependency must be added manually to the build file:

Additionally, the permission for checking the network state is required in the Android Manifest:

Depending on the location the offline data is saved, it may also be required to add the STORAGE permission to the Android Manifest:

## API Usage

The core component responsible for handling offline content is the `OfflineContentManager`. It allows fetching the current offline state, requesting state changes and generating `SourceConfig` for offline playback.

### Initialization

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

### OfflineContentManager

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`, `offlineSourceConfig` and `release` are synchronous and return their values immediately.

#### OfflineContentManagerListener

The `OfflineContentManagerListener` provides seven callbacks:

  • **onOptionsAvailable** is called after a `getOptions` call, or when the state of an OfflineOptionEntry has 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.

  • **onSuspended** is called when all actions have been suspended.

  • **onResumed** is called when all actions have been resumed.

#### OfflineContentOptions

`OfflineContentOptions` can be received by calling `getOptions` on the `OfflineContentManager` for a specific `SourceConfig`. `OfflineContentOptions` represent the "offline state" of a stream and each available track (video, audio, captions/subtitles). It contains four lists, containing the different types: **video**, **audio**, **text** (captions/subtitles) and **thumbnails**.

### Downloading Content

Once an `OfflineContentManger` is created, downloading of content can be started. To gain knowledge of the available tracks and their state, `getOptions` should be called:

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

From the received `OfflineContentOptions` the separate `OfflineOptionEntry` can be received and selected for download or deletion. As an example, the `VideoOfflineOptionEntry` with the highest bitrate will be selected here for download:

_Note:_ Depending on the current state of the `OfflineOptionEntry` it might be not possible to set all actions. For example, already downloaded content cannot be downloaded again.

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

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

### Playback of Offline Content

When the `onCompleted(...)` listener callback has been invoked, meaning at least one `OfflineOptionEntry` is in the `DOWNLOADED` state, an `OfflineSourceConfig` can be requested from the `OfflineContentManager` for playback. With this `OfflineSourceConfig` a `SourceConfig` can be created and loaded into the `Player` as usual:

The Player is now ready to play the offline stored content.