1# Interface (AVPlayer) 2<!--Kit: Media Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @xushubo; @chennotfound--> 5<!--Designer: @dongyu_dy--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> - 本Interface首批接口从API version 9开始支持。 13 14播放管理类，用于管理和播放媒体资源。在调用AVPlayer的方法前，需要先通过[createAVPlayer()](arkts-apis-media-f.md#mediacreateavplayer9)构建一个AVPlayer实例。 15 16应用需要按照实际业务需求合理使用AVPlayer对象，按需创建并及时释放，避免持有过多AVPlayer实例导致内存消耗过大，否则在一定情况下可能导致系统查杀应用。 17 18Audio/Video播放demo可参考：[音频播放开发指导](../../media/media/using-avplayer-for-playback.md)、[视频播放开发指导](../../media/media/video-playback.md)。 19 20> **说明：** 21> 22> 在使用AVPlayer实例的方法时，建议开发者注册相关回调，主动获取当前状态变化。 23> 24> - [on('stateChange')](#onstatechange9)：监听播放状态机AVPlayerState切换。 25> - [on('error')](#onerror9)：监听错误事件。 26 27## 导入模块 28 29```ts 30import { media } from '@kit.MediaKit'; 31``` 32 33## 属性 34 35**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 36 37| 名称 | 类型 | 只读 | 可选 | 说明 | 38| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 39| url<sup>9+</sup> | string | 否 | 是 | 媒体URL，只允许在**idle**状态下设置。<br/>支持的视频格式(mp4、mpeg-ts、mkv)。<br>支持的音频格式(m4a、aac、mp3、ogg、wav、flac、amr、ape)。<br/>**支持路径示例**：<br>1. fd类型播放：fd://xx。<br><br>2. http网络播放: http\://xx。<br/>3. https网络播放: https\://xx。<br/>4. hls网络播放路径：http\://xx或者https\://xx。<br>**说明：**<br>- 设置网络播放路径，需[声明权限](../../security/AccessToken/declare-permissions.md)：[ohos.permission.INTERNET](../../security/AccessToken/permissions-for-all.md#ohospermissioninternet)，相关错误码: [201](../errorcode-universal.md)。<br>- 从API version 11开始不支持webm。<br> - 将资源句柄（fd）传递给 AVPlayer 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致媒体播放器数据获取异常。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 40| fdSrc<sup>9+</sup> | [AVFileDescriptor](arkts-apis-media-i.md#avfiledescriptor9) | 否 | 是 | 媒体文件描述，只允许在**idle**状态下设置。<br/>使用场景：应用中的媒体资源被连续存储在同一个文件中。<br/>支持的视频格式(mp4、mpeg-ts、mkv)。<br>支持的音频格式(m4a、aac、mp3、ogg、wav、flac、amr、ape)。<br/>**使用示例**：<br/>假设一个连续存储的媒体文件: <br/>视频1(地址偏移:0，字节长度:100)；<br/>视频2(地址偏移:101，字节长度:50)；<br/>视频3(地址偏移:151，字节长度:150)；<br/>1. 播放视频1：AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。<br/>2. 播放视频2：AVFileDescriptor { fd = 资源句柄; offset = 101; length = 50; }。<br/>3. 播放视频3：AVFileDescriptor { fd = 资源句柄; offset = 151; length = 150; }。<br/>假设是一个独立的媒体文件: 请使用src=fd://xx。<br>**说明：**<br>从API version 11开始不支持webm。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 41| dataSrc<sup>10+</sup> | [AVDataSrcDescriptor](arkts-apis-media-i.md#avdatasrcdescriptor10) | 否 | 是 | 流式媒体资源描述，只允许在**idle**状态下设置。<br/>使用场景：应用播放从远端下载到本地的文件，在应用未下载完整音视频资源时，提前播放已获取的资源文件。<br/>支持的视频格式(mp4、mpeg-ts、mkv)。<br>支持的音频格式(m4a、aac、mp3、ogg、wav、flac、amr、ape)。<br/>**使用示例**：<br/>假设用户正在从远端服务器获取音视频媒体文件，希望下载到本地的同时播放已经下载好的部分: <br/>1.用户需要获取媒体文件的总大小size（单位为字节），获取不到时设置为-1。<br/>2.用户需要实现回调函数func用于填写数据，如果size = -1，则func形式为：func(buffer: ArrayBuffer, length: number)，此时播放器只会按照顺序获取数据；否则func形式为：func(buffer: ArrayBuffer, length: number, pos: number)，播放器会按需跳转并获取数据。<br/>3.用户设置AVDataSrcDescriptor {fileSize = size, callback = func}。<br/>**注意事项**：<br/>如果播放的是mp4/m4a格式用户需要保证moov字段（媒体信息字段）在mdat字段（媒体数据字段）之前，或者moov之前的字段小于10M，否则会导致解析失败无法播放。<br>**说明：**<br>从API version 11开始不支持webm。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 42| surfaceId<sup>9+</sup> | string | 否 | 是 | 视频窗口ID，默认无窗口。<br/>支持在**initialized**状态下设置。<br/>支持在**prepared**/**playing**/**paused**/**completed**/**stopped**状态下重新设置，重新设置时确保已经在**initialized**状态下进行设置，否则重新设置失败，重新设置后视频播放在新的窗口渲染。<br/>使用场景：视频播放的窗口渲染，纯音频播放不用设置。<br/>**使用示例**：<br/>[通过XComponent创建surfaceId](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid9)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 43| loop<sup>9+</sup> | boolean | 否 | 否 | 视频循环播放属性，默认'false'，设置为'true'表示循环播放，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。<br/>直播场景不支持loop设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 44| videoScaleType<sup>9+</sup> | [VideoScaleType](arkts-apis-media-e.md#videoscaletype9) | 否 | 是 | 视频缩放模式，默认VIDEO_SCALE_TYPE_FIT，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 45| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](../apis-audio-kit/arkts-apis-audio-e.md#interruptmode9) | 否 | 是 | 音频焦点模型，默认SHARE_MODE，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。<br/>在第一次调用[play()](#play9)之前设置， 以便此后中断模式生效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 46| audioRendererInfo<sup>10+</sup> | [audio.AudioRendererInfo](../apis-audio-kit/arkts-apis-audio-i.md#audiorendererinfo8) | 否 | 是 | 设置音频渲染信息。若媒体源包含视频，则usage默认值为STREAM_USAGE_MOVIE，否则usage默认值为STREAM_USAGE_MUSIC。rendererFlags默认值为0。若默认usage不满足需求，则须主动配置[audio.AudioRendererInfo](../apis-audio-kit/arkts-apis-audio-i.md#audiorendererinfo8)。<br/>只允许在**initialized**状态下设置。<br/>在第一次调用[prepare()](#prepare9)之前设置，以便音频渲染器信息在之后生效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 47| audioEffectMode<sup>10+</sup> | [audio.AudioEffectMode](../apis-audio-kit/arkts-apis-audio-e.md#audioeffectmode10) | 否 | 是 | 设置音频音效模式，默认值为EFFECT_DEFAULT，动态属性。audioRendererInfo的usage变动时会恢复为默认值，只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 48| state<sup>9+</sup> | [AVPlayerState](arkts-apis-media-t.md#avplayerstate9) | 是 | 否 | 音视频播放的状态，全状态有效，可查询参数。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 49| currentTime<sup>9+</sup> | number | 是 | 否 | 视频的当前播放位置，单位为毫秒（ms），可查询参数。<br/>返回为(-1)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 50| duration<sup>9+</sup> | number | 是 | 否 | 视频时长，单位为毫秒（ms），可查询参数。<br/>返回为(-1)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 51| width<sup>9+</sup> | number | 是 | 否 | 视频宽，单位为像素（px），可查询参数。<br/>返回为(0)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 52| height<sup>9+</sup> | number | 是 | 否 | 视频高，单位为像素（px），可查询参数。<br/>返回为(0)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 53 54## on('stateChange')<sup>9+</sup> 55 56on(type: 'stateChange', callback: OnAVPlayerStateChangeHandle): void 57 58监听播放状态机AVPlayerState切换的事件。 59 60**原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 61 62**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 63 64**参数：** 65 66| 参数名 | 类型 | 必填 | 说明 | 67| -------- | -------- | ---- | ------------------------------------------------------------ | 68| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 69| callback | [OnAVPlayerStateChangeHandle](arkts-apis-media-t.md#onavplayerstatechangehandle12) | 是 | 状态机切换事件回调方法。 | 70 71**示例：** 72 73```ts 74async function test(){ 75 let avPlayer = await media.createAVPlayer(); 76 avPlayer.on('stateChange', async (state: string, reason: media.StateChangeReason) => { 77 switch (state) { 78 case 'idle': 79 console.info('state idle called'); 80 break; 81 case 'initialized': 82 console.info('initialized prepared called'); 83 break; 84 case 'prepared': 85 console.info('state prepared called'); 86 break; 87 case 'playing': 88 console.info('state playing called'); 89 break; 90 case 'paused': 91 console.info('state paused called'); 92 break; 93 case 'completed': 94 console.info('state completed called'); 95 break; 96 case 'stopped': 97 console.info('state stopped called'); 98 break; 99 case 'released': 100 console.info('state released called'); 101 break; 102 case 'error': 103 console.info('state error called'); 104 break; 105 default: 106 console.info('unknown state :' + state); 107 break; 108 } 109 }); 110} 111``` 112 113## off('stateChange')<sup>9+</sup> 114 115off(type: 'stateChange', callback?: OnAVPlayerStateChangeHandle): void 116 117取消监听播放状态机[AVPlayerState](arkts-apis-media-t.md#avplayerstate9)切换的事件。 118 119**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 120 121**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 122 123**参数：** 124 125| 参数名 | 类型 | 必填 | 说明 | 126| ------ | ------ | ---- | ----------------------------------------------------- | 127| type | string | 是 | 状态机切换事件回调类型，取消注册的事件：'stateChange' | 128| callback | [OnAVPlayerStateChangeHandle](arkts-apis-media-t.md#onavplayerstatechangehandle12) | 否 | 状态机切换事件回调方法。<br/>从API version 12开始支持此参数。 | 129 130**示例：** 131 132```ts 133async function test(){ 134 let avPlayer = await media.createAVPlayer(); 135 avPlayer.off('stateChange'); 136} 137``` 138 139## on('error')<sup>9+</sup> 140 141on(type: 'error', callback: ErrorCallback): void 142 143监听[AVPlayer](arkts-apis-media-AVPlayer.md)的错误事件，该事件仅用于错误提示，不需要用户停止播控动作。如果此时[AVPlayerState](arkts-apis-media-t.md#avplayerstate9)也切至error状态，用户需要通过[reset()](#reset9)或者[release()](#release9)退出播放操作。 144 145**原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 146 147**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 148 149**参数：** 150 151| 参数名 | 类型 | 必填 | 说明 | 152| -------- | -------- | ---- | ------------------------------------------------------------ | 153| type | string | 是 | 错误事件回调类型，支持的事件：'error'，用户操作和系统都会触发此事件。 | 154| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 错误事件回调方法，使用播放器的过程中发生错误，会提供错误码ID和错误信息。 | 155 156**错误码：** 157 158以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 159 160在API version 9-13，针对网络、服务器等数据流异常，接口上报5400103；从API version 14开始，对应错误细化为错误码5411001-5411011。 161 162| 错误码ID | 错误信息 | 163| -------- | --------------------- | 164| 201 | Permission denied. | 165| 401 | The parameter check failed. | 166| 801 | Capability not supported. | 167| 5400101 | No memory. | 168| 5400102 | Operation not allowed.| 169| 5400104 | Time out. | 170| 5400105 | Service died. | 171| 5400106 | Unsupported format. | 172| 5410002 | Seek continuous unsupported. | 173| 5411001 | IO can not find host. | 174| 5411002 | IO connection timeout. | 175| 5411003 | IO network abnormal. | 176| 5411004 | IO network unavailable. | 177| 5411005 | IO no permission. | 178| 5411006 | IO request denied. | 179| 5411007 | IO resource not found. | 180| 5411008 | IO SSL client cert needed. | 181| 5411009 | IO SSL connect fail. | 182| 5411010 | IO SSL server cert untrusted. | 183| 5411011 | IO unsupported request. | 184 185**示例：** 186 187```ts 188import { BusinessError } from '@kit.BasicServicesKit'; 189async function test(){ 190 let avPlayer = await media.createAVPlayer(); 191 avPlayer.on('error', (error: BusinessError) => { 192 console.info('error happened,and error message is :' + error.message); 193 console.info('error happened,and error code is :' + error.code); 194 }); 195} 196``` 197 198## off('error')<sup>9+</sup> 199 200off(type: 'error', callback?: ErrorCallback): void 201 202取消监听播放的错误事件。 203 204**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 205 206**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 207 208**参数：** 209 210| 参数名 | 类型 | 必填 | 说明 | 211| ------ | ------ | ---- | ----------------------------------------- | 212| type | string | 是 | 错误事件回调类型，取消注册的事件：'error' | 213| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 错误事件回调方法，使用播放器的过程中发生错误，会提供错误码ID和错误信息。<br/>从API version 12开始支持此参数。 | 214 215**示例：** 216 217```ts 218import { BusinessError } from '@kit.BasicServicesKit'; 219 220async function test(){ 221 let avPlayer = await media.createAVPlayer(); 222 avPlayer.off('error'); 223} 224``` 225 226## setMediaSource<sup>12+</sup> 227 228setMediaSource(src:MediaSource, strategy?: PlaybackStrategy): Promise\<void> 229 230流媒体预下载资源设置，下载url对应的流媒体数据，并暂存在内存中。[视频播放开发指导](../../media/media/video-playback.md)。通过Promise获取返回值。 231 232**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 233 234**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 235 236**参数：** 237 238| 参数名 | 类型 | 必填 | 说明 | 239| -------- | -------- | ---- | -------------------- | 240| src | [MediaSource](arkts-apis-media-MediaSource.md) | 是 | 流媒体预下载媒体来源。 | 241| strategy | [PlaybackStrategy](arkts-apis-media-i.md#playbackstrategy12) | 否 | 流媒体预下载播放策略。 | 242 243**返回值：** 244 245| 类型 | 说明 | 246| -------------- | ------------------------------------------ | 247| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 248 249**错误码：** 250 251以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 252 253| 错误码ID | 错误信息 | 254| -------- | ----------------------------------------- | 255| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 256| 5400102 | Operation not allowed. Return by promise. | 257 258**示例：** 259 260<!--code_no_check--> 261```ts 262async function test(){ 263 let player = await media.createAVPlayer(); 264 let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 265 let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 266 let playStrategy : media.PlaybackStrategy = { 267 preferredWidth: 1, 268 preferredHeight: 2, 269 preferredBufferDuration: 3, 270 preferredHdr: false, 271 preferredBufferDurationForPlaying: 1, 272 thresholdForAutoQuickPlay: 5 273 }; 274 player.setMediaSource(mediaSource, playStrategy); 275} 276``` 277 278## setPlaybackStrategy<sup>12+</sup> 279 280setPlaybackStrategy(strategy: PlaybackStrategy): Promise\<void> 281 282设置播放策略，只能在initialized状态下调用。 283 284**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 285 286**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 287 288**参数：** 289 290| 参数名 | 类型 | 必填 | 说明 | 291| -------- | -------- | ---- | -------------------- | 292| strategy | [PlaybackStrategy](arkts-apis-media-i.md#playbackstrategy12) | 是 | 播放策略。 | 293 294**返回值：** 295 296| 类型 | 说明 | 297| -------------- | ------------------------------------ | 298| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 299 300**错误码：** 301 302以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 303 304| 错误码ID | 错误信息 | 305| -------- | ----------------------------------------- | 306| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. | 307| 5400102 | Operation not allowed. Return by promise. | 308 309**示例：** 310 311<!--code_no_check--> 312```ts 313import { common } from '@kit.AbilityKit'; 314 315let player = await media.createAVPlayer(); 316let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 317let fileDescriptor = await context.resourceManager.getRawFd('xxx.mp4'); 318player.fdSrc = fileDescriptor 319let playStrategy : media.PlaybackStrategy = { 320 preferredWidth: 1, 321 preferredHeight: 2, 322 preferredBufferDuration: 3, 323 preferredHdr: false, 324 mutedMediaType: media.MediaType.MEDIA_TYPE_AUD, 325 preferredBufferDurationForPlaying: 1, 326 thresholdForAutoQuickPlay: 5 327}; 328player.setPlaybackStrategy(playStrategy); 329``` 330 331## setPlaybackRange<sup>18+</sup> 332 333setPlaybackRange(startTimeMs: number, endTimeMs: number, mode?: SeekMode) : Promise\<void> 334 335设置播放区间，并通过指定的[SeekMode](arkts-apis-media-e.md#seekmode8)跳转到区间开始位置。设置之后，只播放音视频文件设定区间内的内容。该方法异步方式返回执行结果，通过Promise获取返回值。可在**initialized**/**prepared**/**paused**/**stopped**/**completed**状态下使用。 336 337**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 338 339**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 340 341**参数：** 342 343| 参数名 | 类型 | 必填 | 说明 | 344| -------- | ---------------------- | ---- | --------------------------- | 345| startTimeMs | number | 是 | 区间开始位置，单位ms，取值[0, duration)。可以设置-1值，系统将会从0位置开始播放。| 346| endTimeMs | number | 是 | 区间结束位置，单位ms，取值(startTimeMs, duration]。可以设置-1值，系统将会播放到资源末尾。| 347| mode | [SeekMode](arkts-apis-media-e.md#seekmode8) | 否 | 支持SeekMode.SEEK_PREV_SYNC和SeekMode.SEEK_CLOSEST, <br/>默认值: SeekMode.SEEK_PREV_SYNC。| 348 349**返回值：** 350 351| 类型 | 说明 | 352| -------------- | ------------------------------------ | 353| Promise\<void> | Promise对象，无返回结果。 | 354 355**错误码：** 356 357以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 358 359| 错误码ID | 错误信息 | 360| -------- | ------------------------------------------ | 361| 401 | The parameter check failed. Return by promise. | 362| 5400102 | Operation not allowed. Return by promise. | 363 364**示例：** 365 366```ts 367import { BusinessError } from '@kit.BasicServicesKit'; 368 369async function test(){ 370 let avPlayer = await media.createAVPlayer(); 371 avPlayer.setPlaybackRange(0, 6000, media.SeekMode.SEEK_CLOSEST).then(() => { 372 console.info('Succeeded setPlaybackRange'); 373 }).catch((err: BusinessError) => { 374 console.error('Failed to setPlaybackRange' + err.message); 375 }); 376} 377``` 378 379## prepare<sup>9+</sup> 380 381prepare(callback: AsyncCallback\<void>): void 382 383准备播放音频/视频，需在[stateChange](#onstatechange9)事件成功触发至initialized状态后，才能调用。使用callback方式异步获取返回值。 384 385**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 386 387**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 388 389**参数：** 390 391| 参数名 | 类型 | 必填 | 说明 | 392| -------- | -------- | ---- | -------------------- | 393| callback | AsyncCallback\<void> | 是 | 准备播放的回调方法。 | 394 395**错误码：** 396 397以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 398 399| 错误码ID | 错误信息 | 400| -------- | ------------------------------------------ | 401| 5400102 | Operation not allowed. Return by callback. | 402| 5400106 | Unsupported format. Return by callback. | 403 404**示例：** 405 406```ts 407import { BusinessError } from '@kit.BasicServicesKit'; 408 409async function test(){ 410 let avPlayer = await media.createAVPlayer(); 411 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至initialized状态后才能调用。 412 avPlayer.prepare((err: BusinessError) => { 413 if (err) { 414 console.error('Failed to prepare,error message is :' + err.message); 415 } else { 416 console.info('Succeeded in preparing'); 417 } 418 }); 419} 420``` 421 422## prepare<sup>9+</sup> 423 424prepare(): Promise\<void> 425 426准备播放音频/视频，需在[stateChange](#onstatechange9)事件成功触发至initialized状态后，才能调用。通过Promise获取返回值。 427 428如果应用使用到多个短视频频繁切换的场景，为了提升切换性能，可以考虑创建多个AVPlayer对象，提前准备下一个视频，详情参见[在线短视频流畅切换](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-smooth-switching)。 429 430**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 431 432**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 433 434**返回值：** 435 436| 类型 | 说明 | 437| -------------- | ------------------------- | 438| Promise\<void> | 准备播放的Promise返回值。 | 439 440**错误码：** 441 442以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 443 444| 错误码ID | 错误信息 | 445| -------- | ----------------------------------------- | 446| 5400102 | Operation not allowed. Return by promise. | 447| 5400106 | Unsupported format. Return by promise. | 448 449**示例：** 450 451```ts 452import { BusinessError } from '@kit.BasicServicesKit'; 453 454async function test(){ 455 let avPlayer = await media.createAVPlayer(); 456 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至initialized状态后才能调用。 457 avPlayer.prepare().then(() => { 458 console.info('Succeeded in preparing'); 459 }, (err: BusinessError) => { 460 console.error('Failed to prepare,error message is :' + err.message); 461 }); 462} 463``` 464 465## setMediaMuted<sup>12+</sup> 466 467setMediaMuted(mediaType: MediaType, muted: boolean ): Promise\<void> 468 469设置音频静音/取消音频静音。 470 471从API 20开始，支持设置关闭视频画面/取消关闭视频画面。 472 473只能在prepared/playing/paused/completed状态下调用。 474 475**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 476 477**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 478 479**参数：** 480 481| 参数名 | 类型 | 必填 | 说明 | 482| -------- | -------- | ---- | -------------------- | 483| mediaType | [MediaType](arkts-apis-media-e.md#mediatype8) | 是 | 播放策略。 | 484| muted | boolean | 是 | API 12-19，仅支持设置音频格式，表示音频是否静音播放。true表示是静音播放，false表示不是静音播放。<br>API20增加支持设置视频格式，表示视频画面是否关闭，true表示关闭画面，false表示恢复画面。| 485 486**返回值：** 487 488| 类型 | 说明 | 489| -------------- | ------------------------- | 490| Promise\<void> | 准备播放的Promise返回值。 | 491 492**错误码：** 493 494以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 495 496| 错误码ID | 错误信息 | 497| -------- | ----------------------------------------- | 498| 401 | The parameter check failed. Return by promise. | 499| 5400102 | Operation not allowed. Return by promise. | 500 501**示例：** 502 503```ts 504import { BusinessError } from '@kit.BasicServicesKit'; 505 506async function test(){ 507 let avPlayer = await media.createAVPlayer(); 508 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至initialized状态后才能调用。 509 avPlayer.prepare().then(() => { 510 console.info('Succeeded in preparing'); 511 avPlayer.setMediaMuted(media.MediaType.MEDIA_TYPE_AUD, true); 512 }, (err: BusinessError) => { 513 console.error('Failed to prepare,error message is :' + err.message); 514 }); 515} 516``` 517 518## play<sup>9+</sup> 519 520play(callback: AsyncCallback\<void>): void 521 522开始播放音视频资源，只能在prepared/paused/completed状态调用。使用callback方式异步获取返回值。 523 524**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 525 526**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 527 528**参数：** 529 530| 参数名 | 类型 | 必填 | 说明 | 531| -------- | -------- | ---- | -------------------- | 532| callback | AsyncCallback\<void> | 是 | 开始播放的回调方法。 | 533 534**错误码：** 535 536以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 537 538| 错误码ID | 错误信息 | 539| -------- | ------------------------------------------ | 540| 5400102 | Operation not allowed. Return by callback. | 541 542**示例：** 543 544```ts 545import { BusinessError } from '@kit.BasicServicesKit'; 546 547async function test(){ 548 let avPlayer = await media.createAVPlayer(); 549 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/paused/completed状态后才能调用。 550 avPlayer.play((err: BusinessError) => { 551 if (err) { 552 console.error('Failed to play,error message is :' + err.message); 553 } else { 554 console.info('Succeeded in playing'); 555 } 556 }); 557} 558``` 559 560## play<sup>9+</sup> 561 562play(): Promise\<void> 563 564开始播放音视频资源，只能在prepared/paused/completed状态调用。通过Promise获取返回值。 565 566**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 567 568**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 569 570**返回值：** 571 572| 类型 | 说明 | 573| -------------- | ------------------------- | 574| Promise\<void> | 开始播放的Promise返回值。 | 575 576**错误码：** 577 578以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 579 580| 错误码ID | 错误信息 | 581| -------- | ----------------------------------------- | 582| 5400102 | Operation not allowed. Return by promise. | 583 584**示例：** 585 586```ts 587import { BusinessError } from '@kit.BasicServicesKit'; 588 589async function test(){ 590 let avPlayer = await media.createAVPlayer(); 591 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/paused/completed状态后才能调用。 592 avPlayer.play().then(() => { 593 console.info('Succeeded in playing'); 594 }, (err: BusinessError) => { 595 console.error('Failed to play,error message is :' + err.message); 596 }); 597} 598``` 599 600## pause<sup>9+</sup> 601 602pause(callback: AsyncCallback\<void>): void 603 604暂停播放音视频资源，只能在playing状态调用。使用callback方式异步获取返回值。 605 606**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 607 608**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 609 610**参数：** 611 612| 参数名 | 类型 | 必填 | 说明 | 613| -------- | -------- | ---- | -------------------- | 614| callback | AsyncCallback\<void> | 是 | 暂停播放的回调方法。 | 615 616**错误码：** 617 618以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 619 620| 错误码ID | 错误信息 | 621| -------- | ------------------------------------------ | 622| 5400102 | Operation not allowed. Return by callback. | 623 624**示例：** 625 626```ts 627import { BusinessError } from '@kit.BasicServicesKit'; 628 629async function test(){ 630 let avPlayer = await media.createAVPlayer(); 631 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至playing状态后才能调用。 632 avPlayer.pause((err: BusinessError) => { 633 if (err) { 634 console.error('Failed to pause,error message is :' + err.message); 635 } else { 636 console.info('Succeeded in pausing'); 637 } 638 }); 639} 640``` 641 642## pause<sup>9+</sup> 643 644pause(): Promise\<void> 645 646暂停播放音视频资源，只能在playing状态调用。通过Promise获取返回值。 647 648**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 649 650**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 651 652**返回值：** 653 654| 类型 | 说明 | 655| -------------- | ------------------------- | 656| Promise\<void> | 暂停播放的Promise返回值。 | 657 658**错误码：** 659 660以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 661 662| 错误码ID | 错误信息 | 663| -------- | ----------------------------------------- | 664| 5400102 | Operation not allowed. Return by promise. | 665 666**示例：** 667 668```ts 669import { BusinessError } from '@kit.BasicServicesKit'; 670 671async function test(){ 672 let avPlayer = await media.createAVPlayer(); 673 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至playing状态后才能调用。 674 avPlayer.pause().then(() => { 675 console.info('Succeeded in pausing'); 676 }, (err: BusinessError) => { 677 console.error('Failed to pause,error message is :' + err.message); 678 }); 679} 680``` 681 682## stop<sup>9+</sup> 683 684stop(callback: AsyncCallback\<void>): void 685 686停止播放音视频资源，只能在prepared/playing/paused/completed状态调用。使用callback方式异步获取返回值。 687 688**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 689 690**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 691 692**参数：** 693 694| 参数名 | 类型 | 必填 | 说明 | 695| -------- | -------- | ---- | -------------------- | 696| callback | AsyncCallback\<void> | 是 | 停止播放的回调方法。 | 697 698**错误码：** 699 700以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 701 702| 错误码ID | 错误信息 | 703| -------- | ------------------------------------------ | 704| 5400102 | Operation not allowed. Return by callback. | 705 706**示例：** 707 708```ts 709import { BusinessError } from '@kit.BasicServicesKit'; 710 711async function test(){ 712 let avPlayer = await media.createAVPlayer(); 713 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused/completed状态后才能调用。 714 avPlayer.stop((err: BusinessError) => { 715 if (err) { 716 console.error('Failed to stop,error message is :' + err.message); 717 } else { 718 console.info('Succeeded in stopping'); 719 } 720 }); 721} 722``` 723 724## stop<sup>9+</sup> 725 726stop(): Promise\<void> 727 728停止播放音视频资源，只能在prepared/playing/paused/completed状态调用。通过Promise获取返回值。 729 730**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 731 732**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 733 734**返回值：** 735 736| 类型 | 说明 | 737| -------------- | ------------------------- | 738| Promise\<void> | 停止播放的Promise返回值。 | 739 740**错误码：** 741 742以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 743 744| 错误码ID | 错误信息 | 745| -------- | ----------------------------------------- | 746| 5400102 | Operation not allowed. Return by promise. | 747 748**示例：** 749 750```ts 751import { BusinessError } from '@kit.BasicServicesKit'; 752 753async function test(){ 754 let avPlayer = await media.createAVPlayer(); 755 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused/completed状态后才能调用。 756 avPlayer.stop().then(() => { 757 console.info('Succeeded in stopping'); 758 }, (err: BusinessError) => { 759 console.error('Failed to stop,error message is :' + err.message); 760 }); 761} 762``` 763 764## reset<sup>9+</sup> 765 766reset(callback: AsyncCallback\<void>): void 767 768重置播放，只能在initialized/prepared/playing/paused/completed/stopped/error状态调用。使用callback方式异步获取返回值。 769 770**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 771 772**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 773 774**参数：** 775 776| 参数名 | 类型 | 必填 | 说明 | 777| -------- | -------- | ---- | -------------------- | 778| callback | AsyncCallback\<void> | 是 | 重置播放的回调方法。 | 779 780**错误码：** 781 782以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 783 784| 错误码ID | 错误信息 | 785| -------- | ------------------------------------------ | 786| 5400102 | Operation not allowed. Return by callback. | 787 788**示例：** 789 790```ts 791import { BusinessError } from '@kit.BasicServicesKit'; 792 793async function test(){ 794 let avPlayer = await media.createAVPlayer(); 795 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至initialized/prepared/playing/paused/completed/stopped/error状态后才能调用。 796 avPlayer.reset((err: BusinessError) => { 797 if (err) { 798 console.error('Failed to reset,error message is :' + err.message); 799 } else { 800 console.info('Succeeded in resetting'); 801 } 802 }); 803} 804``` 805 806## reset<sup>9+</sup> 807 808reset(): Promise\<void> 809 810重置播放，只能在initialized/prepared/playing/paused/completed/stopped/error状态调用。通过Promise获取返回值。 811 812**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 813 814**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 815 816**返回值：** 817 818| 类型 | 说明 | 819| -------------- | ------------------------- | 820| Promise\<void> | 重置播放的Promise返回值。 | 821 822**错误码：** 823 824以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 825 826| 错误码ID | 错误信息 | 827| -------- | ----------------------------------------- | 828| 5400102 | Operation not allowed. Return by promise. | 829 830**示例：** 831 832```ts 833import { BusinessError } from '@kit.BasicServicesKit'; 834 835async function test(){ 836 let avPlayer = await media.createAVPlayer(); 837 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至initialized/prepared/playing/paused/completed/stopped/error状态后才能调用。 838 avPlayer.reset().then(() => { 839 console.info('Succeeded in resetting'); 840 }, (err: BusinessError) => { 841 console.error('Failed to reset,error message is :' + err.message); 842 }); 843} 844``` 845 846## release<sup>9+</sup> 847 848release(callback: AsyncCallback\<void>): void 849 850销毁播放资源，除released状态外，均可以调用。使用callback方式异步获取返回值。 851 852**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 853 854**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 855 856**参数：** 857 858| 参数名 | 类型 | 必填 | 说明 | 859| -------- | -------- | ---- | -------------------- | 860| callback | AsyncCallback\<void> | 是 | 销毁播放的回调方法。 | 861 862**错误码：** 863 864以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 865 866| 错误码ID | 错误信息 | 867| -------- | ------------------------------------------ | 868| 5400102 | Operation not allowed. Return by callback. | 869 870**示例：** 871 872```ts 873import { BusinessError } from '@kit.BasicServicesKit'; 874 875async function test(){ 876 let avPlayer = await media.createAVPlayer(); 877 // 此处仅为示意，实际开发中需要在stateChange事件成功触发除released以外的状态才能调用。 878 avPlayer.release((err: BusinessError) => { 879 if (err) { 880 console.error('Failed to release,error message is :' + err.message); 881 } else { 882 console.info('Succeeded in releasing'); 883 } 884 }); 885} 886``` 887 888## release<sup>9+</sup> 889 890release(): Promise\<void> 891 892销毁播放资源，除released状态，都可以调用。通过Promise获取返回值。 893 894**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 895 896**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 897 898**返回值：** 899 900| 类型 | 说明 | 901| -------------- | ------------------------- | 902| Promise\<void> | 销毁播放的Promise返回值。 | 903 904**错误码：** 905 906以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 907 908| 错误码ID | 错误信息 | 909| -------- | ----------------------------------------- | 910| 5400102 | Operation not allowed. Return by promise. | 911 912**示例：** 913 914```ts 915import { BusinessError } from '@kit.BasicServicesKit'; 916 917async function test(){ 918 let avPlayer = await media.createAVPlayer(); 919 // 此处仅为示意，实际开发中需要在stateChange事件成功触发除released以外的状态才能调用。 920 avPlayer.release().then(() => { 921 console.info('Succeeded in releasing'); 922 }, (err: BusinessError) => { 923 console.error('Failed to release,error message is :' + err.message); 924 }); 925} 926``` 927 928## getTrackDescription<sup>9+</sup> 929 930getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 931 932获取音视频轨道信息，可以在prepared/playing/paused状态调用。获取所有音视轨道信息，应在数据加载回调后调用。使用callback方式异步获取返回值。 933 934**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 935 936**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 937 938**参数：** 939 940| 参数名 | 类型 | 必填 | 说明 | 941| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 942| callback | AsyncCallback<Array<[MediaDescription](arkts-apis-media-i.md#mediadescription8)>> | 是 | 回调函数，当获取音视频轨道信息成功，err为undefined，data为获取到的MediaDescription数组；否则为错误对象。| 943 944**错误码：** 945 946以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 947 948| 错误码ID | 错误信息 | 949| -------- | ------------------------------------------ | 950| 5400102 | Operation not allowed. Return by callback. | 951 952**示例：** 953 954```ts 955import { BusinessError } from '@kit.BasicServicesKit'; 956 957async function test(){ 958 let avPlayer = await media.createAVPlayer(); 959 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused状态后才能调用。 960 avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 961 if ((arrList) != null) { 962 console.info('Succeeded in doing getTrackDescription'); 963 } else { 964 console.error(`Failed to do getTrackDescription, error:${error}`); 965 } 966 }); 967} 968``` 969 970## getTrackDescription<sup>9+</sup> 971 972getTrackDescription(): Promise\<Array\<MediaDescription>> 973 974获取音视频轨道信息，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 975 976**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 977 978**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 979 980**返回值：** 981 982| 类型 | 说明 | 983| ------------------------------------------------------ | ------------------------------------------------- | 984| Promise<Array<[MediaDescription](arkts-apis-media-i.md#mediadescription8)>> | Promise对象，返回音视频轨道信息MediaDescription数组。 | 985 986**错误码：** 987 988以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 989 990| 错误码ID | 错误信息 | 991| -------- | ----------------------------------------- | 992| 5400102 | Operation not allowed. Return by promise. | 993 994**示例：** 995 996```ts 997import { BusinessError } from '@kit.BasicServicesKit'; 998 999async function test(){ 1000 let avPlayer = await media.createAVPlayer(); 1001 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused状态后才能调用。 1002 avPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 1003 console.info('Succeeded in getting TrackDescription'); 1004 }).catch((error: BusinessError) => { 1005 console.error(`Failed to get TrackDescription, error:${error}`); 1006 }); 1007} 1008``` 1009 1010## getSelectedTracks<sup>12+</sup> 1011 1012getSelectedTracks(): Promise\<Array\<number>> 1013 1014获取已选择的音视频轨道索引，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1015 1016**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1017 1018**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1019 1020**返回值：** 1021 1022| 类型 | 说明 | 1023| ------------------------------------------------------ | ------------------------------------------------- | 1024| Promise\<Array\<number>> | Promise对象，返回已选择音视频轨道索引数组。 | 1025 1026**错误码：** 1027 1028以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1029 1030| 错误码ID | 错误信息 | 1031| -------- | ----------------------------------------- | 1032| 5400102 | Operation not allowed. | 1033 1034**示例：** 1035 1036```ts 1037import { BusinessError } from '@kit.BasicServicesKit'; 1038 1039async function test(){ 1040 let avPlayer = await media.createAVPlayer(); 1041 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused状态后才能调用。 1042 avPlayer.getSelectedTracks().then((arrList: Array<number>) => { 1043 console.info('Succeeded in getting SelectedTracks'); 1044 }).catch((error: BusinessError) => { 1045 console.error(`Failed to get SelectedTracks, error:${error}`); 1046 }); 1047} 1048``` 1049 1050## getPlaybackInfo<sup>12+</sup> 1051 1052getPlaybackInfo(): Promise\<PlaybackInfo> 1053 1054获取播放过程信息，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1055 1056**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1057 1058**返回值：** 1059 1060| 类型 | 说明 | 1061| ------------------------------------------------------ | ------------------------------------------------- | 1062| Promise<[PlaybackInfo](arkts-apis-media-i.md#playbackinfo12)> | Promise对象，返回播放器信息PlaybackInfo。 | 1063 1064**示例：** 1065 1066```ts 1067import { BusinessError } from '@kit.BasicServicesKit'; 1068 1069let avPlayer: media.AVPlayer | undefined = undefined; 1070let playbackInfo: media.PlaybackInfo | undefined = undefined; 1071media.createAVPlayer(async (err: BusinessError, player: media.AVPlayer) => { 1072 if (player != null) { 1073 avPlayer = player; 1074 console.info(`Succeeded in creating AVPlayer`); 1075 if (avPlayer) { 1076 try { 1077 playbackInfo = await avPlayer.getPlaybackInfo(); 1078 console.info(`AVPlayer getPlaybackInfo = ${JSON.stringify(playbackInfo)}`); // 打印整个PlaybackInfo的值。 1079 } catch (error) { 1080 console.error(`error = ${error}`); 1081 } 1082 } 1083 } else { 1084 console.error(`Failed to create AVPlayer, error message:${err.message}`); 1085 } 1086}); 1087``` 1088 1089## getPlaybackPosition<sup>18+</sup> 1090 1091getPlaybackPosition(): number 1092 1093获取当前播放位置，可以在prepared/playing/paused/completed状态调用。 1094 1095**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1096 1097**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1098 1099**返回值：** 1100 1101| 类型 | 说明 | 1102| ------------------------------------------------------ | ------------------------------------------------- | 1103| number | 返回当前播放位置的时间，单位：毫秒（ms）。| 1104 1105**错误码：** 1106 1107以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1108 1109| 错误码ID | 错误信息 | 1110| -------- | ----------------------------------------- | 1111| 5400102 | Operation not allowed. | 1112 1113**示例：** 1114 1115```ts 1116import { BusinessError } from '@kit.BasicServicesKit'; 1117 1118async function test(){ 1119 let avPlayer = await media.createAVPlayer(); 1120 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至initialized状态后才能调用。 1121 avPlayer.prepare().then(() => { 1122 console.info('Succeeded in preparing'); 1123 let playbackPosition: number = avPlayer.getPlaybackPosition(); 1124 console.info(`AVPlayer getPlaybackPosition== ${playbackPosition}`); 1125 }, (err: BusinessError) => { 1126 console.error('Failed to prepare,error message is :' + err.message); 1127 }); 1128} 1129``` 1130 1131## selectTrack<sup>12+</sup> 1132 1133selectTrack(index: number, mode?: SwitchMode): Promise\<void> 1134 1135使用AVPlayer播放多音视频轨资源时，选择指定轨道播放，通过Promise获取返回值。 1136 1137**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1138 1139**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1140 1141**参数：** 1142 1143| 参数名 | 类型 | 必填 | 说明 | 1144| -------- | -------- | ---- | -------------------- | 1145| index | number | 是 | 多音视频资源的轨道索引，可通过[getTrackDescription](#gettrackdescription9-1)接口获取当前资源的所有轨道信息[MediaDescription](arkts-apis-media-i.md#mediadescription8)。 | 1146| mode | [SwitchMode](arkts-apis-media-e.md#switchmode12) | 否 | 切换视频轨道模式，默认为SMOOTH模式，**仅在DASH协议网络流视频轨切换时生效**，其他场景当前暂不支持。 | 1147 1148**返回值：** 1149 1150| 类型 | 说明 | 1151| -------------- | ------------------------- | 1152| Promise\<void> | 选择轨道完成的Promise返回值。 | 1153 1154**错误码：** 1155 1156以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1157 1158| 错误码ID | 错误信息 | 1159| -------- | ----------------------------------------- | 1160| 401 | The parameter check failed. Return by promise. | 1161| 5400102 | Operation not allowed. Return by promise. | 1162 1163**示例：** 1164 1165<!--code_no_check--> 1166```ts 1167import { BusinessError } from '@kit.BasicServicesKit'; 1168 1169let avPlayer: media.AVPlayer = await media.createAVPlayer(); 1170let audioTrackIndex: Object = 0; 1171avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1172 if (arrList != null) { 1173 for (let i = 0; i < arrList.length; i++) { 1174 if (i != 0) { 1175 // 获取音频轨道列表。 1176 audioTrackIndex = arrList[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 1177 } 1178 } 1179 } else { 1180 console.error(`Failed to get TrackDescription, error:${error}`); 1181 } 1182}); 1183 1184// 选择其中一个音频轨道。 1185avPlayer.selectTrack(parseInt(audioTrackIndex.toString())); 1186``` 1187 1188## deselectTrack<sup>12+</sup> 1189 1190deselectTrack(index: number): Promise\<void> 1191 1192使用AVPlayer播放多音轨视频时取消指定音视频轨道播放，通过Promise获取返回值。 1193 1194**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1195 1196**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1197 1198**参数：** 1199 1200| 参数名 | 类型 | 必填 | 说明 | 1201| -------- | -------- | ---- | -------------------- | 1202| index | number | 是 | 多音视频资源的轨道索引，来自[getTrackDescription](#gettrackdescription9-1)接口所获取的轨道信息[MediaDescription](arkts-apis-media-i.md#mediadescription8)。 | 1203 1204**返回值：** 1205 1206| 类型 | 说明 | 1207| -------------- | ------------------------- | 1208| Promise\<void> | 取消选择曲目完成的Promise返回值。 | 1209 1210**错误码：** 1211 1212以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1213 1214| 错误码ID | 错误信息 | 1215| -------- | ----------------------------------------- | 1216| 401 | The parameter check failed. Return by promise. | 1217| 5400102 | Operation not allowed. Return by promise. | 1218 1219**示例：** 1220 1221<!--code_no_check--> 1222```ts 1223import { BusinessError } from '@kit.BasicServicesKit'; 1224 1225let avPlayer: media.AVPlayer = await media.createAVPlayer(); 1226let audioTrackIndex: Object = 0; 1227avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1228 if (arrList != null) { 1229 for (let i = 0; i < arrList.length; i++) { 1230 if (i != 0) { 1231 // 获取音频轨道列表。 1232 audioTrackIndex = arrList[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 1233 } 1234 } 1235 } else { 1236 console.error(`Failed to get TrackDescription, error:${error}`); 1237 } 1238}); 1239 1240// 选择其中一个音频轨道。 1241avPlayer.selectTrack(parseInt(audioTrackIndex.toString())); 1242// 取消选择上次选中的音频轨道，并恢复到默认音频轨道。 1243avPlayer.deselectTrack(parseInt(audioTrackIndex.toString())); 1244``` 1245 1246## setDecryptionConfig<sup>11+</sup> 1247 1248setDecryptionConfig(mediaKeySession: drm.MediaKeySession, secureVideoPath: boolean): void 1249 1250设置解密配置。当收到[mediaKeySystemInfoUpdate事件](#onmediakeysysteminfoupdate11)时，需根据事件上报的信息创建相关配置并设置解密配置，否则无法播放。 1251 1252**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1253 1254**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1255 1256**参数：** 1257 1258| 参数名 | 类型 | 必填 | 说明 | 1259| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1260| mediaKeySession | [drm.MediaKeySession](../apis-drm-kit/arkts-apis-drm-MediaKeySession.md) | 是 | 解密会话 | 1261| secureVideoPath | boolean | 是 | 安全视频通路，true表示选择安全视频通路，false表示选择非安全视频通路 | 1262 1263**错误码：** 1264 1265以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1266 1267| 错误码ID | 错误信息 | 1268| -------- | ----------------------------------------- | 1269| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1270 1271**示例：** 1272 1273关于drm模块的示例具体可见[@ohos.multimedia.drm](../apis-drm-kit/arkts-apis-drm.md)。 1274 1275```ts 1276import { drm } from '@kit.DrmKit'; 1277 1278async function test(){ 1279 let avPlayer = await media.createAVPlayer(); 1280 // 创建MediaKeySystem系统。 1281 let keySystem:drm.MediaKeySystem = drm.createMediaKeySystem('com.clearplay.drm'); 1282 // 创建MediaKeySession解密会话。 1283 let keySession:drm.MediaKeySession = keySystem.createMediaKeySession(drm.ContentProtectionLevel.CONTENT_PROTECTION_LEVEL_SW_CRYPTO); 1284 // 生成许可证请求、设置许可证响应等。 1285 // 安全视频通路标志。 1286 let secureVideoPath:boolean = false; 1287 // 设置解密配置。 1288 avPlayer.setDecryptionConfig(keySession, secureVideoPath); 1289} 1290``` 1291 1292## getMediaKeySystemInfos<sup>11+</sup> 1293 1294getMediaKeySystemInfos(): Array\<drm.MediaKeySystemInfo> 1295 1296获取当前播放的媒体资源的MediaKeySystemInfo。需要在[mediaKeySystemInfoUpdate事件](#onmediakeysysteminfoupdate11)触发成功后才能调用。 1297 1298**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1299 1300**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1301 1302**返回值：** 1303 1304| 类型 | 说明 | 1305| ------------------------------------------------------ | ------------------------------------------------- | 1306| Array<[drm.MediaKeySystemInfo](../apis-drm-kit/arkts-apis-drm-i.md#mediakeysysteminfo)> | MediaKeySystemInfo数组，MediaKeySystemInfo具有uuid和pssh两个属性。 | 1307 1308**示例：** 1309 1310```ts 1311import { drm } from '@kit.DrmKit'; 1312 1313async function test(){ 1314 let avPlayer = await media.createAVPlayer(); 1315 // 此处仅为示意，实际开发中需要在mediaKeySystemInfoUpdate事件触发成功后才能调用。 1316 const infos = avPlayer.getMediaKeySystemInfos(); 1317 console.info('GetMediaKeySystemInfos count: ' + infos.length); 1318 for (let i = 0; i < infos.length; i++) { 1319 console.info('GetMediaKeySystemInfos uuid: ' + infos[i]["uuid"]); 1320 console.info('GetMediaKeySystemInfos pssh: ' + infos[i]["pssh"]); 1321 } 1322} 1323``` 1324 1325## seek<sup>9+</sup> 1326 1327seek(timeMs: number, mode?:SeekMode): void 1328 1329跳转到指定播放位置，只能在prepared/playing/paused/completed状态调用，可以通过[seekDone事件](#onseekdone9)确认是否生效。 1330注：直播场景不支持seek。 1331 1332**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1333 1334**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1335 1336**参数：** 1337 1338| 参数名 | 类型 | 必填 | 说明 | 1339| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 1340| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, [duration](#属性)]。SEEK_CONTINUOU模式可以额外取值-1，用于表示SEEK_CONTINUOUS模式结束。 | 1341| mode | [SeekMode](arkts-apis-media-e.md#seekmode8) | 否 | 基于视频I帧的跳转模式，默认为SEEK_PREV_SYNC模式，**仅在视频资源播放时设置**。 | 1342 1343**示例：** 1344 1345```ts 1346async function test(){ 1347 let avPlayer = await media.createAVPlayer(); 1348 let seekTime: number = 1000; 1349 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused/completed状态后才能调用。 1350 avPlayer.seek(seekTime, media.SeekMode.SEEK_PREV_SYNC); 1351} 1352``` 1353 1354```ts 1355async function test(){ 1356 // SEEK_CONTINUOUS 可以结合Slider的onChange回调方法进行对应处理，当slideMode为Moving时，触发拖动过程的SeekContinuous。 1357 let avPlayer = await media.createAVPlayer(); 1358 let slideMovingTime: number = 2000; 1359 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused/completed状态后才能调用。 1360 avPlayer.seek(slideMovingTime, media.SeekMode.SEEK_CONTINUOUS); 1361 1362 // 当slideMode为End时，调用seek(-1, media.SeekMode.SEEK_CONTINUOUS)结束seek。 1363 avPlayer.seek(-1, media.SeekMode.SEEK_CONTINUOUS); 1364} 1365``` 1366 1367## isSeekContinuousSupported<sup>18+</sup> 1368 1369isSeekContinuousSupported() : boolean 1370 1371查询媒体源是否支持以SEEK_CONTINUOUS模式[SeekMode](arkts-apis-media-e.md#seekmode8)进行[seek](#seek9)，在prepared/playing/paused/completed状态调用返回实际值，其余状态调用返回false。对于不支持SEEK_CONTINUOUS模式进行seek的设备，返回false。 1372 1373**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1374 1375**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1376 1377**返回值：** 1378 1379| 类型 | 说明 | 1380| -------------- | ------------------------------------------ | 1381| boolean | 媒体源是否支持以SEEK_CONTINUOUS模式进行seek。 | 1382 1383**示例：** 1384 1385```ts 1386async function test(){ 1387 let avPlayer = await media.createAVPlayer(); 1388 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused/completed状态后才能调用。 1389 let isSupported = avPlayer.isSeekContinuousSupported(); 1390} 1391``` 1392 1393## on('seekDone')<sup>9+</sup> 1394 1395on(type: 'seekDone', callback: Callback\<number>): void 1396 1397监听seek生效的事件。 1398 1399**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1400 1401**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1402 1403**参数：** 1404 1405| 参数名 | 类型 | 必填 | 说明 | 1406| -------- | -------- | ---- | ------------------------------------------------------------ | 1407| type | string | 是 | seek生效的事件回调类型，支持的事件：'seekDone'，除SEEK_CONTINUOUS外的[SeekMode](arkts-apis-media-e.md#seekmode8)每次调用seek后都会回调此事件。 | 1408| callback | Callback\<number> | 是 | 回调函数。seek生效的事件回调方法，只会上报用户请求的time位置。<br/>**视频播放：**[SeekMode](arkts-apis-media-e.md#seekmode8)会造成实际跳转位置与用户设置产生偏差，精准位置需要通过currentTime获取，事件回调的time仅代表完成用户某一次请求。 | 1409 1410**示例：** 1411 1412```ts 1413async function test(){ 1414 let avPlayer = await media.createAVPlayer(); 1415 avPlayer.on('seekDone', (seekDoneTime:number) => { 1416 console.info('seekDone called,and seek time is:' + seekDoneTime); 1417 }); 1418} 1419``` 1420 1421## off('seekDone')<sup>9+</sup> 1422 1423off(type: 'seekDone', callback?: Callback\<number>): void 1424 1425取消监听seek生效的事件。 1426 1427**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1428 1429**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1430 1431**参数：** 1432 1433| 参数名 | 类型 | 必填 | 说明 | 1434| ------ | ------ | ---- | ---------------------------------------------------- | 1435| type | string | 是 | seek生效的事件回调类型，取消注册的事件：'seekDone'。 | 1436| callback | Callback\<number> | 否 | 回调函数。seek生效的事件回调方法，只会上报用户请求的time位置。<br/>**视频播放：**[SeekMode](arkts-apis-media-e.md#seekmode8)会造成实际跳转位置与用户设置产生偏差，精准位置需要通过currentTime获取，事件回调的time仅代表完成用户某一次请求。<br/>从API version 12开始支持此参数。 | 1437 1438**示例：** 1439 1440```ts 1441async function test(){ 1442 let avPlayer = await media.createAVPlayer(); 1443 avPlayer.off('seekDone'); 1444} 1445``` 1446 1447## setSpeed<sup>9+</sup> 1448 1449setSpeed(speed: PlaybackSpeed): void 1450 1451设置倍速模式，只能在prepared/playing/paused/completed状态调用，可以通过[speedDone事件](#onspeeddone9)确认是否生效。 1452注：直播场景不支持setSpeed。 1453 1454**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1455 1456**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1457 1458**参数：** 1459 1460| 参数名 | 类型 | 必填 | 说明 | 1461| ------ | -------------------------------- | ---- | ------------------ | 1462| speed | [PlaybackSpeed](arkts-apis-media-e.md#playbackspeed8) | 是 | 指定播放倍速模式。 | 1463 1464**示例：** 1465 1466```ts 1467async function test(){ 1468 let avPlayer = await media.createAVPlayer(); 1469 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused/completed状态后才能调用。 1470 avPlayer.setSpeed(media.PlaybackSpeed.SPEED_FORWARD_2_00_X); 1471} 1472``` 1473 1474## on('speedDone')<sup>9+</sup> 1475 1476on(type: 'speedDone', callback: Callback\<number>): void 1477 1478监听setSpeed生效的事件。 1479 1480**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1481 1482**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1483 1484**参数：** 1485 1486| 参数名 | 类型 | 必填 | 说明 | 1487| -------- | -------- | ---- | ------------------------------------------------------------ | 1488| type | string | 是 | setSpeed生效的事件回调类型，支持的事件：'speedDone'，每次调用setSpeed后都会回调此事件。 | 1489| callback | Callback\<number> | 是 | 回调函数。当setSpeed成功，上报生效的倍速模式，具体见[PlaybackSpeed](arkts-apis-media-e.md#playbackspeed8)。 | 1490 1491**示例：** 1492 1493```ts 1494async function test(){ 1495 let avPlayer = await media.createAVPlayer(); 1496 avPlayer.on('speedDone', (speed:number) => { 1497 console.info('speedDone called,and speed value is:' + speed); 1498 }); 1499} 1500``` 1501 1502## off('speedDone')<sup>9+</sup> 1503 1504off(type: 'speedDone', callback?: Callback\<number>): void 1505 1506取消监听setSpeed生效的事件。 1507 1508**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1509 1510**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1511 1512**参数：** 1513 1514| 参数名 | 类型 | 必填 | 说明 | 1515| ------ | ------ | ---- | --------------------------------------------------------- | 1516| type | string | 是 | setSpeed生效的事件回调类型，取消注册的事件：'speedDone'。 | 1517| callback | Callback\<number> | 否 | 回调函数。当setSpeed成功，上报生效的倍速模式，具体见[PlaybackSpeed](arkts-apis-media-e.md#playbackspeed8)。<br/>从API version 12开始支持此参数。 | 1518 1519**示例：** 1520 1521```ts 1522async function test(){ 1523 let avPlayer = await media.createAVPlayer(); 1524 avPlayer.off('speedDone'); 1525} 1526``` 1527 1528## setPlaybackRate<sup>20+</sup> 1529 1530setPlaybackRate(rate: number): void 1531 1532设置倍速模式。只能在prepared/playing/paused/completed状态调用，取值范围是[0.125, 4.0]，可以通过[playbackRateDone](#onplaybackratedone20)事件确认是否生效。 1533 1534> **注意：** 1535> 1536> 直播场景不支持setPlaybackRate。 1537 1538**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1539 1540**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1541 1542**参数：** 1543 1544| 参数名 | 类型 | 必填 | 说明 | 1545| ------ | -------------------------------- | ---- | ------------------ | 1546| rate | number | 是 | 指定播放倍速速率，取值范围为[0.125, 4.0]。 | 1547 1548**错误码：** 1549 1550以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1551 1552| 错误码ID | 错误信息 | 1553| -------- | ------------------------------------------ | 1554| 5400108 | The parameter check failed, parameter value out of range. | 1555| 5400102 | Operation not allowed，if invalid state or live stream. | 1556 1557**示例：** 1558 1559```ts 1560async function test(){ 1561 let avPlayer = await media.createAVPlayer(); 1562 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused/completed状态后才能调用。 1563 avPlayer.setPlaybackRate(2.0); 1564} 1565``` 1566 1567## on('playbackRateDone')<sup>20+</sup> 1568 1569on(type: 'playbackRateDone', callback: OnPlaybackRateDone): void 1570 1571监听[setPlaybackRate](#setplaybackrate20)生效的事件。 1572 1573**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1574 1575**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1576 1577**参数：** 1578 1579| 参数名 | 类型 | 必填 | 说明 | 1580| -------- | -------- | ---- | ------------------------------------------------------------ | 1581| type | string | 是 | setPlaybackRate生效的事件回调类型，支持的事件：'playbackRateDone'，每次调用setPlaybackRate后都会回调此事件。 | 1582| callback | [OnPlaybackRateDone](#onplaybackratedone20) | 是 | setPlaybackRate生效的事件回调方法，上报设置后的播放速率。<br/>从API version 20开始支持此参数。 | 1583 1584**示例：** 1585 1586```ts 1587async function test(){ 1588 let avPlayer = await media.createAVPlayer(); 1589 avPlayer.on('playbackRateDone', (rate:number) => { 1590 console.info('playbackRateDone called,and rate value is:' + rate); 1591 }); 1592} 1593``` 1594 1595## off('playbackRateDone')<sup>20+</sup> 1596 1597off(type: 'playbackRateDone', callback?: OnPlaybackRateDone): void 1598 1599取消监听[setPlaybackRate](#setplaybackrate20)生效的事件。 1600 1601**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1602 1603**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1604 1605**参数：** 1606 1607| 参数名 | 类型 | 必填 | 说明 | 1608| ------ | ------ | ---- | --------------------------------------------------------- | 1609| type | string | 是 | setPlaybackRate生效的事件回调类型，取消注册的事件：'playbackRateDone'。 | 1610| callback | [OnPlaybackRateDone](#onplaybackratedone20) | 否 | setPlaybackRate生效的事件回调方法，上报设置后的播放速率。如填写该参数，则仅取消注册此回调方法，否则取消注册playbackRateDone事件的所有回调方法。<br/>从API version 20开始支持此参数。 | 1611 1612**示例：** 1613 1614```ts 1615async function test(){ 1616 let avPlayer = await media.createAVPlayer(); 1617 avPlayer.off('playbackRateDone'); 1618} 1619``` 1620 1621## setBitrate<sup>9+</sup> 1622 1623setBitrate(bitrate: number): void 1624 1625设置比特率，以播放所指定比特率的流媒体资源，当前仅对**HLS/DASH协议网络流**有效。默认情况下，AVPlayer会根据网络连接速度选择合适的比特率。只能在prepared/playing/paused/completed状态调用，可以通过[bitrateDone](#onbitratedone9)事件确认是否生效。 1626 1627**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1628 1629**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1630 1631**参数：** 1632 1633| 参数名 | 类型 | 必填 | 说明 | 1634| ------- | ------ | ---- | ------------------------------------------------------------ | 1635| bitrate | number | 是 | 指定比特率，须通过[availableBitrates](#onavailablebitrates9)事件获得当前HLS/DASH协议网络流可用的比特率列表，如果用户指定的比特率不在此列表中，则播放器将从可用比特率列表中选择最接近的比特率。如果通过availableBitrates事件获得的比特率列表长度为0，则不支持指定比特率，也不会产生bitrateDone回调。 | 1636 1637**示例：** 1638 1639```ts 1640async function test(){ 1641 let avPlayer = await media.createAVPlayer(); 1642 let bitrate: number = 96000; 1643 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至prepared/playing/paused/completed状态后才能调用。 1644 avPlayer.setBitrate(bitrate); 1645} 1646``` 1647 1648## on('bitrateDone')<sup>9+</sup> 1649 1650on(type: 'bitrateDone', callback: Callback\<number>): void 1651 1652监听setBitrate生效的事件。 1653 1654**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1655 1656**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1657 1658**参数：** 1659 1660| 参数名 | 类型 | 必填 | 说明 | 1661| -------- | -------- | ---- | ------------------------------------------------------------ | 1662| type | string | 是 | setBitrate生效的事件回调类型，支持的事件：'bitrateDone'，每次调用setBitrate后都会回调此事件。 | 1663| callback | Callback\<number> | 是 | setBitrate生效的事件回调方法，上报生效的比特率。 | 1664 1665**示例：** 1666 1667```ts 1668async function test(){ 1669 let avPlayer = await media.createAVPlayer(); 1670 avPlayer.on('bitrateDone', (bitrate:number) => { 1671 console.info('bitrateDone called,and bitrate value is:' + bitrate); 1672 }); 1673} 1674``` 1675 1676## off('bitrateDone')<sup>9+</sup> 1677 1678off(type: 'bitrateDone', callback?: Callback\<number>): void 1679 1680取消监听setBitrate生效的事件。 1681 1682**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1683 1684**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1685 1686**参数：** 1687 1688| 参数名 | 类型 | 必填 | 说明 | 1689| ------ | ------ | ---- | ------------------------------------------------------------ | 1690| type | string | 是 | setBitrate生效的事件回调类型，取消注册的事件：'bitrateDone'。 | 1691| callback | Callback\<number> | 否 | setBitrate生效的事件回调方法，上报生效的比特率。<br/>从API version 12开始支持此参数。 | 1692 1693**示例：** 1694 1695```ts 1696async function test(){ 1697 let avPlayer = await media.createAVPlayer(); 1698 avPlayer.off('bitrateDone'); 1699} 1700``` 1701 1702## on('availableBitrates')<sup>9+</sup> 1703 1704on(type: 'availableBitrates', callback: Callback\<Array\<number>>): void 1705 1706监听HLS/DASH协议网络流可用的比特率列表，只会在切换prepared状态后上报。 1707 1708**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1709 1710**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1711 1712**参数：** 1713 1714| 参数名 | 类型 | 必填 | 说明 | 1715| -------- | -------- | ---- | ------------------------------------------------------------ | 1716| type | string | 是 | HLS/DASH协议网络流可用比特率上报事件回调类型，支持的事件：'availableBitrates'，只会在prepared之后上报一次。 | 1717| callback | Callback\<Array\<number>> | 是 | HLS/DASH协议网络流可用比特率上报事件回调方法，使用数组存放支持的比特率。如果数组长度为0，则不支持指定比特率。 | 1718 1719**示例：** 1720 1721```ts 1722async function test(){ 1723 let avPlayer = await media.createAVPlayer(); 1724 avPlayer.on('availableBitrates', (bitrates: Array<number>) => { 1725 console.info('availableBitrates called,and availableBitrates length is:' + bitrates.length); 1726 }); 1727} 1728``` 1729 1730## off('availableBitrates')<sup>9+</sup> 1731 1732off(type: 'availableBitrates', callback?: Callback\<Array\<number>>): void 1733 1734取消监听HLS/DASH协议网络流可用的比特率列表，调用[prepare](#prepare9)后，上报此事件。 1735 1736**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1737 1738**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1739 1740**参数：** 1741 1742| 参数名 | 类型 | 必填 | 说明 | 1743| ------ | ------ | ---- | ------------------------------------------------------------ | 1744| type | string | 是 | HLS/DASH协议网络流可用比特率上报事件回调类型，取消注册的事件：'availableBitrates'。 | 1745| callback | Callback\<Array\<number>> | 否 | HLS/DASH协议网络流可用比特率上报事件回调方法，使用数组存放支持的比特率。如果数组长度为0，则不支持指定比特率。<br/>从API version 12开始支持此参数。 | 1746 1747**示例：** 1748 1749```ts 1750async function test(){ 1751 let avPlayer = await media.createAVPlayer(); 1752 avPlayer.off('availableBitrates'); 1753} 1754``` 1755 1756 1757## on('mediaKeySystemInfoUpdate')<sup>11+</sup> 1758 1759on(type: 'mediaKeySystemInfoUpdate', callback: Callback\<Array\<drm.MediaKeySystemInfo>>): void 1760 1761监听mediaKeySystemInfoUpdate事件。 1762 1763**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1764 1765**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1766 1767**参数：** 1768 1769| 参数名 | 类型 | 必填 | 说明 | 1770| -------- | -------- | ---- | ------------------------------------------------------------ | 1771| type | string | 是 | 版权保护信息更新上报事件回调类型，支持的事件：'mediaKeySystemInfoUpdate'，当播放内容的版权保护信息更新时上报事件。 | 1772| callback | Callback\<Array\<drm.[MediaKeySystemInfo](../apis-drm-kit/arkts-apis-drm-i.md#mediakeysysteminfo)>> | 是 | 版权保护信息更新上报事件回调方法，上报MediaKeySystemInfo数组。 | 1773 1774**示例：** 1775 1776```ts 1777import { drm } from '@kit.DrmKit'; 1778 1779async function test(){ 1780 let avPlayer = await media.createAVPlayer(); 1781 avPlayer.on('mediaKeySystemInfoUpdate', (mediaKeySystemInfo: Array<drm.MediaKeySystemInfo>) => { 1782 for (let i = 0; i < mediaKeySystemInfo.length; i++) { 1783 console.info('mediaKeySystemInfoUpdate happened uuid: ' + mediaKeySystemInfo[i]["uuid"]); 1784 console.info('mediaKeySystemInfoUpdate happened pssh: ' + mediaKeySystemInfo[i]["pssh"]); 1785 } 1786 }); 1787} 1788``` 1789 1790## off('mediaKeySystemInfoUpdate')<sup>11+</sup> 1791 1792off(type: 'mediaKeySystemInfoUpdate', callback?: Callback\<Array\<drm.MediaKeySystemInfo>>): void; 1793 1794取消监听mediaKeySystemInfoUpdate事件。 1795 1796**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1797 1798**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1799 1800**参数：** 1801 1802| 参数名 | 类型 | 必填 | 说明 | 1803| ------ | ------ | ---- | ------------------------------------------------------------ | 1804| type | string | 是 | 版权保护信息更新上报事件回调类型，取消注册的事件：'mediaKeySystemInfoUpdate'。 | 1805| callback | Callback\<Array\<drm.[MediaKeySystemInfo](../apis-drm-kit/arkts-apis-drm-i.md#mediakeysysteminfo)>> | 否 | 版权保护信息更新上报事件回调方法，上报版权保护信息数组。如填写该参数，则仅取消注册此回调方法，否则取消注册mediaKeySystemInfoUpdate事件的所有回调方法。 | 1806 1807**示例：** 1808 1809```ts 1810async function test(){ 1811 let avPlayer = await media.createAVPlayer(); 1812 avPlayer.off('mediaKeySystemInfoUpdate'); 1813} 1814``` 1815 1816## setVolume<sup>9+</sup> 1817 1818setVolume(volume: number): void 1819 1820设置媒体播放音量，只能在prepared/playing/paused/completed状态调用，可以通过[volumeChange事件](#onvolumechange9)确认是否生效。 1821 1822**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1823 1824**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1825 1826**参数：** 1827 1828| 参数名 | 类型 | 必填 | 说明 | 1829| ------ | ------ | ---- | ------------------------------------------------------------ | 1830| volume | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 1831 1832**示例：** 1833 1834```ts 1835async function test(){ 1836 let avPlayer = await media.createAVPlayer(); 1837 let volume: number = 1.0; 1838 avPlayer.setVolume(volume); 1839} 1840``` 1841 1842## on('volumeChange')<sup>9+</sup> 1843 1844on(type: 'volumeChange', callback: Callback\<number>): void 1845 1846监听setVolume生效的事件。 1847 1848**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1849 1850**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1851 1852**参数：** 1853 1854| 参数名 | 类型 | 必填 | 说明 | 1855| -------- | -------- | ---- | ------------------------------------------------------------ | 1856| type | string | 是 | setVolume生效的事件回调类型，支持的事件：'volumeChange'，每次调用setVolume后都会回调此事件。 | 1857| callback | Callback\<number> | 是 | setVolume生效的事件回调方法，上报生效的媒体音量。 | 1858 1859**示例：** 1860 1861```ts 1862async function test(){ 1863 let avPlayer = await media.createAVPlayer(); 1864 avPlayer.on('volumeChange', (vol: number) => { 1865 console.info('volumeChange called,and new volume is :' + vol); 1866 }); 1867} 1868``` 1869 1870## off('volumeChange')<sup>9+</sup> 1871 1872off(type: 'volumeChange', callback?: Callback\<number>): void 1873 1874取消监听setVolume生效的事件。 1875 1876**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1877 1878**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1879 1880**参数：** 1881 1882| 参数名 | 类型 | 必填 | 说明 | 1883| ------ | ------ | ---- | ------------------------------------------------------------ | 1884| type | string | 是 | setVolume生效的事件回调类型，取消注册的事件：'volumeChange'。 | 1885| callback | Callback\<number> | 否 | setVolume生效的事件回调方法，上报生效的媒体音量。<br/>从API version 12开始支持此参数。 | 1886 1887**示例：** 1888 1889```ts 1890async function test(){ 1891 let avPlayer = await media.createAVPlayer(); 1892 avPlayer.off('volumeChange'); 1893} 1894``` 1895 1896## on('endOfStream')<sup>9+</sup> 1897 1898on(type: 'endOfStream', callback: Callback\<void>): void 1899 1900监听资源播放至结尾的事件；如果用户设置[loop](#属性)=true，播放会跳转至开头重播；如果用户没有设置loop，会通过[stateChange](#onstatechange9)上报completed状态。 1901 1902**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1903 1904**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1905 1906**参数：** 1907 1908| 参数名 | 类型 | 必填 | 说明 | 1909| -------- | -------- | ---- | ------------------------------------------------------------ | 1910| type | string | 是 | 资源播放至结尾的事件回调类型，支持的事件：'endOfStream'，当播放至结尾时会上报此事件。 | 1911| callback | Callback\<void> | 是 | 资源播放至结尾的事件回调方法。 | 1912 1913**示例：** 1914 1915```ts 1916async function test(){ 1917 let avPlayer = await media.createAVPlayer(); 1918 avPlayer.on('endOfStream', () => { 1919 console.info('endOfStream called'); 1920 }); 1921} 1922``` 1923 1924## off('endOfStream')<sup>9+</sup> 1925 1926off(type: 'endOfStream', callback?: Callback\<void>): void 1927 1928取消监听资源播放至结尾的事件。 1929 1930**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1931 1932**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1933 1934**参数：** 1935 1936| 参数名 | 类型 | 必填 | 说明 | 1937| ------ | ------ | ---- | ------------------------------------------------------------ | 1938| type | string | 是 | 资源播放至结尾的事件回调类型，取消注册的事件：'endOfStream'。 | 1939| callback | Callback\<void> | 否 | 资源播放至结尾的事件回调方法。<br/>从API version 12开始支持此参数。 | 1940 1941**示例：** 1942 1943```ts 1944async function test(){ 1945 let avPlayer = await media.createAVPlayer(); 1946 avPlayer.off('endOfStream'); 1947} 1948``` 1949 1950## on('timeUpdate')<sup>9+</sup> 1951 1952on(type: 'timeUpdate', callback: Callback\<number>): void 1953 1954监听资源播放当前时间，单位为毫秒（ms），用于刷新进度条当前位置，默认间隔100ms时间上报，因用户操作(seek)产生的时间变化会立刻上报。 1955 1956注：直播场景不支持timeUpdate上报。 1957 1958**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1959 1960**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1961 1962**参数：** 1963 1964| 参数名 | 类型 | 必填 | 说明 | 1965| -------- | -------- | ---- | ---------------------------------------------- | 1966| type | string | 是 | 时间更新的回调类型，支持的事件：'timeUpdate'。 | 1967| callback | Callback\<number> | 是 | 回调函数。返回当前时间。 | 1968 1969**示例：** 1970 1971```ts 1972async function test(){ 1973 let avPlayer = await media.createAVPlayer(); 1974 avPlayer.on('timeUpdate', (time:number) => { 1975 console.info('timeUpdate called,and new time is :' + time); 1976 }); 1977} 1978``` 1979 1980## off('timeUpdate')<sup>9+</sup> 1981 1982off(type: 'timeUpdate', callback?: Callback\<number>): void 1983 1984取消监听资源播放当前时间。 1985 1986**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1987 1988**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1989 1990**参数：** 1991 1992| 参数名 | 类型 | 必填 | 说明 | 1993| ------ | ------ | ---- | -------------------------------------------------- | 1994| type | string | 是 | 时间更新的回调类型，取消注册的事件：'timeUpdate'。 | 1995| callback | Callback\<number> | 否 | 回调函数。返回当前时间。<br/>从API version 12开始支持此参数。 | 1996 1997**示例：** 1998 1999```ts 2000async function test(){ 2001 let avPlayer = await media.createAVPlayer(); 2002 avPlayer.off('timeUpdate'); 2003} 2004``` 2005 2006## on('durationUpdate')<sup>9+</sup> 2007 2008 2009on(type: 'durationUpdate', callback: Callback\<number>): void 2010 2011监听资源播放资源的时长，单位为毫秒（ms），用于刷新进度条长度，默认只在prepared上报一次，同时允许一些特殊码流刷新多次时长。 2012注：直播场景不支持durationUpdate上报。 2013 2014**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2015 2016**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2017 2018**参数：** 2019 2020| 参数名 | 类型 | 必填 | 说明 | 2021| -------- | -------- | ---- | -------------------------------------------------- | 2022| type | string | 是 | 时长更新的回调类型，支持的事件：'durationUpdate'。 | 2023| callback | Callback\<number> | 是 | 回调函数。返回资源时长。 | 2024 2025**示例：** 2026 2027```ts 2028async function test(){ 2029 let avPlayer = await media.createAVPlayer(); 2030 avPlayer.on('durationUpdate', (duration: number) => { 2031 console.info('durationUpdate called,new duration is :' + duration); 2032 }); 2033} 2034``` 2035 2036## off('durationUpdate')<sup>9+</sup> 2037 2038off(type: 'durationUpdate', callback?: Callback\<number>): void 2039 2040取消监听资源播放资源的时长。 2041 2042**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 2043 2044**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2045 2046**参数：** 2047 2048| 参数名 | 类型 | 必填 | 说明 | 2049| ------ | ------ | ---- | ------------------------------------------------------ | 2050| type | string | 是 | 时长更新的回调类型，取消注册的事件：'durationUpdate'。 | 2051| callback | Callback\<number> | 否 | 回调函数。返回资源时长。<br/>从API version 12开始支持此参数。 | 2052 2053**示例：** 2054 2055```ts 2056async function test(){ 2057 let avPlayer = await media.createAVPlayer(); 2058 avPlayer.off('durationUpdate'); 2059} 2060``` 2061 2062## on('bufferingUpdate')<sup>9+</sup> 2063 2064on(type: 'bufferingUpdate', callback: OnBufferingUpdateHandler): void 2065 2066订阅音视频缓存更新事件，仅网络播放支持该订阅事件。 2067 2068**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2069 2070**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2071 2072**参数：** 2073 2074| 参数名 | 类型 | 必填 | 说明 | 2075| -------- | -------- | ---- | ------------------------------------------------------------ | 2076| type | string | 是 | 播放缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 2077| callback | [OnBufferingUpdateHandler](arkts-apis-media-t.md#onbufferingupdatehandler12) | 是 | 播放缓存事件回调方法。 | 2078 2079**示例：** 2080 2081```ts 2082async function test(){ 2083 let avPlayer = await media.createAVPlayer(); 2084 avPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 2085 console.info('bufferingUpdate called,and infoType value is:' + infoType + ', value is :' + value); 2086 }); 2087} 2088``` 2089 2090## off('bufferingUpdate')<sup>9+</sup> 2091 2092off(type: 'bufferingUpdate', callback?: OnBufferingUpdateHandler): void 2093 2094取消监听音视频缓存更新事件。 2095 2096**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2097 2098**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2099 2100**参数：** 2101 2102| 参数名 | 类型 | 必填 | 说明 | 2103| ------ | ------ | ---- | --------------------------------------------------------- | 2104| type | string | 是 | 播放缓存事件回调类型，取消注册的事件：'bufferingUpdate'。 | 2105| callback | [OnBufferingUpdateHandler](arkts-apis-media-t.md#onbufferingupdatehandler12) | 否 | 播放缓存事件回调方法。 | 2106 2107**示例：** 2108 2109```ts 2110async function test(){ 2111 let avPlayer = await media.createAVPlayer(); 2112 avPlayer.off('bufferingUpdate'); 2113} 2114``` 2115 2116## on('startRenderFrame')<sup>9+</sup> 2117 2118on(type: 'startRenderFrame', callback: Callback\<void>): void 2119 2120订阅视频播放开始首帧渲染的更新事件，仅视频播放支持该订阅事件，该事件仅代表播放服务将第一帧画面送显示模块，实际效果依赖显示服务渲染性能。 2121 2122**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2123 2124**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2125 2126**参数：** 2127 2128| 参数名 | 类型 | 必填 | 说明 | 2129| -------- | -------- | ---- | ------------------------------------------------------------ | 2130| type | string | 是 | 视频播放开始首帧渲染事件回调类型，支持的事件：'startRenderFrame'。 | 2131| callback | Callback\<void> | 是 | 视频播放开始首帧渲染事件回调方法。 | 2132 2133**示例：** 2134 2135```ts 2136async function test(){ 2137 let avPlayer = await media.createAVPlayer(); 2138 avPlayer.on('startRenderFrame', () => { 2139 console.info('startRenderFrame called'); 2140 }); 2141} 2142``` 2143 2144## off('startRenderFrame')<sup>9+</sup> 2145 2146off(type: 'startRenderFrame', callback?: Callback\<void>): void 2147 2148取消监听视频播放开始首帧渲染的更新事件。 2149 2150**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 2151 2152**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2153 2154**参数：** 2155 2156| 参数名 | 类型 | 必填 | 说明 | 2157| ------ | ------ | ---- | ------------------------------------------------------------ | 2158| type | string | 是 | 视频播放开始首帧渲染事件回调类型，取消注册的事件：'startRenderFrame'。 | 2159| callback | Callback\<void> | 否 | 视频播放开始首帧渲染事件回调方法。<br/>从API version 12开始支持此参数。 | 2160 2161**示例：** 2162 2163```ts 2164async function test(){ 2165 let avPlayer = await media.createAVPlayer(); 2166 avPlayer.off('startRenderFrame'); 2167} 2168``` 2169 2170## on('videoSizeChange')<sup>9+</sup> 2171 2172on(type: 'videoSizeChange', callback: OnVideoSizeChangeHandler): void 2173 2174监听视频播放宽高变化事件，仅视频播放支持该订阅事件，默认只在prepared状态上报一次，但HLS协议码流会在切换分辨率时上报。 2175 2176**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2177 2178**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2179 2180**参数：** 2181 2182| 参数名 | 类型 | 必填 | 说明 | 2183| -------- | -------- | ---- | ------------------------------------------------------------ | 2184| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChange'。 | 2185| callback | [OnVideoSizeChangeHandler](arkts-apis-media-t.md#onvideosizechangehandler12) | 是 | 视频播放宽高变化事件回调方法。 | 2186 2187**示例：** 2188 2189```ts 2190async function test(){ 2191 let avPlayer = await media.createAVPlayer(); 2192 avPlayer.on('videoSizeChange', (width: number, height: number) => { 2193 console.info('videoSizeChange called,and width is:' + width + ', height is :' + height); 2194 }); 2195} 2196``` 2197 2198## off('videoSizeChange')<sup>9+</sup> 2199 2200off(type: 'videoSizeChange', callback?: OnVideoSizeChangeHandler): void 2201 2202取消监听视频播放宽高变化事件。 2203 2204**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2205 2206**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2207 2208**参数：** 2209 2210| 参数名 | 类型 | 必填 | 说明 | 2211| ------ | ------ | ---- | ------------------------------------------------------------ | 2212| type | string | 是 | 视频播放宽高变化事件回调类型，取消注册的事件：'videoSizeChange'。 | 2213| callback | [OnVideoSizeChangeHandler](arkts-apis-media-t.md#onvideosizechangehandler12) | 否 | 视频播放宽高变化事件回调方法。<br/>从API version 12开始支持此参数。 | 2214 2215**示例：** 2216 2217```ts 2218async function test(){ 2219 let avPlayer = await media.createAVPlayer(); 2220 avPlayer.off('videoSizeChange'); 2221} 2222``` 2223 2224## on('audioInterrupt')<sup>9+</sup> 2225 2226on(type: 'audioInterrupt', callback: Callback\<audio.InterruptEvent>): void 2227 2228监听音频焦点变化事件，多个音视频资源同时播放时，会根据音频焦点模型[audio.InterruptMode](../apis-audio-kit/arkts-apis-audio-e.md#interruptmode9)触发此事件。应用需根据不同焦点变化事件作相应处理。具体可参考[处理音频焦点事件](../../media/audio/audio-playback-concurrency.md)。 2229 2230**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2231 2232**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2233 2234**参数：** 2235 2236| 参数名 | 类型 | 必填 | 说明 | 2237| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 2238| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 2239| callback | Callback\<[audio.InterruptEvent](../apis-audio-kit/arkts-apis-audio-i.md#interruptevent9)> | 是 | 音频焦点变化事件回调方法。 | 2240 2241**示例：** 2242 2243```ts 2244import { audio } from '@kit.AudioKit'; 2245 2246async function test(){ 2247 let avPlayer = await media.createAVPlayer(); 2248 avPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 2249 console.info('audioInterrupt called,and InterruptEvent info is:' + info); 2250 }); 2251} 2252``` 2253 2254## off('audioInterrupt')<sup>9+</sup> 2255 2256off(type: 'audioInterrupt', callback?: Callback<audio.InterruptEvent>): void 2257 2258取消监听音频焦点变化事件。 2259 2260**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2261 2262**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2263 2264**参数：** 2265 2266| 参数名 | 类型 | 必填 | 说明 | 2267| ------ | ------ | ---- | ------------------------------------------------------------ | 2268| type | string | 是 | 音频焦点变化事件回调类型，取消注册的事件：'audioInterrupt'。 | 2269| callback | Callback\<[audio.InterruptEvent](../apis-audio-kit/arkts-apis-audio-i.md#interruptevent9)> | 否 | 音频焦点变化事件回调方法。<br/>从API version 12开始支持此参数。 | 2270 2271**示例：** 2272 2273```ts 2274async function test(){ 2275 let avPlayer = await media.createAVPlayer(); 2276 avPlayer.off('audioInterrupt'); 2277} 2278``` 2279 2280## on('audioOutputDeviceChangeWithInfo')<sup>11+</sup> 2281 2282on(type: 'audioOutputDeviceChangeWithInfo', callback: Callback\<audio.AudioStreamDeviceChangeInfo>): void 2283 2284订阅监听音频流输出设备变化及原因，使用callback方式返回结果。 2285 2286在订阅此监听时，建议参考[响应音频流输出设备变更](../../media/audio/audio-output-device-change.md)自行实现设备连接或者断开时的播放器行为。 2287 2288**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2289 2290**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2291 2292**参数：** 2293 2294| 参数名 | 类型 | 必填 | 说明 | 2295| :------- | :------------------------- | :--- | :------------------------------------------ | 2296| type | string | 是 | 事件回调类型，支持的事件为：'audioOutputDeviceChangeWithInfo'。 | 2297| callback | Callback\<[audio.AudioStreamDeviceChangeInfo](../apis-audio-kit/arkts-apis-audio-i.md#audiostreamdevicechangeinfo11)> | 是 | 回调函数，返回当前音频流的输出设备描述信息及变化原因。 | 2298 2299**错误码：** 2300 2301| 错误码ID | 错误信息 | 2302| -------- | ------------------------------------------ | 2303| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2304 2305**示例：** 2306 2307```ts 2308import { audio } from '@kit.AudioKit'; 2309 2310async function test(){ 2311 let avPlayer = await media.createAVPlayer(); 2312 avPlayer.on('audioOutputDeviceChangeWithInfo', (data: audio.AudioStreamDeviceChangeInfo) => { 2313 console.info(`${JSON.stringify(data)}`); 2314 }); 2315} 2316``` 2317 2318## off('audioOutputDeviceChangeWithInfo')<sup>11+</sup> 2319 2320off(type: 'audioOutputDeviceChangeWithInfo', callback?: Callback\<audio.AudioStreamDeviceChangeInfo>): void 2321 2322取消订阅监听音频流输出设备变化及原因，使用callback方式返回结果。 2323 2324**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2325 2326**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2327 2328**参数：** 2329 2330| 参数名 | 类型 | 必填 | 说明 | 2331| :------- | :------------------------- | :--- | :------------------------------------------ | 2332| type | string | 是 | 事件回调类型，支持的事件为：'audioOutputDeviceChangeWithInfo'。 | 2333| callback | Callback\<[audio.AudioStreamDeviceChangeInfo](../apis-audio-kit/arkts-apis-audio-i.md#audiostreamdevicechangeinfo11)> | 否 | 回调函数，返回当前音频流的输出设备描述信息及变化原因。 | 2334 2335**错误码：** 2336 2337| 错误码ID | 错误信息 | 2338| -------- | ------------------------------------------ | 2339| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2340 2341**示例：** 2342 2343```ts 2344async function test(){ 2345 let avPlayer = await media.createAVPlayer(); 2346 avPlayer.off('audioOutputDeviceChangeWithInfo'); 2347} 2348``` 2349 2350## addSubtitleFromFd<sup>12+</sup> 2351 2352addSubtitleFromFd(fd: number, offset?: number, length?: number): Promise\<void> 2353 2354依据fd为视频添加外挂字幕，当前仅支持与视频资源同时设置（在avplayer设置fdSrc视频资源后设置外挂字幕）。使用Promise方式返回结果。 2355 2356**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2357 2358**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2359 2360**参数：** 2361 2362| 参数名 | 类型 | 必填 | 说明 | 2363| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 2364| fd | number | 是 | 资源句柄，通过[resourceManager.getRawFd](../apis-localization-kit/js-apis-resource-manager.md#getrawfd9)获取。 | 2365| offset | number | 否 | 资源偏移量，需要基于预置资源的信息输入，非法值会造成字幕频资源解析错误，默认值:0。 | 2366| length | number | 否 | 资源长度，默认值为文件中从偏移量开始的剩余字节，需要基于预置资源的信息输入，非法值会造成字幕频资源解析错误，默认值:0。 | 2367 2368**返回值：** 2369 2370| 类型 | 说明 | 2371| -------------- | ------------------------------------------ | 2372| Promise\<void> | 添加外挂字幕addSubtitleFromFd方法的Promise返回值。 | 2373 2374**错误码：** 2375 2376| 错误码ID | 错误信息 | 2377| -------- | ------------------------------------------ | 2378| 401 | The parameter check failed. Return by promise. | 2379| 5400102 | Operation not allowed. Return by promise. | 2380 2381**示例：** 2382 2383<!--code_no_check--> 2384```ts 2385import { common } from '@kit.AbilityKit' 2386 2387let avPlayer = await media.createAVPlayer(); 2388let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2389let fileDescriptor = await context.resourceManager.getRawFd('xxx.srt'); 2390 2391avPlayer.addSubtitleFromFd(fileDescriptor.fd, fileDescriptor.offset, fileDescriptor.length); 2392``` 2393 2394## addSubtitleFromUrl<sup>12+</sup> 2395 2396addSubtitleFromUrl(url: string): Promise\<void> 2397 2398依据url为视频添加外挂字幕，当前仅支持与视频资源同时设置（在avplayer设置fdSrc视频资源后设置外挂字幕）。使用Promise方式返回结果。 2399 2400**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2401 2402**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2403 2404**参数：** 2405 2406| 参数名 | 类型 | 必填 | 说明 | 2407| ------ | ------ | ---- | ------------------------------------------------------------ | 2408| url | string | 是 | 外挂字幕文件地址。 | 2409 2410**返回值：** 2411 2412| 类型 | 说明 | 2413| -------------- | ------------------------------------------ | 2414| Promise\<void> | 添加外挂字幕addSubtitleFromUrl方法的Promise返回值。 | 2415 2416**错误码：** 2417 2418| 错误码ID | 错误信息 | 2419| -------- | ------------------------------------------ | 2420| 401 | The parameter check failed. Return by promise. | 2421| 5400102 | Operation not allowed. Return by promise. | 2422 2423**示例：** 2424 2425<!--code_no_check--> 2426```ts 2427async function test(){ 2428 let fdUrl:string = 'http://xxx.xxx.xxx/xx/index.srt'; 2429 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 2430 avPlayer.addSubtitleFromUrl(fdUrl); 2431} 2432``` 2433 2434## on('subtitleUpdate')<sup>12+</sup> 2435 2436on(type: 'subtitleUpdate', callback: Callback\<SubtitleInfo>): void 2437 2438订阅获取外挂字幕的事件，当有外挂字幕时，会通过订阅的回调方法通知用户。用户只能订阅一个外挂字幕事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2439 2440**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2441 2442**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2443 2444**参数：** 2445 2446| 参数名 | 类型 | 必填 | 说明 | 2447| -------- | -------- | ---- | ------------------------------------------------------------ | 2448| type | string | 是 | 事件回调类型，支持的事件为：'subtitleUpdate'。 | 2449| callback | Callback\<[SubtitleInfo](arkts-apis-media-i.md#subtitleinfo12)> | 是 | 外挂字幕事件回调方法。 | 2450 2451**示例：** 2452 2453```ts 2454async function test(){ 2455 let avPlayer = await media.createAVPlayer(); 2456 avPlayer.on('subtitleUpdate', async (info: media.SubtitleInfo) => { 2457 if (info) { 2458 let text = (!info.text) ? '' : info.text 2459 let startTime = (!info.startTime) ? 0 : info.startTime 2460 let duration = (!info.duration) ? 0 : info.duration 2461 console.info('subtitleUpdate info: text=' + text + ' startTime=' + startTime +' duration=' + duration); 2462 } else { 2463 console.info('subtitleUpdate info is null'); 2464 } 2465 }); 2466} 2467``` 2468 2469## off('subtitleUpdate')<sup>12+</sup> 2470 2471off(type: 'subtitleUpdate', callback?: Callback\<SubtitleInfo>): void 2472 2473取消订阅获取外挂字幕的事件。 2474 2475**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2476 2477**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2478 2479**参数：** 2480 2481| 参数名 | 类型 | 必填 | 说明 | 2482| -------- | -------- | ---- | ------------------------------------------------------------ | 2483| type | string | 是 | 事件回调类型，支持的事件为：'subtitleUpdate'。 | 2484| callback | function | 否 | 取消外挂字幕事件的回调方法。 | 2485 2486**示例：** 2487 2488```ts 2489async function test(){ 2490 let avPlayer = await media.createAVPlayer(); 2491 avPlayer.off('subtitleUpdate'); 2492} 2493``` 2494 2495## on('trackChange')<sup>12+</sup> 2496 2497on(type: 'trackChange', callback: OnTrackChangeHandler): void 2498 2499订阅获取轨道变更的事件，当播放的轨道变更时，会通过订阅的回调方法通知用户。用户只能订阅一个轨道变更事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2500 2501**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2502 2503**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2504 2505**参数：** 2506 2507| 参数名 | 类型 | 必填 | 说明 | 2508| -------- | -------- | ---- | ------------------------------------------------------------ | 2509| type | string | 是 | 事件回调类型，支持的事件为：'trackChange'。 | 2510| callback | [OnTrackChangeHandler](arkts-apis-media-t.md#ontrackchangehandler12) | 是 | 轨道变更事件回调方法。 | 2511 2512**示例：** 2513 2514```ts 2515async function test(){ 2516 let avPlayer = await media.createAVPlayer(); 2517 avPlayer.on('trackChange', (index: number, isSelect: boolean) => { 2518 console.info('trackChange info: index=' + index + ' isSelect=' + isSelect); 2519 }); 2520} 2521``` 2522 2523## off('trackChange')<sup>12+</sup> 2524 2525off(type: 'trackChange', callback?: OnTrackChangeHandler): void 2526 2527取消订阅获取轨道变更的事件。 2528 2529**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2530 2531**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2532 2533**参数：** 2534 2535| 参数名 | 类型 | 必填 | 说明 | 2536| -------- | -------- | ---- | ------------------------------------------------------------ | 2537| type | string | 是 | 事件回调类型，支持的事件为：'trackChange'。 | 2538| callback | [OnTrackChangeHandler](arkts-apis-media-t.md#ontrackchangehandler12) | 否 | 取消轨道变更事件的回调方法。 | 2539 2540**示例：** 2541 2542```ts 2543async function test(){ 2544 let avPlayer = await media.createAVPlayer(); 2545 avPlayer.off('trackChange'); 2546} 2547``` 2548 2549## on('trackInfoUpdate')<sup>12+</sup> 2550 2551on(type: 'trackInfoUpdate', callback: Callback\<Array\<MediaDescription>>): void 2552 2553订阅获取轨道信息更新的事件，当播放的轨道有更新时，会通过订阅的回调方法通知用户。用户只能订阅一个轨道变更事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2554 2555**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2556 2557**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2558 2559**参数：** 2560 2561| 参数名 | 类型 | 必填 | 说明 | 2562| -------- | -------- | ---- | ------------------------------------------------------------ | 2563| type | string | 是 | 事件回调类型，支持的事件为：'trackInfoUpdate'。 | 2564| callback | Callback\<Array\<[MediaDescription](arkts-apis-media-i.md#mediadescription8)>> | 是 | 轨道信息更新事件回调方法。 | 2565 2566**示例：** 2567 2568```ts 2569async function test(){ 2570 let avPlayer = await media.createAVPlayer(); 2571 avPlayer.on('trackInfoUpdate', (info: Array<media.MediaDescription>) => { 2572 if (info) { 2573 for (let i = 0; i < info.length; i++) { 2574 let propertyIndex: Object = info[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 2575 let propertyType: Object = info[i][media.MediaDescriptionKey.MD_KEY_TRACK_TYPE]; 2576 console.info('track info: index=' + propertyIndex + ' tracktype=' + propertyType); 2577 } 2578 } else { 2579 console.info('track info is null'); 2580 } 2581 }); 2582} 2583``` 2584 2585## off('trackInfoUpdate')<sup>12+</sup> 2586 2587off(type: 'trackInfoUpdate', callback?: Callback\<Array\<MediaDescription>>): void 2588 2589取消订阅获取轨道变更的事件。 2590 2591**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2592 2593**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2594 2595**参数：** 2596 2597| 参数名 | 类型 | 必填 | 说明 | 2598| -------- | -------- | ---- | ------------------------------------------------------------ | 2599| type | string | 是 | 事件回调类型，支持的事件为：'trackInfoUpdate'。 | 2600| callback | Callback\<Array\<[MediaDescription](arkts-apis-media-i.md#mediadescription8)>> | 否 | 取消轨道信息更新事件的回调方法。 | 2601 2602**示例：** 2603 2604```ts 2605async function test(){ 2606 let avPlayer = await media.createAVPlayer(); 2607 avPlayer.off('trackInfoUpdate'); 2608} 2609``` 2610 2611## on('amplitudeUpdate')<sup>13+</sup> 2612 2613on(type: 'amplitudeUpdate', callback: Callback\<Array\<number>>): void 2614 2615订阅音频最大电平值，音频资源播放时定时上报。 2616 2617**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2618 2619**参数：** 2620 2621| 参数名 | 类型 | 必填 | 说明 | 2622| -------- | -------- | ---- | ------------------------------------------------------------ | 2623| type | string | 是 | 事件回调类型，支持的事件为：'amplitudeUpdate'。 | 2624| callback | Callback\<Array\<number>> | 是 | 音频最大电平值更新事件回调方法。 | 2625 2626**示例：** 2627 2628```ts 2629async function test(){ 2630 let avPlayer = await media.createAVPlayer(); 2631 avPlayer.on('amplitudeUpdate', (value: Array<number>) => { 2632 console.info(`amplitudeUpdate called,and amplitudeUpdate = ${value}`); 2633 }); 2634} 2635``` 2636 2637## off('amplitudeUpdate')<sup>13+</sup> 2638 2639off(type: 'amplitudeUpdate', callback?: Callback\<Array\<number>>): void 2640 2641取消订阅获取音频最大电平值事件。 2642 2643**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2644 2645**参数：** 2646 2647| 参数名 | 类型 | 必填 | 说明 | 2648| ------ | ------ | ---- | ------------------------------------------------------------ | 2649| type | string | 是 | 事件回调类型，支持的事件为：'amplitudeUpdate'。 | 2650| callback | Callback\<Array\<number>> | 否 | 取消音频最大电平值更新事件回调方法。 | 2651 2652**示例：** 2653 2654```ts 2655async function test(){ 2656 let avPlayer = await media.createAVPlayer(); 2657 avPlayer.off('amplitudeUpdate'); 2658} 2659``` 2660 2661## on('seiMessageReceived')<sup>18+</sup> 2662 2663on(type: 'seiMessageReceived', payloadTypes: Array\<number>, callback: OnSeiMessageHandle): void 2664 2665订阅获取SEI信息事件，仅适用于HTTP-FLV直播，视频流中包含SEI信息时上报。需在prepare之前订阅，当用户重复订阅时，以最后一次订阅的回调接口为准。 2666 2667**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2668 2669**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2670 2671**参数：** 2672 2673| 参数名 | 类型 | 必填 | 说明 | 2674| -------- | -------- | ---- | ------------------------------------------------------------ | 2675| type | string | 是 | 事件回调类型，支持的事件为：'seiMessageReceived'。 | 2676| payloadTypes | Array\<number> | 是 | SEI信息的订阅负载类型数组。当前仅支持负载类型为5，即payloadType = 5。| 2677| callback | [OnSeiMessageHandle](arkts-apis-media-t.md#onseimessagehandle18) | 是 | 用于监听SEI信息事件的回调函数，接收订阅的负载类型。 | 2678 2679**示例：** 2680 2681```ts 2682import { util } from '@kit.ArkTS'; 2683 2684async function test(){ 2685 let avPlayer = await media.createAVPlayer(); 2686 2687 avPlayer.on('seiMessageReceived', [5], (messages: Array<media.SeiMessage>, playbackPosition?: number) => 2688 { 2689 console.info('seiMessageReceived playbackPosition ' + playbackPosition); 2690 2691 for (let key = 0; key < messages.length; key++) { 2692 console.info('seiMessageReceived messages payloadType ' + messages[key].payloadType + ' payload size ' + messages[key].payload.byteLength); 2693 2694 let textDecoder = util.TextDecoder.create("utf-8",{ignoreBOM: true}); 2695 let ab = messages[key]?.payload?.slice(16, messages[key].payload.byteLength); 2696 let result: Uint8Array = new Uint8Array(ab); 2697 let retStr: string = textDecoder.decodeToString(result); 2698 console.info('seiMessageReceived messages payload ' + retStr); 2699 } 2700 }); 2701} 2702``` 2703 2704## off('seiMessageReceived')<sup>18+</sup> 2705 2706off(type: 'seiMessageReceived', payloadTypes?: Array\<number>, callback?: OnSeiMessageHandle): void 2707 2708取消订阅获取SEI信息事件。 2709 2710**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2711 2712**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2713 2714**参数：** 2715 2716| 参数名 | 类型 | 必填 | 说明 | 2717| ------ | ------ | ---- | ------------------------------------------------------------ | 2718| type | string | 是 | 事件回调类型，支持的事件为：'seiMessageReceived'。 | 2719| payloadTypes | Array\<number> | 否 | SEI信息的订阅负载类型。 | 2720| callback | [OnSeiMessageHandle](arkts-apis-media-t.md#onseimessagehandle18) | 否 | 用于监听SEI信息事件的回调函数，接收订阅的负载类型。 | 2721 2722**示例：** 2723 2724```ts 2725async function test(){ 2726 let avPlayer = await media.createAVPlayer(); 2727 avPlayer.off('seiMessageReceived'); 2728} 2729``` 2730 2731## setSuperResolution<sup>18+</sup> 2732 2733setSuperResolution(enabled: boolean) : Promise\<void> 2734 2735动态开启/关闭超分算法，可以在 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' 状态调用。使用Promise方式返回结果。 2736 2737在调用[prepare()](#prepare9)前先通过[PlaybackStrategy](arkts-apis-media-i.md#playbackstrategy12)使能超分。 2738 2739**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2740 2741**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2742 2743**参数：** 2744 2745| 参数名 | 类型 | 必填 | 说明 | 2746| ------ | ------ | ---- | ------------------------------------------------------------ | 2747| enabled | boolean | 是 | 表示是否开启超分。true表示开启超分，false表示关闭超分。 | 2748 2749**返回值：** 2750 2751| 类型 | 说明 | 2752| -------------- | ------------------------------------------ | 2753| Promise\<void> | 开启/关闭超分setSuperResolution方法的Promise返回值。 | 2754 2755**错误码：** 2756 2757以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 2758 2759| 错误码ID | 错误信息 | 2760| -------- | ------------------------------------------ | 2761| 5400102 | Operation not allowed. Return by promise. | 2762| 5410003 | Super-resolution not supported. Return by promise. | 2763| 5410004 | Missing enable super-resolution feature in [PlaybackStrategy](arkts-apis-media-i.md#playbackstrategy12). Return by promise. | 2764 2765**示例：** 2766 2767```ts 2768async function test(){ 2769 let avPlayer = await media.createAVPlayer(); 2770 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至initialized/prepared/playing/paused/completed/stopped状态后才能调用。 2771 avPlayer.setSuperResolution(true); 2772} 2773``` 2774 2775## setVideoWindowSize<sup>18+</sup> 2776 2777setVideoWindowSize(width: number, height: number) : Promise\<void> 2778 2779动态设置超分算法的输出分辨率，可以在 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' 状态调用。使用Promise方式返回结果。输入参数须在 320x320 ~ 1920x1080 范围内，单位为像素。 2780 2781在调用[prepare()](#prepare9)前先通过[PlaybackStrategy](arkts-apis-media-i.md#playbackstrategy12)使能超分。 2782 2783**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2784 2785**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2786 2787**参数：** 2788 2789| 参数名 | 类型 | 必填 | 说明 | 2790| ------ | ------ | ---- | ------------------------------------------------------------ | 2791| width | number | 是 | 超分算法的目标输出视频宽度，取值范围为[320-1920]，单位为像素。 | 2792| height | number | 是 | 超分算法的目标输出视频高度，取值范围为[320-1080]，单位为像素。 | 2793 2794**返回值：** 2795 2796| 类型 | 说明 | 2797| -------------- | ------------------------------------------ | 2798| Promise\<void> | 配置超分目标输出分辨率setVideoWindowSize方法的Promise返回值。 | 2799 2800**错误码：** 2801 2802以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体错误码](errorcode-media.md)。 2803 2804| 错误码ID | 错误信息 | 2805| -------- | ------------------------------------------ | 2806| 401 | Parameter error. Return by promise. | 2807| 5400102 | Operation not allowed. Return by promise. | 2808| 5410003 | Super-resolution not supported. Return by promise. | 2809| 5410004 | Missing enable super-resolution feature in [PlaybackStrategy](arkts-apis-media-i.md#playbackstrategy12). Return by promise. | 2810 2811**示例：** 2812 2813```ts 2814async function test(){ 2815 let avPlayer = await media.createAVPlayer(); 2816 // 此处仅为示意，实际开发中需要在stateChange事件成功触发至initialized/prepared/playing/paused/completed/stopped状态后才能调用。 2817 avPlayer.setVideoWindowSize(1920, 1080); 2818} 2819``` 2820 2821## on('superResolutionChanged')<sup>18+</sup> 2822 2823on(type:'superResolutionChanged', callback: OnSuperResolutionChanged): void 2824 2825订阅监听超分算法开启/关闭事件。 2826 2827**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2828 2829**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2830 2831**参数：** 2832 2833| 参数名 | 类型 | 必填 | 说明 | 2834| -------- | -------- | ---- | ------------------------------------------------------------ | 2835| type | string | 是 | 事件回调类型，支持的事件为：'superResolutionChanged'，当超分算法开启/关闭状态变化时，触发该事件。 | 2836| callback | [OnSuperResolutionChanged](arkts-apis-media-t.md#onsuperresolutionchanged-18) | 是 | 超分开关事件回调方法。 | 2837 2838**示例：** 2839 2840```ts 2841async function test(){ 2842 let avPlayer = await media.createAVPlayer(); 2843 avPlayer.on('superResolutionChanged', (enabled: boolean) => { 2844 console.info('superResolutionChanged called, and enabled is:' + enabled); 2845 }); 2846} 2847``` 2848 2849## off('superResolutionChanged')<sup>18+</sup> 2850 2851off(type:'superResolutionChanged', callback?: OnSuperResolutionChanged): void 2852 2853取消监听超分算法开启/关闭事件。 2854 2855**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2856 2857**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2858 2859**参数：** 2860 2861| 参数名 | 类型 | 必填 | 说明 | 2862| -------- | -------- | ---- | ------------------------------------------------------------ | 2863| type | string | 是 | 事件回调类型，支持的事件为：'superResolutionChanged'，当超分算法开启/关闭状态变化时，触发该事件。 | 2864| callback | [OnSuperResolutionChanged](arkts-apis-media-t.md#onsuperresolutionchanged-18) | 否 | 超分开关事件回调方法。 | 2865 2866**示例：** 2867 2868```ts 2869async function test(){ 2870 let avPlayer = await media.createAVPlayer(); 2871 avPlayer.off('superResolutionChanged'); 2872} 2873``` 2874
