5-视频下载

1.下載模組整合

影片下載功能透過獨立模組 media-player-sdk-addon-download 提供，需添加對應依賴

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

2.影片下載

影片下載的管理類別為 PLVMediaDownloaderManager，可透過此類別執行影片的下載、暫停、刪除等操作

2.1 初始化

在使用影片下載功能前，需呼叫初始化方法 PLVMediaDownloaderManager.init

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

其中，可透過 setting 參數設定下載的相關配置：

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

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

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

2.2 開始下載

首先，透過 PLVMediaDownloaderManager.getDownloader 取得對應影片的下載器

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

接著，呼叫 PLVMediaDownloaderManager.startDownloader 傳入對應的下載器，即開始影片的下載

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

2.3 狀態監聽

下載過程中的進度、影片資訊、下載速度等狀態可透過下載器的回呼中心 PLVMediaDownloader.listenerRegistry 監聽

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

2.4 暫停、刪除

影片下載的暫停和刪除也是透過下載管理類別 PLVMediaDownloaderManager 實現：

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

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

3.播放離線影片

為播放下載到本機的影片，需在建構影片資源 PLVMediaResource 時，傳入影片下載的根目錄路徑（即下載時設定的 PLVMediaDownloadSetting.downloadRootDirectory）

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

播放器會在 localVideoSearchPaths 下搜尋對應的離線影片，在已下載對應影片到本機的情況下優先播放本機影片。

4.點播SDK下載的影片相容

播放器支援相容播放點播SDK已下載完成的影片，但在播放之前，需呼叫 PLVMediaDownloaderVodMigrate.migrate 以確保播放器SDK能正常識別點播SDK下載的影片：

object PLVMediaDownloaderVodMigrate {

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

}

其中，searchRoots 參數為點播SDK下載時設定的下載根目錄。

透過 migrate 方法相容的點播下載，僅能相容已下載完成影片的播放。播放器SDK不會接管下載進度管理，您仍需在點播SDK進行下載管理、刪除等操作。

5.自訂傳入token

影片下載支援加密影片版權保護的自訂傳入token方式。生產環境建議由您的伺服器端產生下載所需的 token 後下發給客戶端，再按以下方式傳入：

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