集成HarmonyOS NEXT播放器SDK

功能清单

当前版本的主要功能如下：

开发调试Demo

获取Demo

环境要求

SDK集成

获取SDK

配置SDK

har包位置如下：

在oh-package.json5中配置依赖：

"dependencies": {
  "premierlibrary": "file:../amdemos-player-ohos-listapp/libs/premierlibrary.har",
}

配置License

1. 填写表单申请License授权。

2. 申请授权成功后，将获取到的License证书文件拷贝到DevEco Studio项目中，建议放到rawfile目录下。

3. 在module.json5文件中添加如下字段。

   • key为com.aliyun.alivc_license.licensekey（全小写），value为LicenseKey的值。

   • key为com.aliyun.alivc_license.licensefile（全小写），value为步骤2中证书文件的放置路径，请根据实际情况填写。

     "metadata": [
       {
         "name": "com.aliyun.alivc_license.licensekey",
         "value": "********"
       },
       {
         "name": "com.aliyun.alivc_license.licensefile",
         "value": "license.crt"
       },
     ]

基础功能

1. 创建播放器。

   public createAliPlayer(context: Context, traceId: string) {
     this.aliPlayer = AliPlayerFactory.createAliPlayer(context, traceId);
   }

   其中context可以用系统函数getContext获取。

   VideoController.createAliPlayer(getContext(), null);

2. 设置监听器。

   VideoController.getPlayer()?.setOnPreparedListener(this.mPrepared);
   VideoController.getPlayer()?.setOnRenderingStartListener(this.mOnFirstFrame);
   VideoController.getPlayer()?.setOnCompletionListener(this.mOnCompletion);

   监听器定义如下。

   private mPrepared: OnPreparedListener = {
     onPrepared: () => {
       let player: UrlPlayer = VideoController.getPlayer() as UrlPlayer;
       log.i(`mPrepared, getDuration: ${CommonUtils.secondToTime(Math.floor(player.getDuration() / 1000))}, getCurrentPosition: ${player.getCurrentPosition()}`
         + `, getBufferedPosition: ${player.getBufferedPosition()}, getVolume: ${player.getVolume()}`);
   
       // 初始化完成的回调 1、存音量，2、存视频时长
       let volume: number = player.getVolume();
       AppStorage.setOrCreate<number>(LOCAL_PROP_KEY_VOLUME, volume * 100);
       AppStorage.setOrCreate<string>(LOCAL_PROP_KEY_DURATION, this.getDurationString(player.getDuration(), player
         .getCurrentPosition()));
       this.mVideoDuration = player.getDuration();
     }
   };
   private mOnCompletion: OnCompletionListener = {
     onCompletion: () => {
       log.i("play complete");
     }
   }
   private mOnFirstFrame: OnRenderingStartListener = {
     onRenderingStart: () => {
       log.i("first frame start")
     }
   }

3. 创建DataSource，当前仅支持URL播放。

   let urlSource: UrlSource = new UrlSource();
   urlSource.setUri(this.videoUrl);
   VideoController.getPlayer()?.setUrlDataSource(urlSource);

4. 在XComponent中设置显示。

   忽略其他实现，总体示例如下：

   XComponent({
     id: '1234567890',
     type: XComponentType.SURFACE,
     libraryname: 'premierlibrary',
     controller: this.xComponentController
   })
     .onLoad(async () => {
       this.xComponentController.setXComponentSurfaceSize({
         surfaceWidth: 1080,
         surfaceHeight: 200
       });
   
       VideoController.getPlayer()?.setSurfaceId('1234567890');
   
     })
     .width('100%')
     .height(200)

   需要完成的是：

   1. 挂载播放器So。

        libraryname: 'premierlibrary',

   2. 在XComponent的onLoad实现中，将XComponentId与播放器关联。

       VideoController.getPlayer()?.setSurfaceId('1234567890');

      重要

      这里的1234567890为XComponent的id，可以手动设置成不同的id。建议对于不同的XComponent，设置不同的id，避免因为重复导致出现问题。

5. 可选：开启自动播放，默认为关闭状态。

   VideoController.getPlayer()?.setAutoPlay(true);

6. 准备播放，调用prepare()开始读取并解析数据。

   VideoController.getPlayer()?.prepare();

