5-视频下载

1. Module Integration for Download

The video download functionality is provided through a separate module media-player-sdk-addon-download, and the corresponding dependency needs to be added.

implementation("net.polyv.android:media-player-sdk-addon-download:${version}")

2. Video Download

The management class for video downloads is PLVMediaDownloaderManager, through which operations such as downloading, pausing, and deleting videos can be performed.

2.1 Initialization

Before using the video download feature, the initialization method PLVMediaDownloaderManager.init must be called.

/**
 * 初始化，调用其他方法前必须调用初始化方法
 */
@JvmStatic
@JvmOverloads
fun init(
    setting: PLVMediaDownloadSetting,
    onFinish: () -> Unit,
    onFailed: (Throwable) -> Unit
)

Here, download-related settings can be configured via the setting parameter:

data class PLVMediaDownloadSetting @JvmOverloads constructor(
    /**
     * 下载视频存放的根目录
     *
     * SDK 不会主动申请写入权限，外部调用需要确保 APP 具有对应目录的写入权限
     */
    val downloadRootDirectory: File,

    /**
     * 同时下载的任务数量限制
     */
    val concurrentDownloads: Int = Int.MAX_VALUE,

    /**
     * 清晰度降级
     *
     * 无法下载指定的清晰度时，自动下载较低的清晰度
     */
    val allowBitRateFallback: Boolean = true
)

2.2 Start Download

First, obtain the downloader for the corresponding video through PLVMediaDownloaderManager.getDownloader.

/**
 * 获取下载器
 *
 * @param mediaResource 视频资源
 * @param bitRate 指定下载的清晰度，可以通过 [updateSetting] 配置没有对应清晰度时自动降级。
 * 启用自动降级时可以通过 [IPLVMediaDownloaderListenerRegistry.downloadBitRate] 监听实际下载的清晰度。
 */
@JvmStatic
@JvmOverloads
fun getDownloader(
    mediaResource: PLVMediaResource,
    bitRate: PLVMediaBitRate = PLVMediaBitRate.BITRATE_AUTO
): PLVMediaDownloader

Then, call PLVMediaDownloaderManager.startDownloader with the corresponding downloader to start the video download.

/**
 * 开始下载
 */
@JvmStatic
fun startDownloader(downloader: PLVMediaDownloader)

2.3 Status Monitoring

The progress, video information, download speed, and other statuses during the download process can be monitored through the downloader's callback center PLVMediaDownloader.listenerRegistry.

val downloader = PLVMediaDownloaderManager.getDownloader(...)
// 监听下载速度
downloader.listenerRegistry.downloadBytesPerSecond.observe { bytesPerSecond ->
    // 业务操作
}

2.4 Pause and Delete

Pausing and deleting video downloads are also implemented through the download management class PLVMediaDownloaderManager:

/**
 * 暂停下载
 */
@JvmStatic
fun pauseDownloader(downloader: PLVMediaDownloader)

/**
 * 删除已下载的视频文件
 */
@JvmStatic
fun deleteDownloadContent(downloader: PLVMediaDownloader)

3. Playing Offline Videos

To play videos downloaded locally, when constructing the video resource PLVMediaResource, the root directory path for video downloads (i.e., the PLVMediaDownloadSetting.downloadRootDirectory configured during download) must be provided.

data class PLVVodMediaResource(
    // ...
    // 视频下载的路径
    val localVideoSearchPaths: List<String>
)

The player will search for corresponding offline videos under localVideoSearchPaths and prioritize playing the local video if it has been downloaded.

4. Compatibility with Videos Downloaded via VOD SDK

The player supports playing videos already downloaded via the VOD SDK. However, before playback, PLVMediaDownloaderVodMigrate.migrate must be called to ensure the player SDK can properly recognize videos downloaded by the VOD SDK:

object PLVMediaDownloaderVodMigrate {

    /**
     * 兼容播放在点播 SDK 下载的视频
     *
     * 只支持已经下载完成的视频。SDK 不会主动申请写入权限，外部调用需要确保 APP 具有对应目录的写入权限。
     *
     * @param searchRoots 搜索下载视频的根目录
     */
    @JvmStatic
    @JvmOverloads
    fun migrate(
        searchRoots: List<String>,
        onFinish: () -> Unit,
        onFailed: (Throwable) -> Unit
    )

}

Here, the searchRoots parameter is the download root directory configured during VOD SDK downloads.

Videos made compatible via the migrate method can only support playback of already completed downloads. The player SDK will not manage download progress; you still need to handle download management, deletion, and other operations within the VOD SDK.

5. Custom Token Input

Video download supports custom token input for encrypted video copyright protection. In a production environment, it is recommended that your server generate the token required for download and distribute it to the client, then pass it in as follows:

val downloader = PLVMediaDownloaderManager.getDownloader(...)
downloader.listenerRegistry.vodTokenRequestListener = object : IPLVVodMediaTokenRequestListener {
    override fun onRequestToken(
        mediaResource: PLVVodMediaResource,
        callback: (PLVVodVideoTokenVO?) -> Unit
    ) {
        // 通过网络请求，向您的服务器请求视频下载token
        var token: PLVVodVideoTokenVO
        // 将token返回给播放器
        callback(token)
    }
}