一、简介

OpenHarmony 5.0 Release版本标准系统能力持续完善。AVPlayer播放器模块新增或增强了很多特性，媒体引擎发生重大改变。本文将基于 OpenHarmony 5.0.1 Release 版本（API 13）的AVPlayer模块，与 OpenHarmony 4.0 Release 版本（API 10）展开细致对比，深入阐述其中新增的特性与接口 。

二、注意事项

本文中的新特性跨API 11、12、13三个版本，新增接口如果是从API 12开始引入将不会有明显标识，如果是从API11或API13开始引入会显式标识；
每一个on（监听事件的接口）都有对应的off（取消监听事件的接口）；
枚举类型中之前版本有的枚举值未列明，用省略号标识。

三、ArkTS API新特性

1、DRM

概述

• 支持DRM 安全和非安全通路
• 支持获取加密媒体内容的DRM信息
• 支持设置DRM解密配置

DRM相关API是从4.1 Release版本（API 11）引入的，需要依赖DRM模块，关于drm模块的示例具体可见 js-apis-drm.md。

mediaKeySystemInfoUpdate 事件

on(type: 'mediaKeySystemInfoUpdate', callback: Callback<Array<drm.MediaKeySystemInfo>>): void

interface MediaKeySystemInfo {
  uuid: string;      // DRM内容保护系统的唯一标识
  pssh: Uint8Array;  // DRM内容保护系统专用头（Protection System Specific Header）
}

监听mediaKeySystemInfoUpdate事件，事件回调方法会上报MediaKeySystemInfo数组

off(type: 'mediaKeySystemInfoUpdate', callback?: Callback<Array<drm.MediaKeySystemInfo>>): void;

取消监听mediaKeySystemInfoUpdate事件。

setDecryptionConfig

setDecryptionConfig(mediaKeySession: drm.MediaKeySession, secureVideoPath: boolean): void

设置解密配置。当收到mediaKeySystemInfoUpdate事件时，需根据事件上报的信息创建相关配置并设置解密配置，否则无法播放。第二个参数安全视频通路，true表示选择安全视频通路，false表示选择非安全视频通路。示例如下

import { drm } from '@kit.DrmKit';

// 创建MediaKeySystem系统
let keySystem:drm.MediaKeySystem = drm.createMediaKeySystem('com.clearplay.drm');
// 创建MediaKeySession解密会话
let keySession:drm.MediaKeySession = keySystem.createMediaKeySession(drm.ContentProtectionLevel.CONTENT_PROTECTION_LEVEL_SW_CRYPTO);
// 生成许可证请求、设置许可证响应等
// 安全视频通路标志
let secureVideoPath:boolean = false;
// 设置解密配置
avPlayer.setDecryptionConfig(keySession, secureVideoPath);

getMediaKeySystemInfos

getMediaKeySystemInfos(): Array<drm.MediaKeySystemInfo>

获取当前播放的媒体资源的MediaKeySystemInfo。需要在mediaKeySystemInfoUpdate事件触发成功后才能调用。

2、播放轨道

概述

• 获取已选择的音视频轨道索引
• 选择指定轨道播放
• 取消选择轨道
• 注册轨道变更和轨道信息更新事件
• 获取更详细的轨道描述信息

getSelectedTracks

getSelectedTracks(): Promise<Array<number>>

获取已选择的音视频轨道索引，可以在prepared/playing/paused状态调用。通过Promise获取已选择音视频轨道索引数组返回值。

selectTrack

selectTrack(index: number, mode?: SwitchMode): Promise<void>

enum SwitchMode {
    SMOOTH = 0,     // 切换后视频平滑播放，该模式切换存在延迟，不会立即生效
    SEGMENT = 1,    // 切换后从当前分片开始位置播放，该模式立即切换，可能会有重复播放
    CLOSEST = 2,    // 从距离当前播放时间点最近的帧开始播放，该模式立即切换，切换后可能会卡住3到5s，然后恢复播放
}

播放多音视频轨道资源时，选择指定轨道播放。
参数index是音视频轨道索引，参数mode是切换视频轨道模式，默认为SMOOTH模式，仅在DASH协议网络流视频轨道切换时生效，其他场景暂不支持

deselectTrack

deselectTrack(index: number): Promise<void>

播放多音轨视频时取消指定音视频轨道播放，会恢复到默认的播放轨道。

trackChange事件

on(type: 'trackChange', callback: OnTrackChangeHandler): void
type OnTrackChangeHandler = (index: number, isSelected: boolean) => void;     // index是当前选中的track索引，isSelected是当前索引的选中状态

注册获取轨道变更的事件，当播放轨道变更时，会通过注册的回调方法通知用户。用户调用selectTrack和deselectTrack时都会触发该回调。

trackInfoUpdate事件

on(type: 'trackInfoUpdate', callback: Callback<Array<MediaDescription>>): void