7. 开始播放。通过调用start方法开始播放视频。若开启自动播放，数据解析完成后将开始自动播放视频。

   VideoController.getPlayer()?.start();

API参考

对于普通播放器，以IPlayer提供的接口为准，IPlayer文件可以从har包中读取到。

当前IPlayer代码如下：

import { ErrorInfo } from './bean/ErrorInfo';
import { InfoBean } from './bean/InfoBean';
import { PlayerConfig } from './nativeclass/PlayerConfig';

/**
 * 未知状态
 */
/****
 * Unknown status.
 */
export const unKnow: number = -1;

/**
 * 空状态。刚创建出来的状态。
 */
/****
 * Blank. The player enters this state after it is created.
 */
export const idle: number = 0;

/**
 * 初始化了的状态，设置播放源之后的状态
 */
/****
 * Initialized. The player enters this state after a media source is specified for the player.
 */
export const initalized: number = 1;

/**
 * 准备成功的状态
 */
/****
 * Prepared.
 */
export const prepared: number = 2;

/**
 * 正在播放的状态
 */
/****
 * The player is playing video or audio.
 */
export const started: number = 3;

/**
 * 播放已暂停的状态
 */
/****
 * The player is paused.
 */
export const paused: number = 4;

/**
 * 播放已停止的状态
 */
/****
 * The player is stopped.
 */
export const stopped: number = 5;

/**
 * 播放完成状态
 */
/****
 * The player has completed playing the video or audio.
 */
export const completion: number = 6;

/**
 * 出错状态
 */
/****
 * The player has an error.
 */
export const error: number = 7;

export interface IPlayer {
  /**
   * 开始播放。
   */
  /****
   * Start the player.
   */
  start: () => void;

  /**
   * 暂停播放
   */
  /****
   * Pause the player.
   */
  pause: () => void;

  /**
   * 停止播放
   */
  /****
   * Stop the player.
   */
  stop: () => void;

  /**
   * 设置自动播放。如果是自动播放，则接受不到{@link OnPreparedListener}回调。
   *
   * @param on true：是。默认否。
   */
  /****
   * Enable autoplay. If autoplay is enabled, then the {@link OnPreparedListener} callback is not returned.
   *
   * @param on Value true indicates that autoplay is enabled. Default: disabled.
   */
  setAutoPlay: (isAutoPlay: boolean) => void;

  /**
   * 准备。成功结果通过{@link OnPreparedListener}回调，或者失败{@link OnErrorListener}
   */
  /****
   * Prepare the player. Call {@link OnPreparedListener} to return success messages. Call {@link OnErrorListener} to return error messages.
   */
  prepare: () => void;

  /**
   * 设置surfaceId，将播放器的显示surface与XComponent绑定。不同的XComponent的XComponentId应不重复
   *
   * @param surfaceId：实际上是XComponentId。
   */
  /****
   * Set the surfaceId to bind the player's display surface with XComponent. The XComponent id ofSet the surfaceId to bind the player's display surface with XComponent. The XComponent id of different XComponents should not be duplicated.
   *
   * @param surfaceId：it's XComponentId actually。
   */
  setSurfaceId: (surfaceId: string) => void;

  /**
   * 设置倍数播放。
   *
   * @param speed 范围[0.5,5]
   */
  /****
   * Set the playback speed.
   *
   * @param speed Valid values: [0.5,5].
   */
  setSpeed: (speed: number) => void;

  /**
   * 设置音量（非系统音量），范围0.0~2.0，当音量大于1.0时，可能出现噪音，不推荐使用。
   *
   * @param gain 范围[0,1]
   */
  /****
   * Set the volume of the player(Not system volume). The range is 0.0~2.0，it maybe lead to noise if set volume more then 1.0, not recommended.
   *
   * @param gain Valid values: [0,1].
   */
  setVolume: (volume: number) => void;

  /**
   * 获取音量。
   *
   * @return 范围[0, 1]
   */
  /****
   * Query the volume of the player.
   *
   * @return Valid values: [0, 1].
   */
  getVolume: () => number;

