5-视频下载

1.下載模組整合

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

{
  "dependencies": {
    "@polyvharmony/media-player-sdk-addon-cache-down": "$version"
  }
}

2.影片下載

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

2.1 初始化

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

/**
 * 初始化，调用其他方法前必须调用初始化方法
 */
async init(setting: PLVMediaDownloadSetting): Promise<void>

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

export class PLVMediaDownloadSetting {

  /**
   * 下载视频存放的根目录
   *
   * SDK 不会主动申请写入权限，外部调用需要确保 APP 具有对应目录的写入权限
   */
  readonly downloadRootDirectory: string;

  /**
   * 同时下载的任务数量限制
   */
  readonly concurrentDownloads: number;

  /**
   * 清晰度降级
   *
   * 无法下载指定的清晰度时，自动下载较低的清晰度
   */
  readonly allowBitRateFallback: boolean;
  
}

2.2 開始下載

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

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

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

/**
 * 开始下载
 */
startDownloader(downloader: PLVMediaDownloader): void

2.3 狀態監聽

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

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

2.4 暫停、刪除

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

/**
 * 暂停下载
 */
pauseDownloader(downloader: PLVMediaDownloader): void

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

3.播放離線影片

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

const mediaResource: PLVVodMediaResource = {
  // ...
  // 视频下载的路径
  localVideoSearchPaths: [downloadRootDirectory]
}

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

4.自訂傳入 token

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

downloader.listenerRegistry.vodTokenRequestListener = {
  async onRequestToken(mediaResource: PLVVodMediaResource): Promise<PLVVodVideoTokenVO> {
    // 通过网络请求，向您的服务器请求视频下载token
    const token: PLVVodVideoTokenVO = await fetchTokenFromNetwork()
    // 将token返回给播放器
    return token;
  }
}