订阅获取轨道信息更新的事件，当播放轨道信息更新时，会通过订阅的回调方法通知用户

MediaDescriptionKey

通过getTrackDescription获取音视频轨道信息，新增以下描述信息

 enum MediaDescriptionKey {
    ....
    MD_KEY_AUD_SAMPLE_DEPTH = 'sample_depth',    // 音频采样位宽，number类型，单位为bit
    MD_KEY_LANGUAGE = 'language',                // 字幕语言，string类型
    MD_KEY_TRACK_NAME = 'track_name',            // 轨道名称，string类型
    MD_KEY_HDR_TYPE = 'hdr_type',                // 视频hdr类型，string类型
  }

3、播放控制

概述

• 支持设置流媒体媒体源和自定义Http Header
• 支持设置播放策略
• 支持设置播放区间
• 支持音频静音播放
• 支持精准seek
• 支持更多的播放倍速
• 支持播放视频过程更换输出Surface

MediaSource

createMediaSourceWithUrl(url: string, headers?: Record<string, string>): MediaSource

media.createMediaSourceWithUrl 创建流媒体预下载媒体来源实例的方法。
参数url是流媒体预下载媒体源，支持的流媒体格式有hls、http-flv、dash、https，也支持设置本地m3u8的fd路径。
参数headers是媒体源自定义的Http Header，如User-Agent等，非必需参数。

setMediaSource(src:MediaSource, strategy?: PlaybackStrategy): Promise<void>

设置流媒体预下载资源，下载url对应的流媒体数据，并暂存在内存中。
参数strategy是播放策略， 非必需参数

setPlaybackStrategy

setPlaybackStrategy(strategy: PlaybackStrategy): Promise<void>

设置播放策略，只能在initialized状态下调用。支持的播放策略如下：

interface PlaybackStrategy {
    preferredWidth?: number;               // 首选宽度，int类型，如1280
    preferredHeight?: number;              // 首选宽度，int类型，如720
    preferredBufferDuration?: number;      // 首选缓冲持续时间，单位秒，取值范围1-20
    preferredHdr?: boolean;                // rue是hdr，false非hdr，默认非hdr
    mutedMediaType?: MediaType;            // 静音播放的媒体类型，仅支持设置 MediaType.MEDIA_TYPE_AUD。
    preferredAudioLanguage?: string;       // API 13引入。首选音轨语言。dash场景下应用可按需设置。非dash场景暂不支持，建议缺省。
    preferredSubtitleLanguage?: string;    // API 13引入。首选字幕语言。dash场景下应用可按需设置。非dash场景暂不支持，建议缺省。
 }

setPlaybackRange

setPlaybackRange(startTimeMs: number, endTimeMs: number, mode?: SeekMode) : Promise<void>

设置播放区间，并通过指定的SeekMode跳转到区间开始位置。设置之后，只播放码流设定区间内的内容。可在initialized/prepared/paused/stopped/completed状态下使用。
该接口为系统接口。
参数startTimeMs：区间开始位置，单位ms，取值[0, duration)。可以设置-1值，系统将会从0位置开始播放，必需参数。
参数endTimeMs：区间结束位置，单位ms，取值(startTimeMs, duration]。可以设置-1值，系统将会播放到资源末尾，必需参数。
参数mode：目前支持SeekMode有SEEK_PREV_SYNC和SeekMode.SEEK_CLOSEST，默认值是SEEK_PREV_SYNC，非必需参数。

setMediaMuted

setMediaMuted(mediaType: MediaType, muted: boolean ): Promise<void>

设置音频静音/取消音频静音。只能在prepared/playing/paused/completed状态下调用，仅支持设置mediaType为音频格式。

SeekMode

seek(timeMs: number, mode?:SeekMode): void
enum SeekMode {
    ...
    SEEK_CLOSEST = 2,     // 表示跳转到距离指定时间点最近的帧，精准seek
    SEEK_CONTINUOUS = 3,  // API 13引入，Seek in continuous mode
}

PlaybackSpeed

setSpeed(speed: PlaybackSpeed): void;
enum PlaybackSpeed {
   ...
    SPEED_FORWARD_0_50_X = 5,
    SPEED_FORWARD_1_50_X = 6,
    SPEED_FORWARD_3_00_X = 7,     // API13引入
    SPEED_FORWARD_0_25_X = 8,
    SPEED_FORWARD_0_125_X = 9,
  }

surfaceId

视频窗口ID，默认无窗口。
5.0以前的版本只支持在initialized状态下设置。
5.0版本后支持在prepared/playing/paused/completed/stopped状态下重新设置，重新设置时需确保已经在initialized状态下进行设置，否则重新设置失败，重新设置后视频播放在新的窗口渲染。
播放视频过程动态切换surface。

下一篇传送门：OpenHarmony5.0 AVPlayer新特性开发指导（二）