  //position is based on the unit of getDuration
  /**
   * 跳转到。不精准。
   *
   * @param position 位置。单位毫秒。
   */
  /****
   * Specify a position for inaccurate seeking. Unit: millisecond.
   *
   * @param position The specified position.
   */
  seekTo: (position: number, mode: number) => void;

  /**
   * 获取总时长。
   *
   * @return 总时长。单位ms。
   */
  /****
   * Query the total length of the stream.
   *
   * @return The total length of the stream. Unit: milliseconds.
   */
  getDuration: () => number;

  /**
   * 获取当前播放位置。
   *
   * @return 播放位置。单位ms。
   */
  /****
   * Query the current playback position.
   *
   * @return The current playback position. Unit: milliseconds.
   */
  getCurrentPosition: () => number;

  /**
   * 获取缓冲进度位置。注意：与{@link OnLoadingStatusListener}的区别。
   *
   * @return 缓冲进度位置。单位ms。
   */
  /****
   * Query the current buffer progress. Note: Pay close attention to the difference between this method and {@link OnLoadingStatusListener}.
   *
   * @return The current buffer progress. Unit: milliseconds.
   */
  getBufferedPosition: () => number;

  /**
   * 是否启用硬解码
   *
   * @param enable true:启用。false:关闭。
   */
  /****
   * Enable or disable hardware decoding.
   *
   * @param enable Set to true to enable hardware decoding and set to false to disable hardware decoding.
   */
  enableHardwareDecoder: (enabled: boolean) => void;

  /**
   * 释放。
   */
  /****
   * Release.
   */
  release: () => void;

  /**
   * 设置静音
   *
   * @param on true:静音。默认false。
   */
  /****
   * Mute the player.
   *
   * @param on Set to true to mute the player. Default: false.
   */
  setMute: (mute: boolean) => void;

  /**
   * 是否静音
   *
   * @return true:静音。默认false。
   */
  /****
   * Query whether the player is muted.
   *
   * @return Value true indicates that the player is muted. Default: false.
   */
  isMuted: () => boolean;

  /**
   * 设置画面缩放模式
   *
   * @param scaleMode 缩放模式。默认{@link ScaleMode#SCALE_TO_FILL}. 见{@link ScaleMode}。
   */
  /****
   * Set a zoom mode.
   *
   * @param scaleMode The specified zoom mode. Default: {@link ScaleMode#SCALE_TO_FILL}. See {@link ScaleMode}.
   */
  setScaleMode: (mode: ScaleMode) => void;

  /**
   * 获取画面缩放模式
   *
   * @return 缩放模式。默认{@link ScaleMode#SCALE_TO_FILL}.
   */
  /****
   * Query the current zoom mode.
   *
   * @return The current zoom mode. Default: {@link ScaleMode#SCALE_TO_FILL}.
   */
  getScaleMode: () => ScaleMode;

  /**
   * 设置循环播放。如果本地有了缓存，那么下次循环播放则播放本地文件。
   *
   * @param on true：开启循环播放。默认关闭。
   */
  /****
   * Enable loop playback. If the media file is already downloaded to the local host, then the downloaded media file will be used for loop playback.
   *
   * @param on true：Enable loop playback. Default: disabled.
   */
  setLoop: (on: boolean) => void;

  /**
   * 是否循环播放
   *
   * @return true：开启了循环播放。默认关闭。
   */
  /****
   * Query whether loop playback is enabled.
   *
   * @return Value true indicates that loop playback is enabled. Default: disabled.
   */
  isLoop: () => boolean;

  /**
   * 获取视频宽度
   *
   * @return 视频宽度
   */
  /****
   * Query the width of the video.
   *
   * @return The width of the video.
   */
  getVideoWidth: () => number;

  /**
   * 获取视频高度
   *
   * @return 视频高度
   */
  /****
   * Query the height of the video.
   *
   * @return The height of the video.
   */
  getVideoHeight: () => number;

  /**
   * 获取视频旋转角度
   *
   * @return 视频旋转角度
   */
  /****
   * Query the rotate angle of the video.
   *
   * @return The rotate angle of the video.
   */
  getVideoRotation: () => number;

  /**
   * 重新加载。比如网络超时时，可以重新加载。
   */
  /****
   * Reload. Call this method when the network connection times out.
   */
  reload: () => void;

