进阶功能

鸿蒙HarmonyOS NEXT播放器SDK支持添加和切换外挂字幕，现已支持SRT、SSA、ASS、VTT这4种格式的字幕。但还不支持提供外挂字幕的渲染工具，用于直接渲染外挂字幕。示例如下：

1. 设置字幕相关监听。

   展开查看代码

   private mOnSubtitle: OnSubtitleDisplayListener = {
       onSubtitleExtAdded: (trackIndex: number, url: string): void => {
         //外挂字幕已被添加
       },
       onSubtitleShow: (trackIndex: number, id: number, data: string): void => {
         //获取到外挂字幕的字符信息，获取到data后 做相关显示
       },
       onSubtitleHide: (trackIndex: number, id: number): void => {
         //隐藏显示
       },
       onSubtitleHeader: (trackIndex: number, header: string): void => {
         //字幕头信息
       }
     }
   
     mAliPlayer.setOnSubtitleDisplayListener(this.mOnSubtitle);

2. 添加字幕。

   mAliPlayer.addExtSubtitle(url);//在播放器onPrepared回调后添加

3. 显示或隐藏字幕。

   在收到onSubtitleExtAdded回调后，可通过如下方法进行显示或隐藏字幕：

   //trackIndex：传入字幕索引；true：表示显示传入的字幕；false：表示隐藏传入的字幕
   mAliPlayer.selectExtSubtitle(trackIndex, true);

鸿蒙HarmonyOS NEXT播放器SDK通过配合点播服务配置，可以实现试看功能，支持VidSts和VidAuth（视频点播推荐使用此方式）两种播放方式。如何配置和使用试看功能，请参见试看视频。

const vidSts: VidSts = new VidSts();

....
let configGen: VidPlayerConfigGen = new VidPlayerConfigGen();
configGen.setPreviewTime(20);//20秒试看
vidSts.setPlayConfig(configGen);//设置给播放源
...

鸿蒙HarmonyOS NEXT播放器SDK通过PlayerConfig提供了设置缓存和延迟的控制接口。示例如下：

let config:PlayerConfig | undefined = player.getConfig();
if (config) {
  //最大延迟。注意：直播有效。当延时比较大时，播放器sdk内部会追帧等，保证播放器的延时在这个范围内。
  config.mMaxDelayTime = 5000;
  // 最大缓冲区时长。单位ms。播放器每次最多加载这么长时间的缓冲数据。
  config.mMaxBufferDuration = 50000;
  //高缓冲时长。单位ms。当网络不好导致加载数据时，如果加载的缓冲时长到达这个值，结束加载状态。
  config.mHighBufferDuration = 3000;
  // 起播缓冲区时长。单位ms。这个时间设置越短，起播越快。也可能会导致播放之后很快就会进入加载状态。
  config.mStartBufferDuration = 500;
  ....//其他设置
  //往前缓存的最大时长。单位ms。默认为0。
  config.mMaxBackwardBufferDurationMs = 0;
  player.setConfig(config);
}

鸿蒙HarmonyOS NEXT播放器SDK支持设置播放器渲染的背景色。接口和用法说明如下：

接口示例

/**
 * 设置视频的背景色
 *
 * @param color  ARGB
 *
 */
/****
 * Set video background color
 * @param color  ARGB
 */
setVideoBackgroundColor: (color: number) => void;

用法说明

//参数为8位16进制数据，8位数据两两为一组，按照顺序分别表示A(alpha 透明度) R(red) G(green) B(blue) 
//例如0x0000ff00，表示绿色
player.setVideoBackgroundColor(0x0000ff00);

vidAuth设置指定播放域名

通过vidAuth方式可以指定vid对应的域名等字段，支持的字段详情请参见GetPlayInfo请求参数。接口及用法说明如下：

接口示例

/**
 * 设置播放参数
 *
 * @param playConfig 播放参数
 */
/****
 * Set playback parameters.
 *
 * @param playConfig The playback parameters.
 */
setPlayerConfig: (playerConfig: VidPlayerConfigGen) => void

用法说明

通过其中的VidPlayerConfigGen接口的addPlayerConfig添加playDomain字段。

