5-视频下载

1. Download Module Integration

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

{
  "dependencies": {
    "@polyvharmony/media-player-sdk-addon-cache-down": "$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.

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

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

export class PLVMediaDownloadSetting {

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

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

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

2.2 Start Download

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

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

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

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

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.

const downloader = PLVMediaDownloaderManager.getInstance().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:

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

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

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.

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

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

4. Custom Token Input

Video downloads support a custom token input method for encrypted video copyright protection. In a production environment, it is recommended that your server generates the token required for download and delivers it to the client, then input it as follows:

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