  /**
   * 设置画面旋转模式
   *
   * @param rotateMode 旋转模式。见{@link RotateMode}
   */
  /****
   * Set a rotate mode.
   *
   * @param rotateMode The specified rotate mode. See {@link RotateMode}.
   */
  setRotateMode: (mode: RotateMode) => void;

  /**
   * 获取画面旋转模式
   *
   * @return 旋转模式。见{@link RotateMode}
   */
  /****
   * Query the current rotate mode.
   *
   * @return The current rotate mode. See {@link RotateMode}.
   */
  getRotateMode: () => RotateMode;

  /**
   * 设置镜像模式
   *
   * @param mirrorMode 镜像模式。 见{@link MirrorMode}。
   */
  /****
   * Set a mirroring mode
   *
   * @param mirrorMode The specified mirroring mode. See {@link MirrorMode}.
   */
  setMirrorMode: (mode: MirrorMode) => void;

  /**
   * 获取当前镜像模式。
   *
   * @return 镜像模式。 见{@link MirrorMode}。
   */
  /****
   * Query the current mirroring mode.
   *
   * @return The current mirroring mode. See {@link MirrorMode}.
   */
  getMirrorMode: () => MirrorMode;

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

  /**
   * 获取倍数播放值。
   *
   * @return 倍数播放值。范围[0.5,5]
   */
  /****
   * Query the playback speed.
   *
   * @return The playback speed. Valid values: [0.5,2].
   */
  getSpeed: () => number;

  /**
   * 是否自动播放。
   *
   * @return true：是。默认否。
   */
  /****
   * Query whether autoplay is enabled.
   *
   * @return Value true indicates that autoplay is enabled. Default: disabled.
   */
  isAutoPlay: () => boolean;
  /**
   * 设置播放器配置。
   *
   * @param config 播放器配置。见{@link PlayerConfig}
   */
  /****
   * Modify the player configuration.
   *
   * @param config The configuration of the player. See {@link PlayerConfig}.
   */
  setConfig: (config:PlayerConfig) => void;

  /**
   * 获取播放器配置
   *
   * @return 播放器配置
   */
  /****
   * Query the player configuration.
   *
   * @return The player configuration.
   */
  getConfig: () => PlayerConfig | undefined;

  getNativeContextAddr: () => number;

  /**
   * 设置准备成功通知。如果失败，则会通知{@link OnErrorListener}。
   *
   * @param l 准备成功通知
   */
  /****
   * Set a preparation success callback. If the preparation failed, the {@link OnErrorListener} is triggered.
   *
   * @param l Preparation success notification.
   */
  setOnPreparedListener: (l: OnPreparedListener) => void;

  /**
   * 设置渲染开始通知。可以监听首帧显示事件等，用于隐藏封面等功能。
   *
   * @param l 渲染开始通知。
   */
  /****
   * Set a rendering start callback. You can use this callback to listen to first frame display events and hide the album cover.
   *
   * @param l Rendering start notification.
   */
  setOnRenderingStartListener: (l: OnRenderingStartListener) => void;

  /**
   * 设置播放器状态变化通知
   *
   * @param l 播放器状态变化通知
   */
  /****
   * Set a player status update callback.
   *
   * @param l Player status update notification.
   */
  setOnStateChangedListener: (l: OnStateChangedListener) => void;

  /**
   * 设置播放完成通知.注意：循环播放不会发出此通知。
   *
   * @param l 播放完成通知.
   */
  /****
   * Set a playback completion callback. Note: No notification is sent if loop playback is enabled.
   *
   * @param l Playback completion notification.
   */
  setOnCompletionListener: (l: OnCompletionListener) => void;

  /**
   * 设置加载状态通知。
   *
   * @param l 加载状态通知
   */
  /****
   * Set a loading status callback.
   *
   * @param l Loading status notification.
   */
  setOnLoadingStatusListener: (l: OnLoadingStatusListener) => void;

  /**
   * 设置出错通知
   *
   * @param l 出错通知
   */
  /****
   * Set an error callback.
   *
   * @param l Error message.
   */
  setOnErrorListener: (l: OnErrorListener) => void;