const vidAuthSource: VidAuth = new VidAuth();
let configGen: VidPlayerConfigGen = new VidPlayerConfigGen();
//增加playDomain字段，可以添加的字段参考
//https://help.aliyun.com/zh/vod/developer-reference/api-vod-2017-03-21-getplayinfo?spm=a2c4g.11186623.0.0.2bec2e44eqeDgx#api-detail-35
configGen.addPlayerConfigString("playDomain", "com.xxx.xxx");
vidAuthSource.setPlayerConfig(configGen);

player.setVidAuthDataSource(vidAuthSource);

鸿蒙HarmonyOS NEXT播放器SDK提供了本地缓存的功能，能够让用户重复播放视频时，提高起播速度、提高seek速度、减少卡顿，也能达到节省流量的目的。

开启本地缓存

/**
   * 开启本地缓存，开启之后，就会缓存到本地文件中。
   * @param enable true：开启本地缓存。false：关闭。默认关闭。
   * @param maxBufferMemoryKB 设置单个源的最大内存占用大小。单位KB
   * @param localCacheDir 本地缓存的文件目录，绝对路径
   */
  /****
   * Enable local cache. When enabled, it will be cached in local files.
   * @param enable true: enables the local cache. false: disable. This function is disabled by default.
   * @param maxBufferMemoryKB Set the maximum memory size for a single source. Unit is KB
   * @param localCacheDir Directory of files cached locally, absolute path
   */
  static enableLocalCache(enable: boolean, maxBufferMemoryKB: number, localCacheDir: string)


    /**
   *  本地缓存文件自动清理相关的设置
   * @param expireMin 缓存多久过期：单位分钟，默认值30天，过期的缓存不管容量如何，都会在清理时淘汰掉；
   * @param maxCapacityMB 最大缓存容量：单位兆，默认值20GB，在清理时，如果缓存总大小超过此大小，会以cacheItem为粒度，按缓存的最后时间排序，一个一个淘汰掉一些缓存，直到小于等于最大缓存容量；
   * @param freeStorageMB 磁盘最小空余容量：单位兆，默认值0，在清理时，同最大缓存容量，如果当前磁盘容量小于该值，也会按规则一个一个淘汰掉一些缓存，直到freeStorage大于等于该值或者所有缓存都被干掉；
   */
  /****
   * Settings related to automatic cleanup of local cache files
   * @param expireMin How long the cache expires: the unit is minute. The default value is 30 days.
   * @param maxCapacityMB maximum cache capacity: in megabytes. The default value is 20GB. If the total cache size exceeds this size, the cache size is sorted by cacheItem until it is less than or equal to the maximum cache capacity.
   * @param freeStorageMB Minimum free disk capacity: in megabytes (default value: 0). If the current disk capacity is less than this value, the freeStorage will be eliminated one by one until the freeStorage is greater than or equal to this value or all caches are eliminated.
   */
  static setCacheFileClearConfig(expireMin: number, maxCapacityMB: number, freeStorageMB: number)

  /**
   * 设置加载url的hash值回调。如果不设置，SDK使用md5算法。
   */
  setCacheUrlHashCallback(cb: OnGetUrlHashCallback)

开启或关闭单个URL的本地缓存

let config:PlayerConfig | undefined = player.getConfig();
if (config) {
  //是否针对播放的URL开启本地缓存，默认值为true。当AliPlayerGlobalSettings处的本地缓开启时，且同时开启此处的本地缓存，即设置为true，该URL的本地缓存才会生效；若此处设置为false，则关闭该URL的本地缓存。
  config.mEnableLocalCache = true; 
  player.setConfig(config);
}

通过设置数据的最大缓冲区时长可以在播放视频时通过缓存视频数据到内存中，从而提高播放性能和观看体验。当最大缓冲区时长设置过大时，会造成缓冲区对内存的消耗。通过启用大缓存，可以将视频数据缓存到文件中，从而降低内存的占用，进一步提高播放器性能。

当mMaxBufferDuration设置超过50000 ms时，通过开启本地缓存触发大缓存功能自动启用。操作流程如下：

1. 开启全局本地缓存。

   本地缓存功能默认关闭，如需使用，需要手动开启。通过AliPlayerGlobalSettings中的enableLocalCache控制。代码示例请参见本地缓存中的开启本地缓存。

