Download and Offline Playback

This guide is designed to assist you how to download DASH content. We provides convenient APIs for DRM, media controllers, and a generic UI that can be customized as needed.
You can obtain a basic example of the Player Download and Offline Playback through this sample project.
For basic player SDK integration, you can refer to Getting Started.

Prerequisites

Request POST_NOTIFICATIONS permission

We have applied for the permission internally in the manifest, but you still need to request it once at runtime.

requestPermissions(
   arrayOf(Manifest.permission.POST_NOTIFICATIONS), POST_NOTIFICATION_PERMISSION_REQUEST_CODE
)

Downloader

Initialize Downloader

Create a simple downloader instance without settings the track selector callback. Downloader will automatically download the content tracks by default.

val downloader =  Downloader.Builder(context).build()

Start a download task

val config = DownloadConfig(
    mpdUrl = "xxxxx.mpd",
    // below parameters could be ignored, if download content type is non-DRM.
    drmServerUrl = DRM_SERVER_URL,
    drmRequestHeader = mapOf(
        "x-custom-data" to "token_type=xxxx&token_value=xxxxxxxxxx"
    )
)
downloadre.download(config)

Track selection

You can set the track selector callback within the downloader builder.

   private val callback = object : DownloadTrackSelection.Callback {
      override suspend fun selectTrack(downloadableTracks: DownloadableTracks): DownloadTrackSelection {
         // do something
         return DownloadTrackSelection(...)
      }
   }

   val downloader = Downloader.Builder(context)
         .setTrackSelectorCallback(callback)
         .build()

DownloadableTracks & DownloadTrackSelection

• Our library will call back to your application with the DownloadableTracks parameter, which contains all the downloadable tracks for the content you just called the download method.
• You can use the DownloadableTracks to create your own business logic and then return the track id defined in the DownloadableTracks by DownloadTrackSelection, then downloader will download these tracks according to it.
• You can ignore the third parameter in DownloadTrackSelection which means that you want to download all subtitles by default.

Notes

• If you return an empty DownloadTrackSelection, for example return DownloadTrackSelection(), this download process will be abandoned.

Limitation

• Each download task can only include one audio track and one video track, but can include multiple subtitle tracks.

Maximum parallel download

You can set the maximum parallel download thread by using below builder method. The default value is 3.

setMaxParallelDownloads(Int)

Customize download notification

You can replace the download notification by using below builder method.

setCustomNotification(object : DownloadNotification {
    override fun createCustomNotification(
        channelId: String,
        downloadStatus: List<DownloadStatus>
    ): Notification {
        // be excuted while downloading, so that you can update the progress in notification.
    }

    override suspend fun onDownloadStateChanged(
        channelId: String,
        status: DownloadStatus
    ): Notification? {
        // be executed every download status changed.
    }
})

Note: If you also want to modify the service channel name, please override it with the channel_name key as below.

<string name="channel_name">CustomChannelName</string>

Support multi-user download contents storage

You can keep multiple users downloaded contents in a single device by using one of below method. Downloader will separate these contents by each identifier.

1. modify the identifier parameter

   downloader.identifier = "NEW_USER_ID"
2. set the identifier when building the downloader

   val downloader =  Downloader.Builder(context)
           .setIdentifier("NEW_USER_ID")
           .build()

Usage

Downloader provides following functions to fulfil the needs of downloading

    /**
    * Flow for error Events of download processing
    *
    * @return {UniDownloadErrorEvent}
    */
   val errorEvent: Flow<UniDownloadErrorEvent>

   /**
    * Flow for download status, including {DownloadState} and progress in percentage
    */
   val downloadStatus: StateFlow<List<DownloadStatus>>

   /**
    * Start downloading for specified stream
    *
    * @param config the configuration for download content
    */
   fun download(config: DownloadConfig)

   /**
    * Pause downloading for specified stream
    */
   fun pause(config: DownloadConfig)

   /**
    * Resume downloading for specified stream
    */
   fun resume(config: DownloadConfig)

   /**
    * Remove an item while downloaded or still in downloading
    */
   fun remove(config: DownloadConfig)

   /**
    * Remove all items
    */
   fun removeAll()

   /**
    * Release the downloader.
    * We recommend that you should call this method when you don't need the downloader anymore.
    */
   fun release()

Download Status

Used to observe the download status in the list.

data class DownloadStatus(
    val mpdUrl: String,
    val state: DownloadState,
    val percentDownloaded: Float
)

Download State

• QUEUE: In download schedule
• STOPPED: Pause the download process
• DOWNLOADING: Downloading
• COMPLETED: Download Completed
• FAILED: Download Failed

Offline Playback

To playback the downloaded content in offline mode (no need network).
Using OfflineMediaConfig which wrap the manifest you just downloaded to tell our player for offline mode playback.

   // prepare the config
   val offlineMediaConfig = OfflineMediaConfig(
       title = "Offline Testing"
       mpdUrl = "*.mpd"
   )

   // load and start the playback process
   player.load(offlineMediaConfig)
   player.start()