  /**
   * 设置信息监听
   *
   * @param l 信息监听
   */
  /****
   * Set a notification callback.
   *
   * @param l The notification.
   */
  setOnInfoListener: (l: OnInfoListener) => void;

  /**
   * 设置视频宽高变化通知
   *
   * @param l 视频宽高变化通知
   */
  /****
   * Set a video size change callback.
   *
   * @param l Video size change notification.
   */
  setOnVideoSizeChangedListener: (l: OnVideoSizeChangedListener) => void;

  /**
   * 设置拖动完成通知
   *
   * @param l 拖动完成通知
   */
  /****
   * Set a seeking completion callback.
   *
   * @param l Seeking completion notification.
   */
  setOnSeekCompleteListener: (l: OnSeekCompleteListener) => void;

  /**
   * 设置字幕显示通知
   *
   * @param l 字幕显示通知
   */
  /****
   * Set a subtitle display callback.
   *
   * @param l Subtitle display notification.
   */
  setOnSubtitleDisplayListener: (l: OnSubtitleDisplayListener) => void;

  /**
   * 设置视频渲染回调
   * @param l 视频渲染回调。见{@linkplain OnVideoRenderedListener}
   */
  /****
   * set the video render callback
   * @param l video render callback. See {@linkplain OnVideoRenderedListener}
   */
  setOnVideoRenderedListener: (l: OnVideoRenderedListener) => void;
}

/**
 * 准备成功通知
 */
/****
 * Preparation success callback.
 */
export interface OnPreparedListener {
  /**
   * 准备成功
   */
  /****
   * Preparation is complete.
   */
  onPrepared: () => void;
}

/**
 * 信息通知
 */
/****
 * Notification callback.
 */
export interface OnInfoListener {
  /**
   * 信息
   *
   * @param infoBean 信息对象。见{@linkplain InfoBean}
   */
  /****
   * Indicate a notification.
   *
   * @param infoBean The notification object. See {@linkplain InfoBean}.
   */
  onInfo: (infoBean: InfoBean) => void;
}

/**
 * 渲染开始通知
 */
/****
 * Rendering start callback.
 */
export interface OnRenderingStartListener {
  /**
   * 渲染开始。
   */
  /****
   * Rendering starts.
   */
  onRenderingStart: () => void;
}

/**
 * 播放器状态变化通知
 */
/****
 * Player status update callback.
 */
export interface OnStateChangedListener {
  /**
   * 状态变化
   *
   * @param newState 新状态
   */
  /****
   * The player status is updated.
   *
   * @param newState The updated status.
   */
  onStateChanged: (newState: number) => void;
}

/**
 * 播放完成通知.
 */
/****
 * Playback completion callback.
 */
export interface OnCompletionListener {
  /**
   * 播放完成
   */
  /****
   * The player has completed playing the video or audio.
   */
  onCompletion: () => void;
}

/**
 * 加载状态通知
 */
/****
 * Loading status callback.
 */
export interface OnLoadingStatusListener {
  /**
   * 开始加载。
   */
  /****
   * Start loading.
   */
  onLoadingBegin: () => void;

  /**
   * 加载进度
   *
   * @param percent  百分比，[0,100]
   * @param netSpeed 当前网速。kbps
   */
  /****
   * Loading progress.
   *
   * @param percent  The loading progress in percentage. Valid values: [0,100].
   * @param netSpeed The current bandwidth. Unit: kbit/s.
   */
  onLoadingProgress: (percent: number, netSpeed: number) => void;

  /**
   * 加载结束
   */
  /****
   * Loading is complete.
   */
  onLoadingEnd: () => void;
}

/**
 * 出错通知
 */
/****
 * Error callback.
 */
export interface OnErrorListener {
  /**
   * 出错
   *
   * @param errorInfo 错误信息
   */
  /****
   * An error occurs.
   *
   * @param errorInfo Error message.
   */
  onError: (errorInfo: ErrorInfo) => void;
}

/**
 * 视频宽高变化通知
 */
/****
 * Video size change callback.
 */
export interface OnVideoSizeChangedListener {
  /**
   * 视频宽高变化
   *
   * @param width  宽
   * @param height 高
   */
  /****
   * Video size changes.
   *
   * @param width  Width.
   * @param height Height.
   */
  onVideoSizeChanged: (width: number, height: number) => void;
}