2. 开启URL的本地缓存。

   代码示例请参见本地缓存中的开启或关闭单个URL的本地缓存。

3. 开启大缓存。

   AliPlayerGlobalSettings.enableBufferToLocalCache(true);

鸿蒙HarmonyOS NEXT播放器SDK提供预加载功能，是对本地缓存功能的升级，通过设置视频缓存的内存占用大小，更能提升视频的起播速度。

AliPlayerGlobalSettings.enableNetworkBalance(false);

1. 开启本地缓存功能，详细操作请参见本地缓存。

2. 获取AliMediaLoader实例。

   AliMediaLoader实例为单例，即无论获取多少次，创建的都是同一个实例。

   let loader: MediaLoader = MediaLoader.getInstance();

3. 配置AliMediaLoader。

   配置回调，并开始加载。

   说明

   若player的prepare时刻与mediaLoader.load的调用时刻一致，由于都需要遍历本地文件，则可能导致出现ANR的问题。建议设置为当player在onPrepared回调中时，才开始加载。

   展开查看代码

   export interface OnLoadStatusListener {
     /**
      * 加载出错
      *
      * @param url  视频url
      * @param code 错误码
      * @param msg  错误描述
      */
     /****
      * Load error
      *
      * @param url Video URL
      * @param code Error code
      * @param msg Error description
      */
     onError: (url: string, code:number, msg: string) => void;
   
     /**
      * 加载完成
      *
      * @param url 视频url
      */
     /****
      * Load complete
      *
      * @param url Video URL
      */
     onCompleted: (url: string) => void;
   
     /**
      * 取消加载
      *
      * @param url 视频url
      */
     /****
      * Load canceled
      *
      * @param url Video URL
      */
     onCancel: (url: string) => void;
   }
   
   /**
    * 开始加载文件。异步加载。可以同时加载多个视频文件。
    * @param url - 视频文件地址。
    * @param duration - 加载的时长大小，单位：毫秒。
    */
   mediaLoader.load(url, duration);

4. 可选：删除加载文件。

   可按需删除加载文件，以节省空间。鸿蒙HarmonyOS NEXT播放器SDK不提供删除接口，需要在App删除加载目录下的文件。

HTTPDNS

//打开httpdns
AliPlayerGlobalSettings.enableHttpDns(true);;

HTTP/2

AliPlayerGlobalSettings.setUseHttp2(true);

鸿蒙HarmonyOS NEXT播放器SDK提供了点播服务视频的下载功能，允许用户通过阿里云播放器将视频缓存至本地观看。目前仅提供普通下载方式，安全下载将会在后续版本提供。

• 普通下载

  下载后的视频数据未经过阿里云加密，用户可以用第三方播放器播放。

• 安全下载

  下载后的视频数据经过阿里云加密。第三方播放器无法播放。仅支持使用阿里云的播放器进行播放。

使用说明

• 仅VidSts和VidAuth方式支持视频下载功能。

• 使用播放器的视频下载功能，需要在点播控制台开启并配置下载模式，详细操作请参见离线下载。

• 视频下载支持断点续传。

操作步骤

1. 可选：配置安全下载的加密校验文件。仅安全下载需要配置，普通下载无需配置。

   说明

   请确保配置的加密校验文件与App信息一致，否则会导致视频下载失败。

   如果设置为安全下载方式，则需要将在点播控制台生成的密钥文件配置到播放器SDK中，用于视频下载和播放的解密验证，密钥文件的生成请参见开启安全下载。

   建议在Application中配置一次即可，示例如下：

   PrivateService.initServiceWithBytes(getContext(), "encryptedApp.dat 文件内实际文本字符串") //可以读取encryptedApp.dat文件信息后，将字符串传入接口

2. 创建并设置下载器。

   创建下载器，通过AliDownloaderFactory创建。示例如下：

   ......
   //创建下载器
   let mAliDownloader:AliMediaDownloader = AliDownloaderFactory.create(getApplicationContext());
   //配置下载保存的路径
   mAliDownloader.setSaveDir(getContext().cacheDir);