/**
 * 拖动完成通知
 */
/****
 * Seeking completion callback.
 */
export interface OnSeekCompleteListener {
  /**
   * 拖动完成
   */
  /****
   * Seeking is complete.
   */
  onSeekComplete: () => void;
}

/**
 * 字幕显示通知
 */
/****
 * Subtitle display callback.
 */
export interface OnSubtitleDisplayListener {

  /**
   * 外挂字幕被添加
   * @param trackIndex 流id
   * @param url 字幕url
   */
  /****
   * External subtitles have been added
   * @param trackIndex stream id
   * @param url subtitle url
   */
  onSubtitleExtAdded: (trackIndex: number, url: string) => void;

  /**
   * 显示字幕
   *
   * @param tackIndex 流id
   * @param id   索引
   * @param data 内容
   */
  /****
   * Show subtitles.
   *
   * @param id   Index.
   * @param data Content.
   */
  onSubtitleShow: (trackIndex: number, id: number, data: string) => void;

  /**
   * 隐藏字幕
   * @param trackIndex 流id
   * @param id 字幕id
   */
  /****
   * Hide subtitles.
   *
   * @param trackIndex track index
   * @param id subtitle Index.
   */
  onSubtitleHide: (trackIndex: number, id: number) => void;

  /**
   * 字幕头信息
   * @param trackIndex 流id
   * @param header 头信息
   */
  /****
   * Subtitle header.
   *
   * @param trackIndex track index
   * @param header subtitle header.
   */
  onSubtitleHeader: (trackIndex: number, header: string) => void;
}

/**
 * 视频渲染回调
 */
/****
 * video render callback
 */
export interface OnVideoRenderedListener {
  /**
   * 视频帧被渲染
   * @param timeMs 渲染的时间点
   * @param pts 渲染的pts
   */
  /****
   * video frames are rendered
   * @param timeMs render point in time
   * @param pts rendered pts
   */
  onVideoRendered: (timeMs: number, pts: number) => void;
}

export enum IPResolveType {
  /**
   * 任意类型
   */
  /****
   * default
   */
  IpResolveWhatEver,
  /**
   * 只使用ipV4
   */
  /****
   * only ip v4
   */
  IpResolveV4,
  /**
   * 只使用ipV6
   */
  /***
   * only ip v6
   */
  IpResolveV6
}

export enum ScaleMode {
  /**
   * 宽高比适应
   */
  /****
   * Auto zoom to fit.
   */
  SCALE_ASPECT_FIT = 0,
  /**
   * 宽高比填充
   */
  /****
   * Fill to fit.
   */
  SCALE_ASPECT_FILL,
  /**
   * 拉伸填充
   */
  /****
   * Stretch to fit.
   */
  SCALE_TO_FILL
}

export enum MirrorMode {
  /**
   * 无镜像
   */
  /****
   * Disable mirroring.
   */
  MIRROR_MODE_NONE = 0,
  /**
   * 水平镜像
   */
  /****
   * Horizontal mirroring.
   */
  MIRROR_MODE_HORIZONTAL,
  /**
   * 垂直镜像
   */
  /****
   * Vertical mirroring.
   */
  MIRROR_MODE_VERTICAL,
}

export enum RotateMode {
  /**
   * 顺时针旋转0度
   */
  /****
   * Do not rotate.
   */
  ROTATE_0 = 0,
  /**
   * 顺时针旋转90度
   */
  /****
   * Rotate 90 degree clockwise.
   */
  ROTATE_90 = 90,
  /**
   * 顺时针旋转180度
   */
  /****
   * Rotate 180 degree clockwise.
   */
  ROTATE_180 = 180,
  /**
   * 顺时针旋转270度
   */
  /****
   * Rotate 270 degree clockwise.
   */
  ROTATE_270 = 270,
}

已知问题

1. 切换前后台可能导致播放中断，我们正在处理这个问题。

2. 开启“tunnelMode”能有效降低CPU占用消耗，但仍存在若干已知问题，我们正在处理这个问题。

3. Huawei Mate 60 Pro（ALN-AL00）可能存在一些兼容性问题。