3. 设置监听事件。

   下载器提供了多个事件监听。示例如下：

   展开查看代码

   //下载准备成功回调.成功后，通过{@linkplain #selectItem(int)} 方法选择需要下载的Track.
   export interface OnPreparedListener {
     onPrepared: (mediaInfo: MediaInfo) => void;
   }
   
   // 进度回调 
   export interface OnProgressListener {
      //下载进度百分比。
     onDownloadingProgress: (percent: number) => void;
     //处理进度百分比
     onProcessingProgress: (percent: number) => void;
   }
   
   // 下载完成消息回调
   export interface OnCompletionListener {
     onCompletion: () => void;
   }
   
   //错误消息回调
   export interface OnErrorListener {
     //下载错误的消息
     onError: (errorInfo: ErrorInfo) => void;
   }

4. 准备下载源。

   通过prepare方法准备下载源。下载源支持VidSts和VidAuth两种方式。示例如下：

   • VidSts

     //创建VidSts
     let aliyunVidSts : VidSts = new VidSts();
     aliyunVidSts.setVid("Vid信息");// 视频ID（VideoId）。
     aliyunVidSts.setAccessKeyId("<yourAccessKeyId>");// STS临时AK对的访问密钥ID，需要调用STS服务的AssumeRole接口生成。
     aliyunVidSts.setAccessKeySecret"<yourAccessKeySecret>");// STS临时AK对的访问密钥，需要调用STS服务的AssumeRole接口生成。
     aliyunVidSts.setSecurityToken("<yourSecurityToken>");// STS安全令牌，需要调用STS服务的AssumeRole接口生成。
     aliyunVidSts.setRegion("接入地域");// 点播服务的接入地域，默认为cn-shanghai。
     //准备下载源
     mAliDownloader.prepare(aliyunVidSts)

   • VidAuth

     //创建VidAuth
     let vidAuth : VidAuth = new VidAuth();
     vidAuth.setVid("Vid信息");// 视频ID（VideoId）。
     vidAuth.setPlayAuth("<yourPlayAuth>");// 播放凭证，需要调用点播服务的GetVideoPlayAuth接口生成。
     vidAuth.setRegion("接入地域");// 本参数已弃用，无需设置region，播放器会自动解析region。
     //准备下载源
     mAliDownloader.prepare(vidAuth);

   说明

   源文件格式与输出的下载文件格式保持一致，不支持更改。

5. 准备成功后，选择下载项并开始下载。

   准备成功后，会回调OnPreparedListener方法。返回的TrackInfo中会包含各视频流的清晰度等信息，请选择一个Track进行下载，示例如下：

   mAliDownloader.setOnPreparedListener({
     onPrepared: (mediaInfo: MediaInfo) => {
       //准备下载项成功
       let trackInfos : TrackInfo[] = mediaInfo.getTrackInfos();
       //比如：下载第一个TrackInfo
       mAliDownloader.selectItem(trackInfos[0].getIndex());
       //开始下载
       mAliDownloader.start();
     }
   });

6. （可选）更新下载源。

   为了防止VidSts和VidAuth过期，您也可以更新下载源的信息后开始下载。示例如下：

   //更新下载源
   mAliDownloader.updateVidStsSource(VidSts);
   //开始下载
   mAliDownloader.start();

7. 下载成功或失败后，释放下载器。

   下载成功后，在onCompletion或者onError回调中调用release释放下载器。示例如下：

   mAliDownloader.stop();
   mAliDownloader.release();

8. 可选：删除下载的文件。

   下载过程中，或者下载完成后，可以删除下载的文件。示例如下：

   //通过对象删除文件
   mAliDownloader.deleteFile();
   //通过静态方法删除，若删除成功则返回0
   AliDownloaderFactory.deleteFile("待删除的下载文件夹路径","视频ID","视频格式","下载的视频索引");

后续操作

下载的视频可以使用阿里云播放器进行播放。具体方法如下：

1. 下载完成后获取视频文件的绝对路径。

   let path: string = mAliDownloader.getFilePath();

2. 通过点播UrlSource方式设置绝对路径进行播放。

   let urlSource: UrlSource = new UrlSource();
   urlSource.setUri(path);//设置下载视频的绝对路径。
   aliPlayer.setUrlDataSource(urlSource);